[17.0.0.3 and later]

MicroProfile 구성 API

MicroProfile 구성 API는 애플리케이션이 서로 다른 소스에서 구성 정보를 검색할 수 있는 단일 API로 사용할 수 있습니다.

MicroProfile 구성 API를 사용하는 경우:
  • 복수의 구성 소스를 단일 구성으로 병합하고 하나의 API에서 액세스할 수 있습니다.
  • 구성 특성 값을 더 높은 우선순위를 보유하도록 지정된 구성 소스의 값으로 대체할 수 있습니다.
  • 값을 이름 지정된 특성 파일, 시스템 환경 변수 또는 Java™ 시스템 특성에 저장할 수 있습니다.
  • 애플리케이션의 현재 컨텍스트 ClassLoader 또는 사용자가 제공한 ClassLoader 중 하나인 Java ClassLoader를 사용하여 ConfigSource 자원을 로드합니다.
  • ConfigSource 인터페이스의 사용자 구현을 등록하여 값을 제공할 수 있습니다.
  • 기본 제공 또는 사용자 정의 유형 변환기를 사용하여 특정 Java 클래스의 유형 지정된 오브젝트 또는 문자열로 값을 검색할 수 있습니다.
  • Java ServiceLoader 패턴을 사용하여 ConfigSourceConverter 구현을 검색할 수 있습니다.
  • Java CDI(Context and Dependency Injection)를 사용하여 기본요소, 표준 유형 또는 사용자 제공 유형의 구성 특성 값을 직접 삽입할 수 있습니다.

구성 인젝션

MicroProfile 구성 API는 기본 구성 소스 및 Java ServiceLoader configsources에서 로드하는 구성 소스를 수집하며, 이 주제의 뒷부분에서 자세히 설명합니다. Java CDI(Contexts and Dependency Injection)를 사용하여 구성 오브젝트를 애플리케이션에 직접 삽입할 수 있습니다.

@Inject
Config config;
String appName = config.getValue(“APP_NAME”, String.class);

또한 단일 구성 특성 값을 삽입할 수 있습니다.

@Inject
@ConfigProperty
String PROPERTY_NAME1;

이러한 특성은 표준 Java 특성과 마찬가지로 원래 형태의 문자열로 표시됩니다. 시스템은 구성 소스에 대한 기본 설정을 사용하여 classname의 이름에서 구성 특성의 이름을 얻습니다. 여기서 첫 번째 문자는 소문자이고, 그 다음에 변수 이름이 추가되며, 구분 기호는 마침표입니다. 예를 들어 ClassA라는 이름의 클래스에 이전 스니펫이 있는 경우 분석되는 특성 이름은 classA.PROPERTY_NAME1입니다.

@Inject
@ConfigProperty(name="PROPERTY_NAME2")
String propertyTwo;

이 코드 스니펫은 구성 소스에서 필수 특성인 PROPERTY_NAME2를 검색하기 위한 것입니다. 해당 특성이 존재하지 않는 경우 DeploymentException으로 처리됩니다.

구성된 모든 configsources에 특성이 존재하지 않는 경우 defaultValue 매개변수를 사용하여 기본값을 지정하십시오.
@inject
@ConfigProperty(name="myName", defaultValue="Bob")
String name;
이 코드 스니펫은 구성된 configsources에서 myName 특성을 검색합니다. 해당 특성이 정의되어 있지 않은 경우 name 변수에 Bob이 지정됩니다.

프로그래밍 방식 구성 검색

MicroProfile 구성 API에서는 메소드 호출을 사용하여 구성 특성을 검색하는 인터페이스도 제공됩니다. 이 검색은 두 가지 방법(기본 설정을 사용하는 간편한 구성 제공자 클래스 및 완전히 사용자 정의할 수 있는 구성 빌더 클래스)으로 완료할 수 있습니다.

ConfigProvider 클래스

구성을 사용하는 가장 간단한 방법은 ConfigProvider 클래스에서 정적 메소드를 사용하는 것입니다. 이 API는 기본 구성 소스 및 Java® ServiceLoader configsources에서 로드하는 구성 소스를 수집합니다.

Config config = ConfigProvider.getConfig();
String appName = config.getValue(“APP_NAME”, String.class);

ConfigBuilder 클래스

직접 사용자 정의하는 방식으로 구성을 작성하려는 사용자의 경우 구성을 생성하기 전에 구성 빌더 API를 사용하여 다양한 옵션을 설정할 수 있습니다. 이 예제에서는 빌더 패턴을 사용하여 이전 예제의 구성과 동일한 구성을 빌드합니다.

ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Config config = builder.build();

builder.addDefaultSources()를 호출하면 ConfigProvider에서 구성을 빌드하기 위해 사용하는 기본 소스와 동일한 세트가 추가됩니다. 다른 구성 소스를 추가할 수도 있습니다.

구성 소스

구성 특성은 애플리케이션에서 등록하거나 Java ServiceLoader 패턴을 사용하여 로드한 사용자 클래스 및 특성 파일을 포함하여 여러 위치에서 제공받을 수 있습니다.

