[17.0.0.3 and later]

API de MicroProfile Config

Las aplicaciones pueden utilizar la API de MicroProfile Config como una única API que puede recuperar información de configuración de diferentes orígenes.

Cuando se utiliza la API de MicroProfile Config:
  • Se pueden amalgamar varias fuentes de configuración en una sola configuración y se acceda con una API.
  • Los valores de propiedad de configuración se pueden alterar temporalmente con valores de fuentes de configuración que se han designado para tener una prioridad superior.
  • Los valores se pueden almacenar en archivos de propiedad con nombre, variables de entorno del sistema o propiedades del sistema Java™.
  • Los recursos ConfigSource se cargan utilizando un Java ClassLoader, ya sea el ClassLoader del contexto actual de la aplicación o un ClassLoader proporcionado por el usuario.
  • Los valores se pueden proporcionar registrando una implementación de usuario de una interfaz ConfigSource.
  • Los valores se pueden recuperar como serie o como objetos especificados de una clase Java concreta utilizando conversores de tipo incorporado o personalizado.
  • Las implementaciones ConfigSource y Converter se pueden descubrir utilizando el patrón Java ServiceLoader.
  • Los valores de propiedad de configuración, para primitivos, tipos estándares o tipos proporcionados por el usuario, se pueden inyectar directamente utilizando Java CDI (Context and Dependency Injection).

Inyección de configuración

La API de MicroProfile Config recopila los orígenes de configuración predeterminados y los orígenes de configuración cargados por Java ServiceLoader configsources y se describen más adelante en este tema. Es posible utilizar Java CDI (Contexts and Dependency Injection) para inyectar el objeto de configuración directamente en una aplicación.

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

También es posible inyectar un único valor de propiedad de configuración.

@Inject
@ConfigProperty
String PROPERTY_NAME1;

Estas propiedades se representan sin formato como Series, simplemente como las propiedades Java estándar. El sistema utiliza los valores predeterminados para fuentes de configuración y obtiene el nombre de la propiedad de configuración a partir del nombre de classname, donde la primera letra está en minúsculas y se añade como apéndice con el nombre de la variable y el separador es un punto. Por ejemplo, si el fragmento de código anterior está en la clase que se llama ClassA, el nombre de la propiedad que se resuelve es classA.PROPERTY_NAME1.

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

Este fragmento de código es para buscar la propiedad obligatoria PROPERTY_NAME2 en los orígenes de configuración. Si la propiedad no existe, se lanza una excepción DeploymentException.

Si una propiedad no existe en ningún configsources configurado, utilice el parámetro defaultValue para asignar el valor predeterminado.
@inject
@ConfigProperty(name="myName", defaultValue="Bob")
Nombre de serie;
Este fragmento de código busca la propiedad myName en el configsources configurado. Si la propiedad no está definida, el valor Bob se asigna a la variable name.

Búsqueda programática de configuración

La API de MicroProfile Config también proporciona una interfaz para recuperar las propiedades de configuración utilizando llamadas de método. Este recuperación se puede realizar de dos formas, una clase de proveedor de configuración fácil de utilizar que utiliza valores predeterminados y una clase de creador de configuración totalmente configurable.

Clase ConfigProvider

La forma más fácil de utilizar una configuración es mediante un método estático en la clase ConfigProvider. Esta API recopila los orígenes de configuración predeterminados y los orígenes de configuración cargados por el Java® ServiceLoader configsources.

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

Clase ConfigBuilder

Para los usuarios que desean crear configuraciones de una forma más personalizada, se puede utilizar una API de constructor de configuración para establecer distintas opciones antes de que se genere la configuración. Este ejemplo utiliza el patrón de creación para crear la configuración equivalente a la del ejemplo anterior.

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

La llamada a builder.addDefaultSources() se añade en el mismo conjunto de fuentes predeterminadas que utiliza ConfigProvider para crear configuraciones. También se pueden añadir otras fuentes de configuración.

Orígenes de configuración

Las propiedades de configuración se pueden obtener de una serie de ubicaciones, incluyendo archivos de propiedad y clases de usuario que son registrados por la aplicación o que se cargan utilizando el patrón Java ServiceLoader.

