红帽全球峰会此内容没有您所选择的语言版本。
Chapter 2. Understand Eclipse MicroProfile
2.1. Eclipse MicroProfile Config
2.1.1. Eclipse MicroProfile Config in JBoss EAP
Configuration data can change dynamically and applications need to be able to access the latest configuration information without restarting the server.
Eclipse MicroProfile Config provides portable externalization of configuration data. This means, you can configure applications and microservices to run in multiple environments without modification or repackaging.
Eclipse MicroProfile Config functionality is implemented in JBoss EAP using the SmallRye Config component and is provided by the microprofile-config-smallrye subsystem. This subsystem is included in the default JBoss EAP 7.3 configuration.
Eclipse MicroProfile Config is only supported in JBoss EAP XP. It is not supported in JBoss EAP.
Additional Resources
Eclipse MicroProfile Config configuration properties can come from different locations and can be in different formats. These properties are provided by ConfigSources. ConfigSources are implementations of the org.eclipse.microprofile.config.spi.ConfigSource interface.
The Eclipse MicroProfile Config specification provides the following default ConfigSource implementations for retrieving configuration values:
-
System.getProperties(). -
System.getenv(). -
All
META-INF/microprofile-config.propertiesfiles on the class path.
The microprofile-config-smallrye subsystem supports additional types of ConfigSource resources for retrieving configuration values. You can also retrieve the configuration values from the following resources:
-
Properties in a
microprofile-config-smallrye/config-sourcemanagement resource - Files in a directory
-
ConfigSourceclass -
ConfigSourceProviderclass
Additional Resources
2.2. Eclipse MicroProfile Fault Tolerance
The Eclipse MicroProfile Fault Tolerance specification defines strategies to deal with errors inherent in distributed microservices.
The Eclipse MicroProfile Fault Tolerance specification defines the following strategies to handle errors:
- Timeout
- Define the amount of time within which an execution must finish. Defining a timeout prevents waiting for an execution indefinitely.
- Retry
- Define the criteria for retrying a failed execution.
- Fallback
- Provide an alternative in the case of a failed execution.
- CircuitBreaker
- Define the number of failed execution attempts before temporarily stopping. You can define the length of the delay before resuming execution.
- Bulkhead
- Isolate failures in part of the system so that the rest of the system can still function.
- Asynchronous
- Execute client request in a separate thread.
Additional Resources
2.2.2. Eclipse MicroProfile Fault Tolerance in JBoss EAP
The microprofile-fault-tolerance-smallrye subsystem provides support for Eclipse MicroProfile Fault Tolerance in JBoss EAP. The subsystem is available only in the JBoss EAP XP stream.
The microprofile-fault-tolerance-smallrye subsystem provides the following annotations for interceptor bindings:
-
@Timeout -
@Retry -
@Fallback -
@CircuitBreaker -
@Bulkhead -
@Asynchronous
You can bind these annotations at the class level or at the method level. An annotation bound to a class applies to all of the business methods of that class.
The following rules apply to binding interceptors:
If a component class declares or inherits a class-level interceptor binding, the following restrictions apply:
- The class must not be declared final.
- The class must not contain any static, private, or final methods.
- If a non-static, non-private method of a component class declares a method level interceptor binding, neither the method nor the component class may be declared final.
Fault tolerance operations have the following restrictions:
- Fault tolerance interceptor bindings must be applied to a bean class or bean class method.
- When invoked, the invocation must be the business method invocation as defined in CDI specification.
An operation is not considered fault tolerant if both of the following conditions are true:
- The method itself is not bound to any fault tolerance interceptor.
- The class containing the method is not bound to any fault tolerance interceptor.
The microprofile-fault-tolerance-smallrye subsystem provides the following configuration options, in addition to the configuration options provided by Eclipse MicroProfile Fault Tolerance:
-
io.smallrye.faulttolerance.globalThreadPoolSize -
io.smallrye.faulttolerance.timeoutExecutorThreads
Additional Resources
2.3. Eclipse MicroProfile Health
2.3.1. Eclipse MicroProfile Health in JBoss EAP
JBoss EAP includes the SmallRye Health component, which you can use to determine whether the JBoss EAP instance is responding as expected. This capability is enabled by default.
Eclipse MicroProfile Health is only available when running JBoss EAP as a standalone server.
The Eclipse MicroProfile Health specification defines the following health checks:
- Readiness
-
Determines whether an application is ready to process requests. The annotation
@Readinessprovides this health check. - Liveness
-
Determines whether an application is running. The annotation
@Livenessprovides this health check.
The @Health annotation defined in previous versions of Eclipse MicroProfile Health specification is deprecated.
By default, the microprofile-health-smallrye subsystem only examines whether the server is running. The :empty-readiness-checks-status and :empty-liveness-checks-status management attributes specify the global status when no readiness or liveness probes are defined.
2.4. Eclipse MicroProfile JWT
2.4.1. Eclipse MicroProfile JWT integration in JBoss EAP
The subsystem microprofile-jwt-smallrye provides Eclipse MicroProfile JWT integration in JBoss EAP.
The following functionalities are provided by the microprofile-jwt-smallrye subsystem:
- Detecting deployments that use Eclipse MicroProfile JWT security.
- Activating support for Eclipse MicroProfile JWT.
The subsystem contains no configurable attributes or resources.
In addition to the microprofile-jwt-smallrye subsystem, the org.eclipse.microprofile.jwt.auth.api module provides Eclipse MicroProfile JWT integration in JBoss EAP.
Additional Resources
Eclipse MicroProfile JWT deployments do not depend on managed SecurityDomain resources like traditional JBoss EAP deployments. Instead, a virtual SecurityDomain is created and used across the Eclipse MicroProfile JWT deployment.
As the Eclipse MicroProfile JWT deployment is configured entirely within the Eclipse MicroProfile Config properties and the microprofile-jwt-smallrye subsystem, the virtual SecurityDomain does not need any other managed configuration for the deployment.
2.4.3. Eclipse MicroProfile JWT activation in JBoss EAP
Eclipse MicroProfile JWT is activated for applications based on the presence of an auth-method in the application.
The Eclipse MicroProfile JWT integration is activated for an application in the following way:
-
As part of the deployment process, JBoss EAP scans the application archive for the presence of an
auth-method. -
If an
auth-methodis present and defined asMP-JWT, the Eclipse MicroProfile JWT integration is activated.
The auth-method can be specified in either or both of the following files:
-
the file containing the class that extends
javax.ws.rs.core.Application, annotated with the@LoginConfig -
the
web.xmlconfiguration file
If auth-method is defined both in a class, using annotation, and in the web.xml configuration file, the definition in web.xml configuration file is used.
The Eclipse MicroProfile JWT implementation in JBoss EAP has certain limitations.
The following limitations of Eclipse MicroProfile JWT implementation exist in JBoss EAP:
-
The Eclipse MicroProfile JWT implementation parses only the first key from the JSON Web Key Set (JWKS) supplied in the
mp.jwt.verify.publickeyproperty. Therefore, if a token claims to be signed by the second key or any key after the second key, the token fails verification and the request containing the token is not authorized. - Base64 encoding of JWKS is not supported.
In both cases, a clear text JWKS can be referenced instead of using the mp.jwt.verify.publickey.location config property.
2.5. Eclipse MicroProfile Metrics
2.5.1. Eclipse MicroProfile Metrics in JBoss EAP
JBoss EAP includes the SmallRye Metrics component. The SmallRye Metrics component provides the Eclipse MicroProfile Metrics functionality using the microprofile-metrics-smallrye subsystem.
The microprofile-metrics-smallrye subsystem provides monitoring data for the JBoss EAP instance. The subsystem is enabled by default.
The microprofile-metrics-smallrye subsystem is only enabled in standalone configurations.
Additional Resources
2.6. Eclipse MicroProfile OpenAPI
2.6.1. Eclipse MicroProfile OpenAPI in JBoss EAP
Eclipse MicroProfile OpenAPI is integrated in JBoss EAP using the microprofile-openapi-smallrye subsystem.
The Eclipse MicroProfile OpenAPI specification defines an HTTP endpoint that serves an OpenAPI 3.0 document. The OpenAPI 3.0 document describes the REST services for the host. The OpenAPI endpoint is registered using the configured path, for example http://localhost:8080/openapi, local to the root of the host associated with a deployment.
Currently, the OpenAPI endpoint for a virtual host can only document a single deployment. To use OpenAPI with multiple deployments registered with different context paths on the same virtual host, each deployment must use a distinct endpoint path.
The OpenAPI endpoint returns a YAML document by default. You can also request a JSON document using an Accept HTTP header, or a format query parameter.
If the Undertow server or host of a given application defines an HTTPS listener then the OpenAPI document is also available using HTTPS. For example, an endpoint for HTTPS is https://localhost:8443/openapi.
2.7. Eclipse MicroProfile OpenTracing
2.7.1. Eclipse MicroProfile OpenTracing
The ability to trace requests across service boundaries is important, especially in a microservices environment where a request can flow through multiple services during its life cycle.
The Eclipse MicroProfile OpenTracing specification defines behaviors and an API for accessing an OpenTracing compliant Tracer interface within a CDI-bean application. The Tracer interface automatically traces JAX-RS applications.
The behaviors specify how OpenTracing Spans are created automatically for incoming and outgoing requests. The API defines how to explicitly disable or enable tracing for given endpoints.
Additional Resources
- For more information about Eclipse MicroProfile OpenTracing specification, see Eclipse MicroProfile OpenTracing documentation.
-
For more information about the
Tracerinterface, seeTracerjavadoc.
2.7.2. Eclipse MicroProfile OpenTracing in EAP
You can use the microprofile-opentracing-smallrye subsystem to specify environment variables that trace Jakarta EE applications. This subsystem uses the SmallRye OpenTracing component to provide the Eclipse MicroProfile OpenTracing functionality for JBoss EAP.
MicroProfile 1.3.0 supports tracing requests for applications. You can configure the default Jaeger Java Client tracer, plus a set of instrumentation libraries for components commonly used in Jakarta EE, to set system properties or environment variables.
Each individual WAR deployed to the JBoss EAP server automatically has its own Tracer instance. Each WAR within an EAR is treated as an individual WAR, and each has its own Tracer instance. By default, the service name used with the Jaeger Client is derived from the deployment’s name, which is usually the WAR file name.
Within the microprofile-opentracing-smallrye subsystem, you can configure the Jaeger Java Client by setting system properties or environment variables.
Configuring the Jeager Client tracer using system properties and environment variables is provided as a Technology Preview. The system properties and environment variables affiliated with the Jeager Client tracer might change and become incompatible with each other in future releases.
By default, the probabilistic sampling strategy of the Jaeger Client for Java is set to 0.001, meaning that only approximately one in one thousand traces are sampled. To sample every request, set the system properties JAEGER_SAMPLER_TYPE to const and JAEGER_SAMPLER_PARAM to 1.
Additional Resources
- For more information about SmallRye OpenTracing functionality, see the SmallRye OpenTracing component.
- For more information about the default tracer, see the Jaeger Java Client.
-
For more information about the
Tracerinterface, seeTracerjavadoc. - For more information about overriding the default tracer and tracing CDI beans, see Using Eclipse MicroProfile OpenTracing to Trace Requests in the Development Guide.
- For more information about configuring the Jaeger Client, see the Jaeger documentation.
- For more information about valid system properties, see Configuration via Environment in the Jaeger documentation.
2.8. Eclipse MicroProfile REST Client
2.8.1. MicroProfile REST client
JBoss EAP XP 1.0.0 supports the MicroProfile REST client 1.4.x that builds on JAX-RS 2.1 client APIs to provide a type-safe approach to invoke RESTful services over HTTP. The MicroProfile Type Safe REST clients are defined as Java interfaces. With the MicroProfile REST clients, you can write client applications with executable code.
Use the MicroProfile REST client to avail the following capabilities:
- An intuitive syntax
- Programmatic registration of providers
- Declarative registration of providers
- Declarative specification of headers
- Propagation of headers on the server
-
ResponseExceptionMapper - CDI integration
Additional resources
- A comparison between MicroProfile REST client and JAX-RS syntaxes
- Programmatic registration of providers in MicroProfile REST client
- Declarative registration of providers in MicroProfile REST client
- Declarative specification of headers in MicroProfile REST client
- Propagation of headers on the server in MicroProfile REST client
- ResponseExceptionMapper in MicroProfile REST client
- Context dependency injection with MicroProfile REST client
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}