기본 소스

ConfigProvider 인터페이스와는 달리 ConfigBuilder 인터페이스의 경우 초기에는 구성 특성 소스 세트가 비어 있습니다. 기본 소스를 추가하면 다음 내용이 적용됩니다.

  1. 구성에 프로세스 환경 변수가 포함됩니다. Liberty는 Java System.getenv() 메소드에 호스트 프로세스 환경 변수를 표시한 후 서버에 있는 server.env 파일의 특성을 추가합니다. 이렇게 하면 MicroProfile 구성 API에서 해당 변수를 사용할 수 있게 됩니다.
  2. 구성에 System.getProperties() 방식으로 사용 가능한 Java 시스템 특성이 포함됩니다. Liberty는 서버에 있는 bootstrap.propertiesjvm.options 파일의 특성을 Java 시스템 특성에 추가합니다.
  3. resourceNameMETA-INF/microprofile-config.properties인 애플리케이션 ThreadContextClassLoader 클래스 경로에서 파일이 로드됩니다. 이러한 특성 파일 내에서는 표준 Java 특성 파일에서 사용하는 것과 동일한 구문을 사용하여 특성을 저장합니다. Liberty 애플리케이션의 경우 META-INF 디렉토리 위치는 JAR의 루트에 있는 서브디렉토리이거나 WAR 파일에 대한 WEB-INF\classes\META-INF\ 디렉토리일 수 있으며 또는 EAR의 lib 디렉토리에 있는 JAR 또는 서버 레벨 공유 라이브러리 JAR에 있을 수 있습니다. 사용되는 ClassLoader 및 클래스 경로는 빌더의 forClassLoader 메소드를 사용하여 변경할 수 있습니다.

사용자 제공 ConfigSources

org.eclipse.microprofile.config.spi.ConfigSource를 구현하는 사용자 클래스를 ConfigBuilder에 등록할 수 있습니다. 이 방식으로 이 사용자 클래스는 빌더가 생성하는 나중의 구성에 포함됩니다.

MySource source = new MySource();
builder.withSources(source);

ConfigSource의 Java ServiceLoader 로드

또한 Java ServiceLoader 패턴을 사용하여 사용자 정의 구성 소스 오브젝트를 찾을 수 있습니다. 전체 패키지의 완전한 클래스 이름이 ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource 형식의 파일에 나열되어 있을 경우 ConfigSource 인터페이스를 구현하는 사용자 클래스가 로드됩니다.

변환기

MicroProfile 구성 API는 원하는 특성 오브젝트의 유형을 가져오는 포괄적인 메소드가 포함된 Java 오브젝트 유형으로 특성을 검색할 수도 있습니다. 이 메소드는 기본 제공 또는 사용자 제공 변환기가 포함된 모든 유형에 대해 작동합니다. 예를 들어 이전 예제의 코드를 다음과 같이 기본 제공 문자열 변환기를 사용하도록 작성할 수 있습니다.

appName = config.getOptionalValue(“APP_NAME”, String.class).orElse(“MicroDemo”);

기본 제공 변환기

MicroProfile 구성 API에는 다음 유형의 기본 제공 변환기가 포함되어 있습니다. boolean, Boolean, int, Integer, long, Long, float, Float, double, Double, Duration, LocalTime, LocalDate, LocalDateTime, OffsetDateTime, OffsetTime, InstantURL

이러한 유형의 변수는 포괄적인 getValue 호출을 사용하여 직접 삽입하거나 검색할 수 있습니다. 단일 문자열 매개변수를 가져와서 관련 valueof, parse 또는 생성자 메소드를 사용하여 특성의 문자열 값을 유형으로 변환할 수 있습니다.

사용자 정의 변환기

org.eclipse.microprofile.config.spi.Converter<T> 인터페이스를 구현하는 사용자 정의 변환기는 ConfigBuilder API를 사용하여 구성에 등록하고 사용할 수 있습니다.

ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Converter<CustomProperty> converter = new MyConverter(); 
builder.withConverters(converter);
Config config = builder.build();
Optional<CustomProperty> opt = config.getOptionalValue(“PROPOBJ”, CustomProperty.class);
withConverters 메소드는 리플렉션을 사용하여 변환기의 대상 유형을 판별합니다. Java Lambda 코드는 현재 리플렉션 API에 대한 충분한 특정 유형 정보를 제공하고 있지 않습니다. 따라서 사용자 정의 변환기의 경우 Converter<T> 인터페이스를 명시적으로 구현하는 코드가 필요합니다.

변환기 우선순위

동일한 유형의 변환기가 여러 개 존재하는 경우 @Priority 어노테이션을 사용하여 사용되는 변환기를 제어할 수 있습니다. 이 방법을 사용하여 애플리케이션 라이프사이클의 후반에 변환기 구현을 대체할 수 있습니다. 변환기는 동일한 유형의 우선순위가 더 낮은 다른 모든 변환기를 대체합니다.