Orígenes predeterminados

A diferencia de la interfaz ConfigProvider, la interfaz ConfigBuilder tiene inicialmente un conjunto vacío de fuentes de propiedades de configuración. Añadir las fuentes predeterminadas tiene los efectos siguientes:

  1. Las variables de entorno de proceso están incluidas en la configuración. Liberty muestra variables de entorno de proceso de host en el método de Java System.getenv() y, además, añade propiedades del archivo del servidor server.env. Entonces estas variables están disponibles en la API de MicroProfile Config.
  2. Las propiedades del sistema Java disponibles a través de System.getProperties() se incluyen en la configuración. Liberty añade propiedades del archivo bootstrap.properties y jvm.options del servidor a las propiedades del sistema Java.
  3. Los archivos que se cargan desde la vía de acceso de clases ThreadContextClassLoader de la aplicación con un resourceName de META-INF/microprofile-config.properties. Dentro de estos archivos de propiedad, las propiedades se almacenan utilizando la misma sintaxis que utilizan los archivos de propiedades estándar de Java. Para una aplicación Liberty, la ubicación del directorio META-INF podría ser un subdirectorio en la raíz de un JAR o el directorio WEB-INF\classes\META-INF\ para un archivo WAR, o en un JAR del directorio lib de EAR, o en un JAR de biblioteca compartida de nivel de servidor. El ClassLoadery, la vía de acceso de clases, que se utilizan se pueden alterar utilizando el método forClassLoader del constructor.

ConfigSources proporcionado por el usuario

Una clase de usuario que implementa org.eclipse.microprofile.config.spi.ConfigSource se puede registrar con un ConfigBuilder. De esta forma, esta clase de usuario se incluye, posteriormente, en configuraciones que genera el compilador.

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

Carga de Java ServiceLoader de ConfigSources

El patrón de Java ServiceLoader también se puede utilizar para localizar objetos de origen de configuración personalizados. Una clase de usuario que implementa la interfaz ConfigSource se carga, si su nombre de clase de paquete completo aparece listado en un archivo del formato, ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource.

Conversores

La API de MicroProfile Config también puede recuperar propiedades como tipos de objeto Java con un método genérico que toma el tipo del objeto de propiedad que se desea. Este método puede funcionar para cualquier tipo que tenga un conversor incorporado o proporcionado por usuario. Por ejemplo, el código en el ejemplo anterior se puede escribir para utilizar el conversor de serie incorporado como:

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

Conversores incorporados

La API de MicroProfile Config incluye conversores incorporados para los tipos siguientes: boolean, Boolean, int, Integer, long, Long, float, Float, double, Double, Duration, LocalTime, LocalDate, LocalDateTime, OffsetDateTime, OffsetTime, Instant y URL.

Las variables de cualquiera de estos tipos se pueden inyectar directamente, o recuperar utilizando la llamada getValue genérica. Si el valor de serie de la propiedad se puede convertir correctamente al tipo utilizando el método valueof, parse o de constructor relevante tomando un único parámetro de serie.

Conversores personalizados

Los conversores personalizados que implementan la interfaz org.eclipse.microprofile.config.spi.Converter<T> se pueden registrar y utilizar en configuraciones utilizando la API ConfigBuilder.

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);
El método withConverters utiliza el reflejo para determinar para qué tipo es el conversor. El código Java Lambda actualmente no ofrece información de tipo suficientemente específica a las API de reflejo, así que el código que implementa explícitamente una interfaz Converter<T> es necesario para un conversor personalizado.

Prioridad de conversor

Si existen varios conversores para el mismo tipo, el conversor que se utiliza se puede controlar utilizando una anotación @Priority. Este método permite que la implementación del conversor se altere temporalmente más tarde en el ciclo de vida de la aplicación. Un conversor altera temporalmente cualquier otro conversor con una prioridad inferior que es para el mismo tipo.

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;
    }
}

La prioridad predeterminada para un conversor si la anotación @Priority no se utiliza es 100.

Soporte de Java ServiceLoader para conversores

El patrón de Java ServiceLoader también se puede utilizar para localizar conversores personalizados, si sus nombres de clase completos de paquete aparecen en un archivo de servicio del formulario, ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converter.

Ambos conversores predeterminados incluidos en la implementación de API de MicroProfile Config y los conversores descubiertos utilizando el patrón de Java ServiceLoader están disponibles para que los utilicen todas las configuraciones.

Alteración temporal de valores de propiedad

Cuando se utiliza más de un origen de configuración, las propiedades de todos los orígenes se recopilan juntas y la aplicación accede a las mismas como un conjunto único. A cada fuente de configuración se le asigna un valor ordinal. Si una propiedad aparece en más de una fuente, el valor de la propiedad de la fuente con el ordinal más alto tiene prioridad y se devuelve a la aplicación. Los valores ordinales predeterminados son:

  • Propiedades del sistema - 400
  • Variables de entorno - 300
  • /META-INF/microprofile-config.properties - 100
  • Objetos ConfigSource personalizados - El resultado getOrdinal de ConfigSource
Nota: Los tres primeros valores ordinales que aparecen listados se pueden alterar temporalmente utilizando una propiedad config_ordinal que se encuentra en el origen de configuración a la que se aplica.

Si dos ConfigSources que proporcionan la misma propiedad tienen ordinales idénticos, el ID ConfigSources se utiliza para la comparación de acuerdo con las reglas de comparación de serie.

Las fuentes que normalmente se establecen con anterioridad en el ciclo de vida de desarrollo tienen ordinales y una prioridad inferiores. Esto es para dar soporte a la capacidad de alterar temporalmente un valor de propiedad existente más tarde en el ciclo de vida de la aplicación, por ejemplo, durante el ensamblaje o la instalación de la aplicación.

Valores de propiedades dinámicas

Aunque una aplicación de microservicio bien diseñada mantiene la disponibilidad entre reinicios de aplicaciones individuales, es deseable que los cambios en los valores de configuración estén disponibles en una aplicación sin reiniciarla. Los valores de propiedad de una configuración proporcionados por por objetos ConfigSource registrados se pueden renovar con cualquier valor actualizado que los ConfigSources proporcionen. La frecuencia con la que se consultan ConfigSources y con la que se renuevan los valores se controla mediante la propiedad del sistema microprofile.config.refresh.rate Java. Las unidades que se utilizan son milisegundos y el valor predeterminado es 500, lo que significa que, de forma predeterminada, los valores proporcionados por ConfigSources alimentan cualquier configuración en la que colaboren en medio segundo.

Las fuentes de configuración no programáticas como, por ejemplo, archivos microprofile-config.properties, no se releen dinámicamente después de la construcción de configuración inicial.

Para habilitar actualizaciones en valores que se van a ver después de que se inyecten propiedades, se puede utilizar un objeto ConfigValue. Este tiene métodos getter, tanto para el valor de propiedad de configuración como un Optional<T> del valor de propiedad de configuración, que devuelven el valor actual cada vez que se llama al método getter. Por ejemplo:

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

También puede ver que la clase ConfigValue se ha hecho genérica y se puede utilizar para recuperar una propiedad de un tipo específico, si está presente un conversor idóneo.

Almacenamiento en memoria caché de configuración

Para ayudar con la eficiencia, un ConfigProvider almacena en la memoria caché la configuración devuelta por su método getConfig para una aplicación (o módulo) concreta identificada por su ClassLoader. Si la configuración se genera utilizando ConfigBuilder, el objeto de configuración no se almacena en la memoria caché. Sin embargo, el ConfigProviderResolver, en el paquete org.eclipse.microprofile.config.spi, tiene un método registerConfig que se puede utilizar para almacenar en memoria caché objetos de configuración y un método releaseConfig para liberar el objeto de configuración.

Para obtener más información sobre cómo implementar MicroProfile Config en Liberty, consulte el sitio de proyecto de configuración de MicroProfile.


Icono que indica el tipo de tema Tema de concepto

Nombre de archivo: cwlp_microprofile_overview.html