import javax.annotation.Priority;
import org.eclipse.microprofile.config.spi.Converter;
@Priority(200)
publicclass StringPrefixConverter implements Converter<String> {
    @Override
    public String convert(String value) throws IllegalArgumentException {
        return"Converted:" + value;
    }
}

@Priority 어노테이션을 사용하지 않을 경우 변환기에 대한 기본 우선순위는 100입니다.

변환기에 대한 Java ServiceLoader 지원

또한 패키지에 규정된 클래스 이름이 ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converter 양식의 서비스 파일에 표시되는 경우 Java ServiceLoader 패턴을 사용하여 사용자 정의 변환기를 찾을 수 있습니다.

MicroProfile 구성 API 구현에 포함된 기본 변환기와 Java ServiceLoader 패턴을 사용하여 검색되는 변환기는 모든 구성에서 사용할 수 있습니다.

특성 값 대체

둘 이상의 구성 소스를 사용하는 경우 모든 소스의 특성이 함께 수집되어 애플리케이션에서 단일 세트로 액세스됩니다. 각 구성 소스에는 서수 값이 지정됩니다. 둘 이상의 소스에 특성이 표시되는 경우 서수 값이 가장 높은 소스의 특성 값이 우선순위가 높으며, 해당 특성 값이 애플리케이션에 리턴됩니다. 기본 서수 값은 다음과 같습니다.

  • 시스템 특성 - 400
  • 환경 변수 - 300
  • /META-INF/microprofile-config.properties - 100
  • 사용자 정의 ConfigSource 오브젝트 - ConfigSourcegetOrdinal 결과
참고: 나열되는 처음 세 개의 서수 값은 해당 값이 적용되는 구성 소스에 있는 config_ordinal 특성을 사용하여 대체할 수 있습니다.

동일한 특성을 제공하는 두 개의 ConfigSources에서 서수가 동일한 경우 문자열 비교 규칙에 따라 비교하기 위해 ConfigSources ID를 사용합니다.

일반적으로 개발 라이프사이클의 초반에 설정되는 소스는 서수 및 우선순위가 낮습니다. 이는 애플리케이션 라이프사이클의 후반(예: 애플리케이션 어셈블리 또는 설치 중)에 기존 특성 값을 대체하는 기능을 지원하기 위한 것입니다.

특성 값 대체

잘 설계된 마이크로서비스 애플리케이션은 개별 애플리케이션을 다시 시작하는 중에도 가용성을 유지하지만 애플리케이션을 다시 시작하지 않고도 애플리케이션에서 구성 값에 대한 변경사항을 사용할 수 있어야 합니다. 등록된 ConfigSource 오브젝트가 제공하는 구성의 특성 값은 ConfigSources가 제공하는 업데이트된 값으로 새로 고칠 수 있습니다. ConfigSources를 참조하고 값을 새로 고치는 빈도는 microprofile.config.refresh.rate Java 시스템 특성에 의해 제어됩니다. 사용되는 단위는 밀리초이고 기본값은 500입니다. 이는 기본적으로 ConfigSources 제공 값이 약 0.5초 내에 컨트리뷰션되는 모든 구성에 피드됨을 의미합니다.

microprofile-config.properties 파일과 같은 비프로그래밍 방식의 구성 소스는 초기 구성 구축 이후에 동적으로 다시 읽어들이지 않습니다.

특성을 삽입한 후 값의 업데이트가 표시되도록 하기 위해 ConfigValue 오브젝트를 사용할 수 있습니다. 여기에는 구성 특성 값 및 구성 특성 값의 Optional<T> 모두에 대해 Getter가 호출될 때마다 현재 값을 리턴하는 Getter가 있습니다. 예:

@Inject
@ConfigProperty(name="propertyName3")
Provider<MyClass> propertyName3;
MyClass mc = propertyName3.get();

또한 적절한 변환기가 존재하는 경우 ConfigValue 클래스가 포괄적이며 특정 유형의 특성을 검색하기 위해 사용할 수 있음을 확인할 수 있습니다.

구성 캐싱

ConfigProvider는 효율적인 지원을 위해 해당 ClassLoader로 식별되는 특정 애플리케이션(또는 모듈)에 대한 getConfig 메소드에서 리턴하는 구성을 캐시합니다. ConfigBuilder를 사용하여 구성을 생성하는 경우에는 해당 구성 오브젝트를 캐시하지 않습니다. 하지만 org.eclipse.microprofile.config.spi 패키지의 ConfigProviderResolver에는 구성 오브젝트를 캐싱하는 데 사용할 수 있는 registerConfig 메소드 및 구성 오브젝트를 해제하기 위한 releaseConfig 메소드가 있습니다.

Liberty에서 MicroProfile 구성 구현에 대한 자세한 정보는 MicroProfile 구성 프로젝트 사이트를 참조하십시오.


주제의 유형을 표시하는 아이콘 개념 주제

파일 이름: cwlp_microprofile_overview.html