The page you’re looking for does not exist. It may have been moved. + You can return to the start page, or browse the extensions in the navigation bar on the left.
+If you arrived on this page by clicking on a link, please notify the owner of the site that the link is broken. +If you typed the URL of this page manually, please double check that you entered the address correctly.
+The page you requested has been relocated to https://docs.quarkiverse.io/index/explore/index.html.
diff --git a/index/explore/index.html b/index/explore/index.html new file mode 100644 index 0000000000..91593b196a --- /dev/null +++ b/index/explore/index.html @@ -0,0 +1,900 @@ + + + + + +Welcome to the Quarkiverse documentation site.
+Pick the Quarkus extension you’re interested in from the navigation menu.
+This Quarkus extension aims at making the Amazon Alexa SDK work in native executables.
+If you want to use this extension, you need to add the io.quarkiverse.amazonalexa:quarkus-amazon-alexa extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.amazonalexa</groupId>
+ <artifactId>quarkus-amazon-alexa</artifactId>
+ <version>1.0.5</version>
+</dependency>Service client for accessing Amazon Cognito user pools (Identity Provider).
+Using the Amazon Cognito user pools API, you can create a user pool to manage directories and users. +You can authenticate a user to obtain tokens related to user identity and access policies.
+For more information, see the Amazon Cognito user pools (AWS Java SDK 2.x docs).
+| + + | ++The Cognito User Pools extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use Cognito User Pool locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+One of:
+An AWS Account to access the Cognito service
+Or Docker for your system to run Cognito locally for testing purposes
+The easiest way to start working with Cognito is to run a local instance using Dev Services.
+You can also set up a local version of Cognito manually, first start a local instance as a container:
+docker run --rm --name moto -p 5000:5000 -d motoserver/moto:3.0.2This starts a Cognito mock instance that is accessible on port 5000.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile moto
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: testCreate a Cognito user pool using AWS CLI.
+aws --profile moto --endpoint-url=http://localhost:5000 cognito-idp create-user-pool --pool-name quarkus-users-devOr, if you want to use your Cognito user pool on your AWS account create a user pool using your default profile
+aws cognito-user-pools cognito-idp --pool-name quarkus-users-devThe application built here shows the count of Cognito User Pools in the current region.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-cognito-user-pools-quickstart \
+ -DclassName="org.acme.cognitouserpools.CognitoExampleResource" \
+ -Dpath="/cognito-example" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-cognito-user-pools,resteasy-mutiny"
+cd amazon-cognito-user-pools-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Cognito User Pool extensions.
+After this, the amazon-cognito-user-pools extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Edit a org.acme.cognitouserpools.CognitoExampleResource that will provide an API return count of Cognito User Pools using the synchronous client.
package org.acme.cognitouserpools;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsResponse;
+
+@Path("/cognito-example")
+public class CognitoExampleResource {
+ @Inject
+ CognitoIdentityProviderClient cognitoClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ ListUserPoolsResponse response = cognitoClient.listUserPools(request);
+ return String.format("You have %d user pools", response.userPools().size());
+ }
+}And update test class:
+package org.acme.cognitouserpools;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.Test;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+
+@QuarkusTest
+public class CognitoExampleResourceTest {
+
+ @Test
+ public void testHelloEndpoint() {
+ given()
+ .when().get("/cognito-example")
+ .then()
+ .statusCode(200)
+ .body(is("You have 1 user pools"));
+ }
+
+}Both Cognito clients (sync and async) are configurable via the application.properties file that
+can be provided in the src/main/resources directory.
Additionally, you need to add to the classpath a proper implementation of the sync client.
+By default the extension uses the URL connection HTTP client, so you need to add a URL connection
+client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local Cognito mock instance, configure it as follows:
+quarkus.cognito-user-pools.endpoint-override=http://localhost:5000
+
+quarkus.cognito-user-pools.aws.region=eu-west-1
+quarkus.cognito-user-pools.aws.credentials.type=static
+quarkus.cognito-user-pools.aws.credentials.static-provider.access-key-id=test-key
+quarkus.cognito-user-pools.aws.credentials.static-provider.secret-access-key=test-secretquarkus.cognito-user-pools.aws.region - It’s required by the client, but since you’re using a local Cognito mock instance use us-east-1 as it’s a default region of moto.
quarkus.cognito-user-pools.aws.credentials - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.cognito-user-pools.endpoint-override - Override the Cognito User Pools client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Cognito User Pools
+related properties. By default, the Cognito User Pools client extension will use the default
+credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.cognitouserpools.CognitoAsyncExampleResource REST resource that will be similar to our
+CognitoExampleResource but using an asynchronous programming model.
package org.acme.cognitouserpools;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderAsyncClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+
+@Path("/cognito-async-example")
+public class CognitoAsyncExampleResource {
+ @Inject
+ CognitoIdentityProviderAsyncClient cognitoAsyncClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ return Uni
+ .createFrom()
+ .completionStage(cognitoAsyncClient.listUserPools(request))
+ .map(response -> {
+ return String.format("You have %d user pools", response.userPools().size());
+ });
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous Cognito
+Identity Provider client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+DynamoDB is a scalable AWS managed NoSQL database. +It supports both key-value and document data models, that enables to have a flexible schema for your data. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about DynamoDB at the Amazon DynamoDB website.
+| + + | ++The DynamoDB extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). +Keep in mind it’s actively developed and does not support yet all the features available in SDK 1.x such as Document APIs + | +
The Quarkus extension supports the traditional DynamoDB client as well as the enhanced client.
+It supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the DynamoDB service
+Optionally, Docker for your system to run DynamoDB locally for testing purposes
+The easiest way to start working with DynamoDB is to run a local instance using Dev Services.
+You can also set up a local version of DynamoDB manually, first start a local instance as a container:
+docker run --publish 4566:8000 amazon/dynamodb-local:1.19.0 -jar DynamoDBLocal.jar -inMemory -sharedDbThis starts a DynamoDB instance that is accessible on port 4566.
+You can check if it’s working with aws dynamodb list-tables --endpoint-url http://localhost:4566.
{
+ "TableNames": []
+}You should see the output above in your terminal. That’s it, DynamoDB runs locally.
+Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.
+Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. +For more information, see Setting Up DynamoDB (Web Service).
+We recommend to use the AWS CLI to provision the table:
+The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-dynamodb-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-dynamodb-quickstart \
+ -DclassName="org.acme.dynamodb.FruitResource" \
+ -Dpath="/fruits" \
+ -Dextensions="resteasy-reactive-jackson,amazon-dynamodb"
+cd amazon-dynamodb-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and DynamoDB Client extensions.
+After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Fruit bean as follows:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ public static Fruit from(Map<String, AttributeValue> item) {
+ Fruit fruit = new Fruit();
+ if (item != null && !item.isEmpty()) {
+ fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
+ fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
+ }
+ return fruit;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map
+object provided by the DynamoDB client response.
Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.
package org.acme.dynamodb;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.ScanRequest;
+
+public abstract class AbstractService {
+
+ public final static String FRUIT_NAME_COL = "fruitName";
+ public final static String FRUIT_DESC_COL = "fruitDescription";
+
+ public String getTableName() {
+ return "QuarkusFruits";
+ }
+
+ protected ScanRequest scanRequest() {
+ return ScanRequest.builder().tableName(getTableName())
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
+ }
+
+ protected PutItemRequest putRequest(Fruit fruit) {
+ Map<String, AttributeValue> item = new HashMap<>();
+ item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
+ item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());
+
+ return PutItemRequest.builder()
+ .tableName(getTableName())
+ .item(item)
+ .build();
+ }
+
+ protected GetItemRequest getRequest(String name) {
+ Map<String, AttributeValue> key = new HashMap<>();
+ key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());
+
+ return GetItemRequest.builder()
+ .tableName(getTableName())
+ .key(key)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
+ .build();
+ }
+}Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ DynamoDbClient dynamoDB;
+
+ public List<Fruit> findAll() {
+ return dynamoDB.scanPaginator(scanRequest()).items().stream()
+ .map(Fruit::from)
+ .collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ dynamoDB.putItem(putRequest(fruit));
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
+ }
+}Now, edit the org.acme.dynamodb.FruitResource class as follows:
package org.acme.dynamodb;
+
+import java.util.List;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.core.MediaType;
+
+@Path("/fruits")
+public class FruitResource {
+
+ @Inject
+ FruitSyncService service;
+
+ @GET
+ public List<Fruit> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Fruit getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public List<Fruit> add(Fruit fruit) {
+ service.add(fruit);
+ return getAll();
+ }
+}The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.
DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local DynamoDB instance, configure it as follows:
+quarkus.dynamodb.endpoint-override=http://localhost:4566
+
+quarkus.dynamodb.aws.region=eu-central-1
+quarkus.dynamodb.aws.credentials.type=static
+quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
+quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secretquarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.
quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.dynamodb.aws.region=<YOUR_REGION>
+quarkus.dynamodb.aws.credentials.type=defaultquarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,
quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Collectors;
+
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ @Inject
+ DynamoDbAsyncClient dynamoDB;
+
+ public Uni<List<Fruit>> findAll() {
+ return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
+ .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
+ }
+
+ public Uni<List<Fruit>> add(Fruit fruit) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit)))
+ .onItem().ignore().andSwitchTo(this::findAll);
+ }
+
+ public Uni<Fruit> get(String name) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
+ .onItem().transform(resp -> Fruit.from(resp.item()));
+ }
+}In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.
Then, create an asynchronous REST resource that consumes this async service:
+package org.acme.dynamodb;
+
+import io.smallrye.mutiny.Uni;
+
+import javax.inject.Inject;
+import javax.ws.rs.*;
+import javax.ws.rs.core.MediaType;
+import java.util.List;
+
+@Path("/async-fruits")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class FruitAsyncResource {
+
+ @Inject
+ FruitAsyncService service;
+
+ @GET
+ public Uni<List<Fruit>> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Uni<Fruit> getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public Uni<List<Fruit>> add(Fruit fruit) {
+ return service.add(fruit)
+ .onItem().ignore().andSwitchTo(this::getAll);
+ }
+}And add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>The DynamoDB enhanced client is part of the AWS SDK for Java version 2 and makes the mapping between DynamoDB Tables and Java beans very easy. +The Enhanced Client requires a TableSchema, which can be generated with a set of annotations or declared in code. +It has both a sync and an async variants.
+To use the enhanced client, add the quarkus-amazon-dynamodb-enhanced extension to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-dynamodb-enhanced</artifactId>
+</dependency>The Fruit bean would look like this:
package org.acme.dynamodb;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
+
+@DynamoDbBean
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ @DynamoDbPartitionKey
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+}The FruitSyncService would need to use the DynamoDbEnhancedClient as well as create a TableSchema:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ private DynamoDbTable<Fruit> fruitTable;
+
+ @Inject
+ DynamoDbEnhancedClient dynamoEnhancedClient;
+
+ FruitSyncService() {
+ fruitTable = dynamoEnhancedClient.table(getTableName(),
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public List<Fruit> findAll() {
+ return exampleBlockingTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}The FruitResource does not change.
You can find more information about the DynamoDB enhanced client in the AWS documentation:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
Amazon Identity and Access Management (IAM) enables users to manage access to AWS services and resources securely.
+You can find more information about IAM at the Amazon IAM website.
+| + + | ++The IAM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Key Management Service (KMS) is a service that allows you to create and control the keys used to encrypt or digitally sign your data. +Using KMS, you can create and manage cryptographic keys and control their use across a wide range of AWS services and in your application.
+You can find more information about KMS at the AWS KMS website.
+| + + | ++The KMS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use KMS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the KMS service
+Docker for your system to run KMS locally for testing purposes
+The easiest way to start working with KMS is to run a local instance using Dev Services.
+You can also set up a local version of KMS manually, first start a LocalStack container:
+docker run --rm --name local-kms --publish 4566:4599 -e SERVICES=kms -e START_WEB=0 -d localstack/localstack:1.0.3This starts a KMS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a KMS master key queue using AWS CLI and store in MASTER_KEY_ARN environment variable.
MASTER_KEY_ARN=`aws kms create-key --profile localstack --endpoint-url=http://localhost:4566 | cut -f3`Generate a key data as 256-bit symmetric key (AES 256)
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256 --profile localstack --endpoint-url=http://localhost:4566Or, if you want to use your AWS account create a key using your default profile
+MASTER_KEY_ARN=`aws kms create-key | cut -f3`
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256The application built here allows to encrypt and decrypt text messages using a master key created on AWS KMS.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-kms-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kms-quickstart \
+ -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kms"
+cd amazon-kms-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon KMS Client extensions.
+After this, the amazon-kms extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to encrypt and decrypt text message provided in the request. +The example application will demonstrate the two programming models supported by the extension.
+Let’s create a org.acme.kms.QuarkusKmsSyncResource that will provide an API to encrypt and decrypt message using the synchronous client.
package org.acme.kms;
+
+import java.util.Base64;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsSyncResource {
+
+ @Inject
+ KmsClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public String encrypt(String data) {
+ SdkBytes encryptedBytes = kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))).ciphertextBlob();
+
+ return Base64.getEncoder().encodeToString(encryptedBytes.asByteArray());
+ }
+
+ @POST
+ @Path("/decrypt")
+ public String decrypt(String data) {
+ SdkBytes encryptedData = SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes()));
+ DecryptResponse decrypted = kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(encryptedData));
+
+ return decrypted.plaintext().asUtf8String();
+ }
+}An encrypted message is in the form of a bytes array. To return it to the user we need to encode it as Base64 string in the encrypt endpoint.
+On the decrypt endpoint we need to decode from the Base64 string back to the bytes array before sending it out to the KMS client.
Both KMS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local KMS instance, configure it as follows:
+quarkus.kms.endpoint-override=http://localhost:4566
+
+quarkus.kms.aws.region=us-east-1
+quarkus.kms.aws.credentials.type=static
+quarkus.kms.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kms.aws.credentials.static-provider.secret-access-key=test-secretquarkus.kms.aws.region - It’s required by the client, but since you’re using a local KMS instance use us-east-1 as it’s a default region of LocalStack’s KMS.
quarkus.kms.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.kms.endpoint-override - Override the KMS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon KMS related properties. By default, the KMS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dkey.arn=$MASTER_KEY_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.kms.QuarkusKmsAsyncResource REST resource that will be similar to our QuarkusKmsSyncResource but using an asynchronous programming model.
package org.acme.kms;
+
+import java.util.Base64;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsAsyncClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+import software.amazon.awssdk.services.kms.model.EncryptResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsAsyncResource {
+
+ @Inject
+ KmsAsyncClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public Uni<String> encrypt(String data) {
+ return Uni.createFrom().completionStage(kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))))
+ .onItem().transform(EncryptResponse::ciphertextBlob)
+ .onItem().transform(blob -> Base64.getEncoder().encodeToString(blob.asByteArray()));
+ }
+
+ @POST
+ @Path("/decrypt")
+ public Uni<String> decrypt(String data) {
+ return Uni.createFrom().item(SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes())))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg)))
+ )
+ .onItem().transform(DecryptResponse::plaintext)
+ .onItem().transform(SdkBytes::asUtf8String);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous KMS client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon S3 is an object storage service. It can be employed to store any type of object which allows for uses like storage for Internet applications, +backup and recovery, disaster recovery, data archives, data lakes for analytics, any hybrid cloud storage. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about S3 at the Amazon S3 website.
+| + + | ++The S3 extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use S3 locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the S3 service. Before you can use the AWS SDKs with Amazon S3, you must get an AWS access key ID and secret access key.
+Optionally, Docker for your system to run S3 locally for testing purposes
+The easiest way to start working with S3 is to run a local instance using Dev Services.
+You can optionally configure the buckets that are created on startup with the quarkus.s3.devservices.buckets config property.
You can also setup a local version of S3 manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=s3 -e START_WEB=0 localstack/localstack:1.0.3This starts a S3 instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to manage files stored in Amazon S3.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-s3-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-s3-quickstart \
+ -DclassName="org.acme.s3.S3SyncClientResource" \
+ -Dpath="/s3" \
+ -Dextensions="resteasy-reactive-jackson,amazon-s3"
+cd amazon-s3-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and S3 Client extensions.
+After this, the amazon-s3 extension has been added to your pom.xml.
| + + | +
+The default setting for quarkus.http.limits.max-body-size is 10240K. This may limit your ability to upload multipart files larger than the default. If you want to upload larger files, you will need to set this limit explicitly.
+ |
+
In this example, we will create an application to manage a list of files. The example application will demonstrate the two programming models supported by the extension.
+Because the primary goal of our application is to upload a file into the S3 bucket, we need to setup the model we will be using to define the multipart/form-data payload,
+in the form of a @MultipartForm POJO.
Create a org.acme.s3.FormData class as follows:
package org.acme.s3;
+
+import java.io.File;
+import javax.ws.rs.core.MediaType;
+import org.jboss.resteasy.reactive.PartType;
+import org.jboss.resteasy.reactive.RestForm;
+
+public class FormData {
+
+ @RestForm("file")
+ public File data;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String filename;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String mimetype;
+
+}The class defines three fields:
+data that fill capture stream of uploaded bytes from the client
fileName that captures a filename as provided by the submited form
mimeType content type of the uploaded file
In the second step let’s create a bean that will represent a file in a Amazon S3 bucket as follows:
+package org.acme.s3;
+
+import software.amazon.awssdk.services.s3.model.S3Object;
+
+public class FileObject {
+ private String objectKey;
+
+ private Long size;
+
+ public FileObject() {
+ }
+
+ public static FileObject from(S3Object s3Object) {
+ FileObject file = new FileObject();
+ if (s3Object != null) {
+ file.setObjectKey(s3Object.key());
+ file.setSize(s3Object.size());
+ }
+ return file;
+ }
+
+ public String getObjectKey() {
+ return objectKey;
+ }
+
+ public Long getSize() {
+ return size;
+ }
+
+ public FileObject setObjectKey(String objectKey) {
+ this.objectKey = objectKey;
+ return this;
+ }
+
+ public FileObject setSize(Long size) {
+ this.size = size;
+ return this;
+ }
+}Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the S3Object
+object provided by the S3 client response when listing all the objects in a bucket.
Now create a org.acme.s3.CommonResource that will consist of methods to prepare S3 request to get object from a S3 bucket, or to put file into a S3 bucket.
+Note a configuration property bucket.name is defined here as the request method required name of the S3 bucket.
package org.acme.s3;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+
+abstract public class CommonResource {
+
+ @ConfigProperty(name = "bucket.name")
+ String bucketName;
+
+ protected PutObjectRequest buildPutRequest(FormData formData) {
+ return PutObjectRequest.builder()
+ .bucket(bucketName)
+ .key(formData.filename)
+ .contentType(formData.mimetype)
+ .build();
+ }
+
+ protected GetObjectRequest buildGetRequest(String objectKey) {
+ return GetObjectRequest.builder()
+ .bucket(bucketName)
+ .key(objectKey)
+ .build();
+ }
+
+}Then, create a org.acme.s3.S3SyncClientResource that will provides an API to upload/download files as well as to list all the files in a bucket.
package org.acme.s3;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.ResponseBuilder;
+import javax.ws.rs.core.Response.Status;
+import org.jboss.resteasy.reactive.MultipartForm;
+import software.amazon.awssdk.core.ResponseBytes;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectResponse;
+
+
+@Path("/s3")
+public class S3SyncClientResource extends CommonResource {
+ @Inject
+ S3Client s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Response uploadFile(@MultipartForm FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ PutObjectResponse putResponse = s3.putObject(buildPutRequest(formData),
+ RequestBody.fromFile(formData.data));
+ if (putResponse != null) {
+ return Response.ok().status(Status.CREATED).build();
+ } else {
+ return Response.serverError().build();
+ }
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public Response downloadFile(String objectKey) {
+ ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(buildGetRequest(objectKey));
+ ResponseBuilder response = Response.ok(objectBytes.asUtf8String());
+ response.header("Content-Disposition", "attachment;filename=" + objectKey);
+ response.header("Content-Type", objectBytes.response().contentType());
+ return response.build();
+ }
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public List<FileObject> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder().bucket(bucketName).build();
+
+ //HEAD S3 objects to get metadata
+ return s3.listObjects(listRequest).contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}Both S3 clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
| + + | +
+You need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+add a URL connection client dependency to the pom.xml file:
+ |
+
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>For asynchronous client refer to Going asynchronous for more information.
+If you’re going to use a local S3 instance, configure it as follows:
+quarkus.s3.endpoint-override=http://localhost:4566
+
+quarkus.s3.aws.region=us-east-1
+quarkus.s3.aws.credentials.type=static
+quarkus.s3.aws.credentials.static-provider.access-key-id=test-key
+quarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret
+
+bucket.name=quarkus.s3.quickstartquarkus.s3.aws.region - It’s required by the client, but since you’re using a local S3 instance you can pick any valid AWS region.
quarkus.s3.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.s3.endpoint-override - Override the S3 client to use a local instance instead of an AWS service
bucket.name - Name of the S3 bucket
If you want to work with an AWS account, you’d need to set it with:
+bucket.name=<your-bucket-name>
+
+quarkus.s3.aws.region=<YOUR_REGION>
+quarkus.s3.aws.credentials.type=defaultbucket.name - name of the S3 bucket on your AWS account.
quarkus.s3.aws.region you should set it to the region where your S3 bucket was created,
quarkus.s3.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Now let’s add a simple web page to interact with our S3SyncClientResource.
+Quarkus automatically serves static resources located under the META-INF/resources directory.
+In the src/main/resources/META-INF/resources directory, add a s3.html file with the content from this s3.html file in it.
You can now interact with your REST service:
+start Quarkus with ./mvnw compile quarkus:dev
open a browser to http://localhost:8080/s3.html
upload new file to the current S3 bucket via the form and see the list of files in the bucket
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.s3.S3AsyncClientResource that will be similar to our S3SyncClientResource but using an asynchronous programming model.
package org.acme.s3;
+
+import io.smallrye.mutiny.Uni;
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.Status;
+import org.jboss.resteasy.reactive.MultipartForm;
+import software.amazon.awssdk.core.async.AsyncRequestBody;
+import software.amazon.awssdk.core.async.AsyncResponseTransformer;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.ListObjectsResponse;
+
+@Path("/async-s3")
+public class S3AsyncClientResource extends CommonResource {
+ @Inject
+ S3AsyncClient s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Uni<Response> uploadFile(@MultipartForm FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ return Uni.createFrom()
+ .completionStage(() -> {
+ return s3.putObject(buildPutRequest(formData), AsyncRequestBody.fromFile(formData.data));
+ })
+ .onItem().ignore().andSwitchTo(Uni.createFrom().item(Response.created(null).build()))
+ .onFailure().recoverWithItem(th -> {
+ th.printStackTrace();
+ return Response.serverError().build();
+ });
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public Uni<Response> downloadFile(String objectKey) {
+ return Uni.createFrom()
+ .completionStage(() -> s3.getObject(buildGetRequest(objectKey), AsyncResponseTransformer.toBytes()))
+ .onItem()
+ .transform(object -> Response.ok(object.asUtf8String())
+ .header("Content-Disposition", "attachment;filename=" + objectKey)
+ .header("Content-Type", object.response().contentType()).build());
+ }
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<List<FileObject>> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder()
+ .bucket(bucketName)
+ .build();
+
+ return Uni.createFrom().completionStage(() -> s3.listObjects(listRequest))
+ .onItem().transform(result -> toFileItems(result));
+ }
+
+ private List<FileObject> toFileItems(ListObjectsResponse objects) {
+ return objects.contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Secrets Manager enables you to replace hardcoded credentials in your code, including passwords, with an API call to Secrets Manager to retrieve the secret programmatically. +This helps ensure the secret can’t be compromised by someone examining your code, because the secret no longer exists in the code.
+You can find more information about Secrets Manager at the AWS Secrets Manager website.
+| + + | ++The Secrets Manager extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use Secrets Manager locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Secrets Manager service
+Docker for your system to run Secrets Manager locally for testing purposes
+The easiest way to start working with Secrets Manager is to run a local instance using Dev Services.
+You can also set up a local version of Secrets Manager manually, first start a LocalStack container:
+docker run --rm --name local-secrets-manager --publish 4566:4584 -e SERVICES=secretsmanager -e START_WEB=0 -d localstack/localstack:1.0.3This starts a Secrets Manager instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve credentials using Secrets Manager.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-secretsmanager-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-secretsmanager-quickstart \
+ -DclassName="org.acme.secretsmanager.QuarkusSecretsManagerSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-secretsmanager,resteasy-mutiny"
+cd amazon-secretsmanager-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Secrets Manager Client extensions.
+After this, the amazon-secretsmanager extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from Secrets Manager store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.secretsmanager.QuarkusSecretsManagerResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.secretsmanager;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import javax.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.secretsmanager.model.CreateSecretRequest;
+import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueRequest;
+
+public abstract class QuarkusSecretsManagerResource {
+ public static final String VERSION_STAGE = "AWSCURRENT";
+
+ @ConfigProperty(name = "secret.name") (1)
+ String secretName;
+
+ protected GetSecretValueRequest generateGetSecretValueRequest() {
+ return GetSecretValueRequest.builder() (2)
+ .secretId(secretName)
+ .versionStage(VERSION_STAGE)
+ .build();
+ }
+
+ protected CreateSecretRequest generateCreateSecretRequest(String name, String secret) {
+ return CreateSecretRequest.builder() (3)
+ .name(name)
+ .secretString(secret)
+ .build();
+ }
+
+}| 1 | +Inject a configured name under which is stored the secret | +
| 2 | +Generate a request for the credentials with the configured name | +
| 3 | +Generate a request to create a specific secret | +
Now, we can extend the class and create the synchronous implementation in the org.acme.secretsmanager.QuarkusSecretsManagerSyncResource class.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerClient;
+
+@Path("/sync")
+public class QuarkusSecretsManagerSyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject (1)
+ SecretsManagerClient secretsManagerClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public String getSecret() {
+ return secretsManagerClient.getSecretValue(generateGetSecretValueRequest()).secretString();
+ }
+
+ @POST
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void createSecret(String name, String value) {
+ secretsManagerClient.createSecret(generateCreateSecretRequest(name, secret));
+ }
+
+}| 1 | +Inject the client provided by the amazon-secretsmanager extension | +
Using the Amazon Secrets Manager SDK, we can easily store and retrieve secrets.
+Both Secrets Manager clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local Secrets Manager instance, configure it as follows:
+quarkus.secretsmanager.endpoint-override=http://localhost:4566 (1)
+
+quarkus.secretsmanager.aws.region=us-east-1 (2)
+quarkus.secretsmanager.aws.credentials.type=static (3)
+quarkus.secretsmanager.aws.credentials.static-provider.access-key-id=test-key
+quarkus.secretsmanager.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Secret Manager client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Secrets Manager related properties. By default, the Secrets Manager client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.secretsmanager.QuarkusSecretsManagerAsyncResource REST resource that will be similar to our QuarkusSecretsManagerSyncResource but using an asynchronous programming model.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerAsyncClient;
+
+@Path("/async")
+public class QuarkusSecretsManagerAsyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject
+ SecretsManagerAsyncClient secretsManagerAsyncClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<String> getSecret() {
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.getSecretValue(generateGetSecretValueRequest()))
+ .onItem().transform(r -> r.secretString());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> createSecret(String name, String value) {
+
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.createSecret(generateCreateSecretRequest(name, secret)))
+ .onItem().transform(r -> null);
+ }
+
+}Note that the SecretsManagerAsyncClient behaves just like the SecretsManagerClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Email Service (SES) is a flexible and highly-scalable email sending and receiving service. +Using SES, you can send emails with any type of correspondence. You can find more information about SES at the Amazon SES website.
+| + + | ++The SES extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use SES locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SES service
+Docker for your system to run SES locally for testing purposes
+The easiest way to start working with SES is to run a local instance using Dev Services. +However, local instance of SES is only mocks the SES APIs without the actual email sending capabilities. You can still use it for this guide to verify an API communication or integration test purposes.
+You can also set up a local version of SES manually, first start a LocalStack container:
+docker run --rm --name local-ses -p 4566:4579 -e SERVICES=ses -e START_WEB=0 -d localstack/localstack:1.0.3This starts a SES instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textAmazon applies certain restrictions to new Amazon SES accounts, mainly to prevent fraud and abuse. All new accounts are in the Amazon SES sandbox. +All the features of the Amazon SES are still available while in sandbox, but a following restrictions applies: +- You can send mail to verified email addresses and domains or to the Amazon SES mailbox simulator +- You can only send mail from verified email addresses and domains +- You can send a maximum of 1 message per second.
+Going production, you’d need to get your account of the sandbox following the Amazon procedure.
+We assume you are going to use AWS SES sandbox for the sake of this guide. But before sending any email, you must verify sender and recipient email addresses using AWS CLI. +You can use your personal email or any temporary email service available if you wish.
+aws ses verify-email-identity --email-address <sender@email.address>
+aws ses verify-email-identity --email-address <recipient@email.address>Now, you need to open a mailboxes of those email addresses in order to follow confirmation procedure. Once email is approved you can use it in your application.
+If you are using local SES you still need to verify email addresses, otherwise your send email in order to let local SES accepting your request. +However, no emails to be send as it only mocks the service APIs.
+aws ses verify-email-identity --email-address <sender@email.address> --profile localstack --endpoint-url=http://localhost:4566
+aws ses verify-email-identity --email-address <recipient@email.address> --profile localstack --endpoint-url=http://localhost:4566The application built here allows sending text emails to the recipients that are verified on AWS SES.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ses-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ses-quickstart \
+ -DclassName="org.acme.ses.QuarkusSesSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ses"
+cd amazon-ses-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SES Client extensions.
+After this, the amazon-ses extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Lets create a org.acme.ses.QuarkusSesSyncResource that will provide an API to send emails using the synchronous client.
package org.acme.ses;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesClient;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesSyncResource {
+
+ @Inject
+ SesClient ses;
+
+ @POST
+ @Path("/email")
+ public String encrypt(Email data) {
+ return ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))).messageId();
+ }
+}Both SES clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SES instance, configure it as follows:
+quarkus.ses.endpoint-override=http://localhost:4566
+
+quarkus.ses.aws.region=us-east-1
+quarkus.ses.aws.credentials.type=static
+quarkus.ses.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ses.aws.credentials.static-provider.secret-access-key=test-secretquarkus.ses.aws.region - It’s required by the client, but since you’re using a local SES instance use us-east-1 as it’s a default region of LocalStack’s SES.
quarkus.ses.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.ses.endpoint-override - Override the SES client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon SES related properties. By default, the SES client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ses.QuarkusSesAsyncResource REST resource that will be similar to our QuarkusSesSyncResource but using an asynchronous programming model.
package org.acme.ses;
+
+import io.smallrye.mutiny.Uni;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesAsyncClient;
+import software.amazon.awssdk.services.ses.model.SendEmailResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesAsyncResource {
+
+ @Inject
+ SesAsyncClient ses;
+
+ @POST
+ @Path("/email")
+ public Uni<String> encrypt(Email data) {
+ return Uni.createFrom()
+ .completionStage(
+ ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))))
+ .onItem().apply(SendEmailResponse::messageId);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SES client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Notification Service (SNS) is a highly available and fully managed pub/sub messaging service. +It provides topics for high-throughput, push-based, many-to-many messaging. Messages can fan out to a large number of subscriber endpoints for +parallel processing, including Amazon SQS queues, AWS Lambda functions, and HTTP/S webhooks. Additionally, SNS can be used +to fan out notifications to end users using mobile push, SMS and email.
+You can find more information about SNS at the Amazon SNS website.
+| + + | ++The SNS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use SNS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SNS service
+Optionally, Docker for your system to run SNS locally for testing purposes
+The easiest way to start working with SNS is to run a local instance using Dev Services.
+You can also set up a local version of SNS manually, first start a LocalStack container:
+docker run -it --publish 4566:4575 -e SERVICES=sns -e START_WEB=0 localstack/localstack:1.0.3This starts a SNS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SNS topic using AWS CLI and store in TOPIC_ARN environment variable
TOPIC_ARN=`aws sns create-topic --name=QuarksCollider --profile localstack --endpoint-url=http://localhost:4566`| + + | +
+
+
+If you are using LocalStack, some additional configuration is needed: +
+
+
+
+Otherwise your service will not receive the notifications. + |
+
If you want to run the demo using SNS on your AWS account, you can create a topic using AWS default profile
+TOPIC_ARN=`aws sns create-topic --name=QuarksCollider`The application built here allows to shoot elementary particles (quarks) into a QuarksCollider topic of the AWS SNS.
+Additionally, we create a resource that allows to subscribe to the QuarksCollider topic in order to receive published quarks.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sns-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sns-quickstart \
+ -DclassName="org.acme.sns.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sns"
+cd amazon-sns-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SNS Client extensions.
+After this, the amazon-sns extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to publish quarks. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sns.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sns.QuarksCannonSyncResource that will provide an API to shoot quarks into the SNS topic via the SNS synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ PublishResponse response = sns.publish(p -> p.topicArn(topicArn).message(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact that messages published must be simply a String we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
The missing piece is the subscriber that will receive the messages published to our topic. Before implementing subscribers, we need to define POJO classes representing messages posted by the AWS SNS.
+Let’s create two classes that represent SNS Notification and SNS Subscription Confirmation messages based on the AWS SNS Message and JSON formats
+Create org.acme.sns.model.SnsNotification class
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class SnsNotification {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signinCertUrl;
+
+ @JsonProperty("Subject")
+ private String subject;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ @JsonProperty("UnsubscribeURL")
+ private String unsubscribeURL;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigninCertUrl() {
+ return signinCertUrl;
+ }
+
+ public void setSigninCertUrl(String signinCertUrl) {
+ this.signinCertUrl = signinCertUrl;
+ }
+
+ public String getSubject() {
+ return subject;
+ }
+
+ public void setSubject(String subject) {
+ this.subject = subject;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+
+ public String getUnsubscribeURL() {
+ return unsubscribeURL;
+ }
+
+ public void setUnsubscribeURL(String unsubscribeURL) {
+ this.unsubscribeURL = unsubscribeURL;
+ }
+}Then, create org.acme.sns.SnsSubscriptionConfirmation
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class SnsSubscriptionConfirmation {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signingCertUrl;
+
+ @JsonProperty("SubscribeURL")
+ private String subscribeUrl;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("Token")
+ private String token;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigningCertUrl() {
+ return signingCertUrl;
+ }
+
+ public void setSigningCertUrl(String signingCertUrl) {
+ this.signingCertUrl = signingCertUrl;
+ }
+
+ public String getSubscribeUrl() {
+ return subscribeUrl;
+ }
+
+ public void setSubscribeUrl(String subscribeUrl) {
+ this.subscribeUrl = subscribeUrl;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getToken() {
+ return token;
+ }
+
+ public void setToken(String token) {
+ this.token = token;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+}Now, create org.acme.QuarksShieldSyncResource REST resources that:
+- Allows to subscribe itself to our SNS topic
+- Unsubscribe from the SNS topic
+- Receive notifications from the subscribed SNS topic
| + + | ++Keep in mind that AWS SNS supports multiple types of subscribers (that is web servers, email addresses, AWS SQS queues, AWS Lambda functions, and many more), but for the sake of the +quickstart we will show how to subscribe an HTTP endpoint served by our application. + | +
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.HashMap;
+import java.util.Map;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Response notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) throws JsonProcessingException {
+ if (messageType == null) {
+ return Response.status(400).build();
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ SnsNotification notification = readObject(SnsNotification.class, message);
+ Quark quark = readObject(Quark.class, notification.getMessage());
+ LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ SnsSubscriptionConfirmation subConf = readObject(SnsSubscriptionConfirmation.class, message);
+ sns.confirmSubscription(cs -> cs.topicArn(topicArn).token(subConf.getToken()));
+ LOGGER.info("Subscription confirmed. Ready for quarks collisions.");
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ } else {
+ return Response.status(400).entity("Unknown messageType").build();
+ }
+
+ return Response.ok().build();
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Response subscribe() {
+ String notificationEndpoint = notificationEndpoint();
+ SubscribeResponse response = sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint));
+ subscriptionArn = response.subscriptionArn();
+ LOGGER.infov("Subscribed Quarks shield <{0}> : {1} ", notificationEndpoint, response.subscriptionArn());
+ return Response.ok().entity(response.subscriptionArn()).build();
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Response unsubscribe() {
+ if (subscriptionArn != null) {
+ sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn));
+ LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn);
+ return Response.ok().build();
+ } else {
+ LOGGER.info("Not subscribed yet");
+ return Response.status(400).entity("Not subscribed yet").build();
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/sync/shield";
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}subscribe() endpoint subscribes to our topic by providing the URL to the POST endpoint receiving SNS notification requests.
unsubscribe() simply removes our subscription, so any messages published to the topic will not be routed to our endpoint anymore
notificationEndpoint() is called by SNS on new message if endpoint is subscribed.
+See Amazon SNS message and JSON formats for details about the format of the messages SNS can submit.
Both SNS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SNS instance, configure it as follows:
+quarkus.sns.endpoint-override=http://localhost:4566
+
+quarkus.sns.aws.region=us-east-1
+quarkus.sns.aws.credentials.type=static
+quarkus.sns.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sns.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sns.aws.region - It’s required by the client, but since you’re using a local SNS instance you can pick any valid AWS region.
quarkus.sns.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sns.endpoint-override - Override the SNS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sns.aws.region=<YOUR_REGION>
+quarkus.sns.aws.credentials.type=defaultquarkus.sns.aws.region you should set it to the region where you provisioned the SNS table,
quarkus.sns.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dtopic.arn=$TOPIC_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sns.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sns.publish(p -> p.topicArn(topicArn).message(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(PublishResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SNS client, and then transform the emitted item.
And corresponding async subscriber org.acme.sns.QuarksShieldAsyncResource
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.HashMap;
+import java.util.Map;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Uni<Response> notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) {
+ if (messageType == null) {
+ return Uni.createFrom().item(Response.status(400).build());
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsNotification.class, message))
+ .onItem().transform(notification -> readObject(Quark.class, notification.getMessage()))
+ .onItem().invoke(quark -> LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(quark -> Response.ok().build());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsSubscriptionConfirmation.class, message))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(
+ sns.confirmSubscription(confirm -> confirm.topicArn(topicArn).token(msg.getToken())))
+ )
+ .onItem().invoke(resp -> LOGGER.info("Subscription confirmed. Ready for quarks collisions."))
+ .onItem().transform(resp -> Response.ok().build());
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ return Uni.createFrom().item(Response.ok().build());
+ }
+
+ return Uni.createFrom().item(Response.status(400).entity("Unknown messageType").build());
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Uni<Response> subscribe() {
+ return Uni.createFrom()
+ .completionStage(sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint())))
+ .onItem().transform(SubscribeResponse::subscriptionArn)
+ .onItem().invoke(this::setSubscriptionArn)
+ .onItem().invoke(arn -> LOGGER.infov("Subscribed Quarks shield with id = {0} ", arn))
+ .onItem().transform(arn -> Response.ok().entity(arn).build());
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Uni<Response> unsubscribe() {
+ if (subscriptionArn != null) {
+ return Uni.createFrom()
+ .completionStage(sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn)))
+ .onItem().invoke(arn -> LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn))
+ .onItem().invoke(arn -> subscriptionArn = null)
+ .onItem().transform(arn -> Response.ok().build());
+ } else {
+ return Uni.createFrom().item(Response.status(400).entity("Not subscribed yet").build());
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/async/shield";
+ }
+
+ private void setSubscriptionArn(String arn) {
+ this.subscriptionArn = arn;
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}And we need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Queue Service (SQS) is a fully managed message queuing service. +Using SQS, you can send, store, and receive messages between software components at any volume, without losing messages or requiring other +services to be available. +SQS offers two types of message queues. Standard queues offer maximum throughput, best-effort ordering and at-least-once delivery. +SQS FIFO queues are designed to guarantee that messages are processes exactly once, on the exact order that they were sent.
+You can find more information about SQS at the Amazon SQS website.
+| + + | ++The SQS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use SQS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SQS service
+Docker for your system to run SQS locally for testing purposes
+The easiest way to start working with SQS is to run a local instance using Dev Services.
+You can optionally configure the queues that are created on startup with the quarkus.sqs.devservices.queues config property.
You can also set up a local version of SQS manually, first start a LocalStack container:
+docker run --rm --name local-sqs -p 4566:4576 -e SERVICES=sqs -e START_WEB=0 -d localstack/localstack:1.0.3This starts a SQS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SQS queue using AWS CLI and store in QUEUE_URL environment variable.
QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue --profile localstack --endpoint-url=http://localhost:4566`Or, if you want to use your SQS queue on your AWS account create a queue using your default profile
+QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue`The application built here allows shooting an elementary particles (quarks) into a ColliderQueue queue of the AWS SQS.
+Additionally, we create a resource that allows receiving those quarks from the ColliderQueue queue in the order they were sent.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sqs-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sqs-quickstart \
+ -DclassName="org.acme.sqs.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sqs"
+cd amazon-sqs-quickstartThis command generates a Maven structure importing the RESTEasy Reactive and Amazon SQS Client extensions.
+After this, the amazon-sqs extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that sends quarks via the queue. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sqs.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sqs.QuarksCannonSyncResource that will provide an API to shoot quarks into the SQS queue using the synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ SendMessageResponse response = sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact messages sent to the queue must be a String, we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
Now, create the org.acme.QuarksShieldSyncResource REST resources that provides an endpoint to read the messages from the ColliderQueue queue.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public List<Quark> receive() {
+ List<Message> messages = sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)).messages();
+
+ return messages.stream()
+ .map(Message::body)
+ .map(this::toQuark)
+ .collect(Collectors.toList());
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}We are using here a Jackson’s ObjectReader in order to deserialize queue messages into our Quark POJOs.
Both SQS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SQS instance, configure it as follows:
+quarkus.sqs.endpoint-override=http://localhost:4566
+
+quarkus.sqs.aws.region=us-east-1
+quarkus.sqs.aws.credentials.type=static
+quarkus.sqs.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sqs.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sqs.aws.region - It’s required by the client, but since you’re using a local SQS instance use us-east-1 as it’s a default region of LocalStack’s SQS.
quarkus.sqs.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sqs.endpoint-override - Override the SQS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all SQS related properties. By default, the SQS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dqueue.url=$QUEUE_URL -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sqs.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(SendMessageResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SQS client, and then transform the emitted item.
And the corresponding async receiver of the queue messages org.acme.sqs.QuarksShieldAsyncResource
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+import software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public Uni<List<Quark>> receive() {
+ return Uni.createFrom()
+ .completionStage(sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)))
+ .onItem().transform(ReceiveMessageResponse::messages)
+ .onItem().transform(m -> m.stream().map(Message::body).map(this::toQuark).collect(Collectors.toList()));
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Systems Manager (formerly Amazon Simple Systems Manager, or SSM) is a service that you can use to view and control your infrastructure on AWS. +One of the most useful features of SSM for microservices is the Parameter Store, which provides secure, hierarchical storage for configuration data management and secrets management..
+You can find more information about SSM at the AWS Systems Manager website.
+| + + | ++The SSM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use SSM locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SSM service
+Docker for your system to run SSM locally for testing purposes
+The easiest way to start working with SSM is to run a local instance using Dev Services.
+You can also set up a local version of SSM manually, first start a LocalStack container:
+docker run --rm --name local-ssm --publish 4566:4583 -e SERVICES=ssm -e START_WEB=0 -d localstack/localstack:1.0.3This starts a SSM instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve parameters using the SSM parameter store.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ssm-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ssm-quickstart \
+ -DclassName="org.acme.ssm.QuarkusSsmSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ssm"
+cd amazon-ssm-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SSM Client extensions.
+After this, the amazon-ssm extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from SSM parameter store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.ssm.QuarkusSsmResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.ssm;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import javax.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.ssm.model.GetParameterRequest;
+import software.amazon.awssdk.services.ssm.model.GetParametersByPathRequest;
+import software.amazon.awssdk.services.ssm.model.Parameter;
+import software.amazon.awssdk.services.ssm.model.ParameterType;
+import software.amazon.awssdk.services.ssm.model.PutParameterRequest;
+
+public abstract class QuarkusSsmResource {
+
+ @ConfigProperty(name = "parameters.path") (1)
+ String parametersPath;
+
+ @PostConstruct (2)
+ void normalizePath() {
+ if (!parametersPath.startsWith("/")) {
+ parametersPath = "/" + parametersPath;
+ }
+ if (!parametersPath.endsWith("/")) {
+ parametersPath = parametersPath + "/";
+ }
+ }
+
+ protected Collector<Parameter, ?, Map<String, String>> parametersToMap() { (3)
+ return toMap(p -> p.name().substring(parametersPath.length()), Parameter::value);
+ }
+
+ protected GetParametersByPathRequest generateGetParametersByPathRequest() {
+ return GetParametersByPathRequest.builder() (4)
+ .path(parametersPath)
+ .withDecryption(TRUE)
+ .build();
+ }
+
+ protected PutParameterRequest generatePutParameterRequest(String name, String value, boolean secure) {
+ return PutParameterRequest.builder() (5)
+ .name(parametersPath + name)
+ .value(value)
+ .type(secure ? ParameterType.SECURE_STRING : ParameterType.STRING)
+ .overwrite(TRUE)
+ .build();
+ }
+
+ protected GetParameterRequest generateGetParameterRequest(String name) {
+ return GetParameterRequest.builder() (6)
+ .name(parametersPath + name)
+ .withDecryption(TRUE)
+ .build();
+ }
+}| 1 | +Inject a configured path under which to store parameters | +
| 2 | +Ensure the path starts and ends with / |
+
| 3 | +Collect parameters into a map of simple names and values | +
| 4 | +Generate a request for all parameters under the configured path | +
| 5 | +Generate a request to set a specific parameter | +
| 6 | +Generate a request to get a specific parameter value | +
Now, we can extend the class and create the synchronous implementation in the org.acme.ssm.QuarkusSsmSyncResource class.
package org.acme.ssm;
+
+import java.util.Map;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import org.jboss.resteasy.reactive.RestQuery;
+
+import software.amazon.awssdk.services.ssm.SsmClient;
+
+@Path("/sync")
+public class QuarkusSsmSyncResource extends QuarkusSsmResource {
+
+ @Inject (1)
+ SsmClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Map<String, String> getParameters() {
+ return ssm.getParametersByPath(generateGetParametersByPathRequest())
+ .parameters().stream().collect(parametersToMap());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ ssm.putParameter(generatePutParameterRequest(name, value, secure));
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String getParameter(String name) {
+ return ssm.getParameter(generateGetParameterRequest(name))
+ .parameter().value();
+ }
+}| 1 | +Inject the client provided by the amazon-ssm extension | +
Using the Amazon SSM SDK, we can easily store and retrieve arbitrary name/value pairs, and we can optionally store the values in a secure manner.
+Both SSM clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SSM instance, configure it as follows:
+quarkus.ssm.endpoint-override=http://localhost:4566 (1)
+
+quarkus.ssm.aws.region=us-east-1 (2)
+quarkus.ssm.aws.credentials.type=static (3)
+quarkus.ssm.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ssm.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the SSM client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon SSM related properties. By default, the SSM client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ssm.QuarkusSsmAsyncResource REST resource that will be similar to our QuarkusSsmSyncResource but using an asynchronous programming model.
package org.acme.ssm;
+
+import java.util.Map;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import org.jboss.resteasy.reactive.RestQuery;
+import software.amazon.awssdk.services.ssm.SsmAsyncClient;
+
+@Path("/async")
+public class QuarkusSsmAsyncResource extends QuarkusSsmResource {
+
+ @Inject
+ SsmAsyncClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<Map<String, String>> getParameters() {
+ return Uni.createFrom().completionStage(ssm.getParametersByPath(generateGetParametersByPathRequest()))
+ .onItem().transform(r -> r.parameters().stream().collect(parametersToMap()));
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ return Uni.createFrom().completionStage(ssm.putParameter(generatePutParameterRequest(name, value, secure)))
+ .onItem().transform(r -> null);
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> getParameter(String name) {
+ return Uni.createFrom().completionStage(ssm.getParameter(generateGetParameterRequest(name)))
+ .onItem().transform(r -> r.parameter().value());
+ }
+}Note that the SsmAsyncClient behaves just like the SsmClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege credentials for users.
+You can find more information about STS at AWS Security Token Service API Reference.
+| + + | ++The STS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use STS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the STS service
+Docker for your system to run STS locally for testing purposes
+The easiest way to start working with STS is to run a local instance using Dev Services.
+You can also set up a local version of STS manually, first start a LocalStack container:
+docker run --rm --name local-sts --publish 4592:4592 -e SERVICES=sts -e START_WEB=0 -d localstack/localstack:1.0.3This starts a STS instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.9.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sts-quickstart \
+ -DclassName="org.acme.sts.QuarkusStsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sts"
+cd amazon-sts-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon STS Client extensions.
+After this, the amazon-sts extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both STS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local STS instance, configure it as follows:
+quarkus.sts.endpoint-override=http://localhost:4592 (1)
+
+quarkus.sts.aws.region=us-east-1 (2)
+quarkus.sts.aws.credentials.type=static (3)
+quarkus.sts.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sts.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the STS client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon STS related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Quarkus Amazon Services automatically starts a LocalStack container in dev mode and when running tests. So, you don’t have to start one manually. The extension client is configured automatically.
+Dev Services for Amazon Services is automatically enabled for each extensions added to pom.xml except in the following situations:
quarkus.devservices.enabled is set to false
devservices.enabled is set to false per extension (eg. quarkus.s3.devservices.enabled=false)
the endpoint-override is configured (eg. quarkus.s3.endpoint-override=http://localhost:4566)
Your environment does not support Docker
+By default, Dev Services for Amazon Services will start one LocalStack container with only the needed services.
+If you need to share a particular service between applications, Dev Services for Amazon Services implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single container. To ease sharing, each service will be started in its own container.
+Dev Services for Amazon Services starts the container with the quarkus-dev-service-localstack label and service name as the value, which is used to identify the container.
+If you need multiple (shared) container, you can configure the devservices.service-name attribute for a given extension (eg. quarkus.s3.devservices.services-name) and indicate the container name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is localstack.
Sharing is disabled by default in dev mode, and is always disabled in test mode. You can enable the sharing with devservices.shared=true for a given extension (e.g. quarkus.s3.devservices.shared=true). All other non-shared services will be grouped in another container.
Dev Services for Amazon Services uses localstack/localstack image. You can configure the image and version using the quarkus.aws.devservices.localstack.image-name property:
quarkus.aws.devservices.localstack.image-name=localstack/localstack:1.0.3Dev Services for Amazon Services can support specific properties sent to the container. It can be globally applied to all containers or be specified per service as follows:
+quarkus.aws.devservices.localstack.container-properties.START_WEB=0
+quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1GRefer to the LocalStack documentation for more configuration : https://docs.localstack.cloud/localstack/configuration/#local-aws-services. Note that not all environment variables are supported and some may affect Dev Services for Amazon Services.
+To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:
quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
+quarkus.aws.devservices.localstack.additional-services."redshift".enabled=trueThe key is the name of the service to enable and must be a valid LocalStack service name.
+Some extensions support additional configuration to be applied at startup. Refer to the extension documentation.
+The Cognito extension is not using LocalStack but Moto.
+Dev Services for Amazon Services uses the latest motoserver/moto image. You can configure the image and version using the quarkus.aws.devservices.moto.image-name property:
quarkus.aws.devservices.moto.image-name=motoserver/moto:3.0.2Dev Services for Amazon Services can support specific properties sent to the container as follows:
+quarkus.aws.devservices.moto.container-properties.MOTO_COGNITO_IDP_USER_POOL_ID_STRATEGY=HASHConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK.
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown.
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle.
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed.
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client.
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group.
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group.
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread.
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
This set of extensions expose AWS services through configuration properties and CDI injection.
+You can find the full set of supported services and documentation for each of them in the navigation on the left.
+Service client for accessing Amazon Cognito user pools (Identity Provider).
+Using the Amazon Cognito user pools API, you can create a user pool to manage directories and users. +You can authenticate a user to obtain tokens related to user identity and access policies.
+For more information, see the Amazon Cognito user pools (AWS Java SDK 2.x docs).
+| + + | ++The Cognito User Pools extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Cognito User Pool locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+One of:
+An AWS Account to access the Cognito service
+Or Docker for your system to run Cognito locally for testing purposes
+The easiest way to start working with Cognito is to run a local instance using Dev Services.
+You can also set up a local version of Cognito manually, first start a local instance as a container:
+docker run --rm --name moto -p 5000:5000 -d motoserver/moto:3.0.2This starts a Cognito mock instance that is accessible on port 5000.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile moto
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: testCreate a Cognito user pool using AWS CLI.
+aws --profile moto --endpoint-url=http://localhost:5000 cognito-idp create-user-pool --pool-name quarkus-users-devOr, if you want to use your Cognito user pool on your AWS account create a user pool using your default profile
+aws cognito-user-pools cognito-idp --pool-name quarkus-users-devThe application built here shows the count of Cognito User Pools in the current region.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-cognito-user-pools-quickstart \
+ -DclassName="org.acme.cognitouserpools.CognitoExampleResource" \
+ -Dpath="/cognito-example" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-cognito-user-pools,resteasy-mutiny"
+cd amazon-cognito-user-pools-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Cognito User Pool extensions.
+After this, the amazon-cognito-user-pools extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Edit a org.acme.cognitouserpools.CognitoExampleResource that will provide an API return count of Cognito User Pools using the synchronous client.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsResponse;
+
+@Path("/cognito-example")
+public class CognitoExampleResource {
+ @Inject
+ CognitoIdentityProviderClient cognitoClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ ListUserPoolsResponse response = cognitoClient.listUserPools(request);
+ return String.format("You have %d user pools", response.userPools().size());
+ }
+}And update test class:
+package org.acme.cognitouserpools;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.Test;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+
+@QuarkusTest
+public class CognitoExampleResourceTest {
+
+ @Test
+ public void testHelloEndpoint() {
+ given()
+ .when().get("/cognito-example")
+ .then()
+ .statusCode(200)
+ .body(is("You have 1 user pools"));
+ }
+
+}Both Cognito clients (sync and async) are configurable via the application.properties file that
+can be provided in the src/main/resources directory.
Additionally, you need to add to the classpath a proper implementation of the sync client.
+By default the extension uses the URL connection HTTP client, so you need to add a URL connection
+client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Cognito mock instance, configure it as follows:
+quarkus.cognito-user-pools.endpoint-override=http://localhost:5000
+
+quarkus.cognito-user-pools.aws.region=eu-west-1
+quarkus.cognito-user-pools.aws.credentials.type=static
+quarkus.cognito-user-pools.aws.credentials.static-provider.access-key-id=test-key
+quarkus.cognito-user-pools.aws.credentials.static-provider.secret-access-key=test-secretquarkus.cognito-user-pools.aws.region - It’s required by the client, but since you’re using a local Cognito mock instance use us-east-1 as it’s a default region of moto.
quarkus.cognito-user-pools.aws.credentials - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.cognito-user-pools.endpoint-override - Override the Cognito User Pools client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Cognito User Pools
+related properties. By default, the Cognito User Pools client extension will use the default
+credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.cognitouserpools.CognitoAsyncExampleResource REST resource that will be similar to our
+CognitoExampleResource but using an asynchronous programming model.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderAsyncClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+
+@Path("/cognito-async-example")
+public class CognitoAsyncExampleResource {
+ @Inject
+ CognitoIdentityProviderAsyncClient cognitoAsyncClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ return Uni
+ .createFrom()
+ .completionStage(cognitoAsyncClient.listUserPools(request))
+ .map(response -> {
+ return String.format("You have %d user pools", response.userPools().size());
+ });
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous Cognito
+Identity Provider client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+DynamoDB is a scalable AWS managed NoSQL database. +It supports both key-value and document data models, that enables to have a flexible schema for your data. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about DynamoDB at the Amazon DynamoDB website.
+| + + | ++The DynamoDB extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). +Keep in mind it’s actively developed and does not support yet all the features available in SDK 1.x such as Document APIs + | +
The Quarkus extension supports the traditional DynamoDB client as well as the enhanced client.
+It supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the DynamoDB service
+Optionally, Docker for your system to run DynamoDB locally for testing purposes
+The easiest way to start working with DynamoDB is to run a local instance using Dev Services.
+You can also set up a local version of DynamoDB manually, first start a local instance as a container:
+docker run --publish 4566:8000 amazon/dynamodb-local:1.19.0 -jar DynamoDBLocal.jar -inMemory -sharedDbThis starts a DynamoDB instance that is accessible on port 4566.
+You can check if it’s working with aws dynamodb list-tables --endpoint-url http://localhost:4566.
{
+ "TableNames": []
+}You should see the output above in your terminal. That’s it, DynamoDB runs locally.
+Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.
+Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. +For more information, see Setting Up DynamoDB (Web Service).
+We recommend to use the AWS CLI to provision the table:
+The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-dynamodb-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-dynamodb-quickstart \
+ -DclassName="org.acme.dynamodb.FruitResource" \
+ -Dpath="/fruits" \
+ -Dextensions="resteasy-reactive-jackson,amazon-dynamodb"
+cd amazon-dynamodb-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and DynamoDB Client extensions.
+After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Fruit bean as follows:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ public static Fruit from(Map<String, AttributeValue> item) {
+ Fruit fruit = new Fruit();
+ if (item != null && !item.isEmpty()) {
+ fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
+ fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
+ }
+ return fruit;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map
+object provided by the DynamoDB client response.
Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.
package org.acme.dynamodb;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.ScanRequest;
+
+public abstract class AbstractService {
+
+ public final static String FRUIT_NAME_COL = "fruitName";
+ public final static String FRUIT_DESC_COL = "fruitDescription";
+ public final static String FRUIT_TABLE_NAME = "QuarkusFruits";
+
+ protected ScanRequest scanRequest() {
+ return ScanRequest.builder().tableName(FRUIT_TABLE_NAME)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
+ }
+
+ protected PutItemRequest putRequest(Fruit fruit) {
+ Map<String, AttributeValue> item = new HashMap<>();
+ item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
+ item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());
+
+ return PutItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .item(item)
+ .build();
+ }
+
+ protected GetItemRequest getRequest(String name) {
+ Map<String, AttributeValue> key = new HashMap<>();
+ key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());
+
+ return GetItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .key(key)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
+ .build();
+ }
+}Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ DynamoDbClient dynamoDB;
+
+ public List<Fruit> findAll() {
+ return dynamoDB.scanPaginator(scanRequest()).items().stream()
+ .map(Fruit::from)
+ .collect(Collectors.toList());
+ }
+
+ public void add(Fruit fruit) {
+ dynamoDB.putItem(putRequest(fruit));
+ }
+
+ public Fruit get(String name) {
+ return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
+ }
+}Now, edit the org.acme.dynamodb.FruitResource class as follows:
package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/fruits")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class FruitResource {
+
+ @Inject
+ FruitSyncService service;
+
+ @GET
+ public List<Fruit> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Fruit getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public List<Fruit> add(Fruit fruit) {
+ service.add(fruit);
+ return getAll();
+ }
+}The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.
DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local DynamoDB instance, configure it as follows:
+quarkus.dynamodb.endpoint-override=http://localhost:4566
+
+quarkus.dynamodb.aws.region=eu-central-1
+quarkus.dynamodb.aws.credentials.type=static
+quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
+quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secretquarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.
quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.dynamodb.aws.region=<YOUR_REGION>
+quarkus.dynamodb.aws.credentials.type=defaultquarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,
quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ @Inject
+ DynamoDbAsyncClient dynamoDB;
+
+ public Uni<List<Fruit>> findAll() {
+ return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
+ .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
+ }
+
+ public Uni<Void> add(Fruit fruit) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit))).replaceWithVoid();
+ }
+
+ public Uni<Fruit> get(String name) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
+ .onItem().transform(resp -> Fruit.from(resp.item()));
+ }
+}In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.
Then, create an asynchronous REST resource that consumes this async service:
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+import io.smallrye.mutiny.Uni;
+
+@Path("/async-fruits")
+public class FruitAsyncResource {
+
+ @Inject
+ FruitAsyncService service;
+
+ @GET
+ public Uni<List<Fruit>> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Uni<Fruit> getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public Uni<List<Fruit>> add(Fruit fruit) {
+ return service.add(fruit)
+ .onItem().ignore().andSwitchTo(this::getAll);
+ }
+}And add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.dynamodb.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>The DynamoDB enhanced client is part of the AWS SDK for Java version 2 and makes the mapping between DynamoDB Tables and Java beans very easy.
+The Enhanced Client requires a TableSchema which can be generated from a bean class annotated with DynamoDbBean or DynamoDbImmutable or generated from code.
+By default, TableSchemas generated from bean classes are registered and cached at startup. You don’t need to explicitely instantiate them at class-load time.
+It has both a sync and an async variants.
To use the enhanced client, add the quarkus-amazon-dynamodb-enhanced extension to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-dynamodb-enhanced</artifactId>
+</dependency>The Fruit bean would look like this:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+@DynamoDbBean
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ @DynamoDbPartitionKey
+ @DynamoDbAttribute(AbstractService.FRUIT_NAME_COL)
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ @DynamoDbAttribute(AbstractService.FRUIT_DESC_COL)
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}Note that you don’t need to add @RegisterForReflection anymore.
The FruitSyncService would need to use the DynamoDbEnhancedClient as well as create a TableSchema:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ private DynamoDbTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedSyncService(DynamoDbEnhancedClient dynamoEnhancedClient) {
+ fruitTable = dynamoEnhancedClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}The same goes for the asynchronous version with DynamoDbEnhanceAsyncdClient:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedAsyncService(DynamoDbEnhancedAsyncClient dynamoEnhancedAsyncClient) {
+ fruitTable = dynamoEnhancedAsyncClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}Resource classes remain unchanged.
+Alternatively, if you only need to use the DynamoDbTable instance, you can inject it directly with a @NamedDynamoDbTable annotation.
The synchronous version would be :
+package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ DynamoDbTable<Fruit> fruitTable;
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}And the asynchronous version :
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitEnhancedAsyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}You can find more information about the DynamoDB enhanced client in the AWS documentation:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Amazon EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources.
+You can find more information about EventBridge at AWS EventBridge Data Streams Service API Reference.
+| + + | ++The EventBridge extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use EventBridge locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the EventBridge service
+Docker for your system to run EventBridge locally for testing purposes
+The easiest way to start working with EventBridge is to run a local instance using Dev Services.
+You can also set up a local version of EventBridge manually, first start a LocalStack container:
+docker run --rm --name local-eventbridge --publish 4592:4592 -e SERVICES=events -e START_WEB=0 -d localstack/localstack:3.0.1This starts a EventBridge instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-eventbridge-quickstart \
+ -DclassName="org.acme.eventbridge.QuarkusEventBridgeSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-eventbridge"
+cd amazon-eventbridge-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon EventBridge Client extensions.
+After this, the amazon-eventbridge extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both EventBridge clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.eventbridge.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.eventbridge.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local EventBridge instance, configure it as follows:
+quarkus.eventbridge.endpoint-override=http://localhost:4592 (1)
+
+quarkus.eventbridge.aws.region=us-east-1 (2)
+quarkus.eventbridge.aws.credentials.type=static (3)
+quarkus.eventbridge.aws.credentials.static-provider.access-key-id=test-key
+quarkus.eventbridge.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the EventBridge client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon EventBridge related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.eventbridge.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Identity and Access Management (IAM) enables users to manage access to AWS services and resources securely.
+You can find more information about IAM at the Amazon IAM website.
+| + + | ++The IAM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Kinesis Data Streams is a managed service provided by Amazon Web Services (AWS) that scales elastically for real-time processing of streaming big data.
+You can find more information about Kinesis at AWS Kinesis Data Streams Service API Reference.
+| + + | ++The Kinesis extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use Kinesis locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Kinesis service
+Docker for your system to run Kinesis locally for testing purposes
+The easiest way to start working with Kinesis is to run a local instance using Dev Services.
+You can also set up a local version of Kinesis manually, first start a LocalStack container:
+docker run --rm --name local-kinesis --publish 4592:4592 -e SERVICES=kinesis -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Kinesis instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kinesis-quickstart \
+ -DclassName="org.acme.kinesis.QuarkusKinesisSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kinesis"
+cd amazon-kinesis-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon Kinesis Client extensions.
+After this, the amazon-kinesis extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both Kinesis clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.kinesis.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kinesis.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Kinesis instance, configure it as follows:
+quarkus.kinesis.endpoint-override=http://localhost:4592 (1)
+
+quarkus.kinesis.aws.region=us-east-1 (2)
+quarkus.kinesis.aws.credentials.type=static (3)
+quarkus.kinesis.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kinesis.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Kinesis client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Kinesis related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kinesis.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Key Management Service (KMS) is a service that allows you to create and control the keys used to encrypt or digitally sign your data. +Using KMS, you can create and manage cryptographic keys and control their use across a wide range of AWS services and in your application.
+You can find more information about KMS at the AWS KMS website.
+| + + | ++The KMS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use KMS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the KMS service
+Docker for your system to run KMS locally for testing purposes
+The easiest way to start working with KMS is to run a local instance using Dev Services.
+You can also set up a local version of KMS manually, first start a LocalStack container:
+docker run --rm --name local-kms --publish 4566:4599 -e SERVICES=kms -e START_WEB=0 -d localstack/localstack:3.0.1This starts a KMS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a KMS master key queue using AWS CLI and store in MASTER_KEY_ARN environment variable.
MASTER_KEY_ARN=`aws kms create-key --profile localstack --endpoint-url=http://localhost:4566 | cut -f3`Generate a key data as 256-bit symmetric key (AES 256)
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256 --profile localstack --endpoint-url=http://localhost:4566Or, if you want to use your AWS account create a key using your default profile
+MASTER_KEY_ARN=`aws kms create-key | cut -f3`
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256The application built here allows to encrypt and decrypt text messages using a master key created on AWS KMS.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-kms-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kms-quickstart \
+ -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kms"
+cd amazon-kms-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon KMS Client extensions.
+After this, the amazon-kms extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to encrypt and decrypt text message provided in the request. +The example application will demonstrate the two programming models supported by the extension.
+Let’s create a org.acme.kms.QuarkusKmsSyncResource that will provide an API to encrypt and decrypt message using the synchronous client.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsSyncResource {
+
+ @Inject
+ KmsClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public String encrypt(String data) {
+ SdkBytes encryptedBytes = kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))).ciphertextBlob();
+
+ return Base64.getEncoder().encodeToString(encryptedBytes.asByteArray());
+ }
+
+ @POST
+ @Path("/decrypt")
+ public String decrypt(String data) {
+ SdkBytes encryptedData = SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes()));
+ DecryptResponse decrypted = kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(encryptedData));
+
+ return decrypted.plaintext().asUtf8String();
+ }
+}An encrypted message is in the form of a bytes array. To return it to the user we need to encode it as Base64 string in the encrypt endpoint.
+On the decrypt endpoint we need to decode from the Base64 string back to the bytes array before sending it out to the KMS client.
Both KMS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local KMS instance, configure it as follows:
+quarkus.kms.endpoint-override=http://localhost:4566
+
+quarkus.kms.aws.region=us-east-1
+quarkus.kms.aws.credentials.type=static
+quarkus.kms.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kms.aws.credentials.static-provider.secret-access-key=test-secretquarkus.kms.aws.region - It’s required by the client, but since you’re using a local KMS instance use us-east-1 as it’s a default region of LocalStack’s KMS.
quarkus.kms.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.kms.endpoint-override - Override the KMS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon KMS related properties. By default, the KMS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dkey.arn=$MASTER_KEY_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.kms.QuarkusKmsAsyncResource REST resource that will be similar to our QuarkusKmsSyncResource but using an asynchronous programming model.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsAsyncClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+import software.amazon.awssdk.services.kms.model.EncryptResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsAsyncResource {
+
+ @Inject
+ KmsAsyncClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public Uni<String> encrypt(String data) {
+ return Uni.createFrom().completionStage(kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))))
+ .onItem().transform(EncryptResponse::ciphertextBlob)
+ .onItem().transform(blob -> Base64.getEncoder().encodeToString(blob.asByteArray()));
+ }
+
+ @POST
+ @Path("/decrypt")
+ public Uni<String> decrypt(String data) {
+ return Uni.createFrom().item(SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes())))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg)))
+ )
+ .onItem().transform(DecryptResponse::plaintext)
+ .onItem().transform(SdkBytes::asUtf8String);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous KMS client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kms.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Service client for accessing Amazon Lambda.
+Using the Amazon Lambda API, you can manage your AWS Lambdas.
+You can find more information about Lambda at the AWS Lambda website.
+| + + | ++The Lambda extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Lambda locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Lambda service
+Docker for your system to run Lambda locally for testing purposes
+The easiest way to start working with Lambda is to run a local instance using Dev Services.
+You can also set up a local version of Lambda manually, first start a LocalStack container:
+docker run --rm --name local-lambda --publish 4566:4583 -e SERVICES=lambda -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Lambda instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-lambda-quickstart \
+ -DclassName="org.acme.lambda.QuarkusLambdaSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-lambda"
+cd amazon-lambda-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon Lambda Client extensions.
+After this, the amazon-lambda extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both Lambda clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.lambda.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.lambda.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Lambda instance, configure it as follows:
+quarkus.lambda.endpoint-override=http://localhost:4566 (1)
+
+quarkus.lambda.aws.region=us-east-1 (2)
+quarkus.lambda.aws.credentials.type=static (3)
+quarkus.lambda.aws.credentials.static-provider.access-key-id=test-key
+quarkus.lambda.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Lambda client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Lambda related properties. By default, the Lambda client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.lambda.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon S3 is an object storage service. It can be employed to store any type of object which allows for uses like storage for Internet applications, +backup and recovery, disaster recovery, data archives, data lakes for analytics, any hybrid cloud storage. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about S3 at the Amazon S3 website.
+| + + | ++The S3 extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use S3 locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the S3 service. Before you can use the AWS SDKs with Amazon S3, you must get an AWS access key ID and secret access key.
+Optionally, Docker for your system to run S3 locally for testing purposes
+The easiest way to start working with S3 is to run a local instance using Dev Services.
+You can optionally configure the buckets that are created on startup with the quarkus.s3.devservices.buckets config property.
You can also setup a local version of S3 manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=s3 -e START_WEB=0 localstack/localstack:3.0.1This starts a S3 instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to manage files stored in Amazon S3.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-s3-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-s3-quickstart \
+ -DclassName="org.acme.s3.S3SyncClientResource" \
+ -Dpath="/s3" \
+ -Dextensions="resteasy-reactive-jackson,amazon-s3"
+cd amazon-s3-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and S3 Client extensions.
+After this, the amazon-s3 extension has been added to your pom.xml.
| + + | +
+The default setting for quarkus.http.limits.max-body-size is 10240K. This may limit your ability to upload multipart files larger than the default. If you want to upload larger files, you will need to set this limit explicitly.
+ |
+
In this example, we will create an application to manage a list of files. The example application will demonstrate the two programming models supported by the extension.
+Because the primary goal of our application is to upload a file into the S3 bucket, we need to setup the model we will be using to define the multipart/form-data payload,
+in the form of a @MultipartForm POJO.
Create a org.acme.s3.FormData class as follows:
package org.acme.s3;
+
+import java.io.File;
+import jakarta.ws.rs.core.MediaType;
+import org.jboss.resteasy.reactive.PartType;
+import org.jboss.resteasy.reactive.RestForm;
+
+public class FormData {
+
+ @RestForm("file")
+ public File data;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String filename;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String mimetype;
+
+}The class defines three fields:
+data that fill capture stream of uploaded bytes from the client
fileName that captures a filename as provided by the submited form
mimeType content type of the uploaded file
In the second step let’s create a bean that will represent a file in a Amazon S3 bucket as follows:
+package org.acme.s3;
+
+import software.amazon.awssdk.services.s3.model.S3Object;
+
+public class FileObject {
+ private String objectKey;
+
+ private Long size;
+
+ public FileObject() {
+ }
+
+ public static FileObject from(S3Object s3Object) {
+ FileObject file = new FileObject();
+ if (s3Object != null) {
+ file.setObjectKey(s3Object.key());
+ file.setSize(s3Object.size());
+ }
+ return file;
+ }
+
+ public String getObjectKey() {
+ return objectKey;
+ }
+
+ public Long getSize() {
+ return size;
+ }
+
+ public FileObject setObjectKey(String objectKey) {
+ this.objectKey = objectKey;
+ return this;
+ }
+
+ public FileObject setSize(Long size) {
+ this.size = size;
+ return this;
+ }
+}Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the S3Object
+object provided by the S3 client response when listing all the objects in a bucket.
Now create a org.acme.s3.CommonResource that will consist of methods to prepare S3 request to get object from a S3 bucket, or to put file into a S3 bucket.
+Note a configuration property bucket.name is defined here as the request method required name of the S3 bucket.
package org.acme.s3;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+
+abstract public class CommonResource {
+
+ @ConfigProperty(name = "bucket.name")
+ String bucketName;
+
+ protected PutObjectRequest buildPutRequest(FormData formData) {
+ return PutObjectRequest.builder()
+ .bucket(bucketName)
+ .key(formData.filename)
+ .contentType(formData.mimetype)
+ .build();
+ }
+
+ protected GetObjectRequest buildGetRequest(String objectKey) {
+ return GetObjectRequest.builder()
+ .bucket(bucketName)
+ .key(objectKey)
+ .build();
+ }
+
+}Then, create a org.acme.s3.S3SyncClientResource that will provides an API to upload/download files as well as to list all the files in a bucket.
package org.acme.s3;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.ResponseBuilder;
+import jakarta.ws.rs.core.Response.Status;
+import software.amazon.awssdk.core.ResponseBytes;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectResponse;
+
+
+@Path("/s3")
+public class S3SyncClientResource extends CommonResource {
+ @Inject
+ S3Client s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Response uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ PutObjectResponse putResponse = s3.putObject(buildPutRequest(formData),
+ RequestBody.fromFile(formData.data));
+ if (putResponse != null) {
+ return Response.ok().status(Status.CREATED).build();
+ } else {
+ return Response.serverError().build();
+ }
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public Response downloadFile(String objectKey) {
+ ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(buildGetRequest(objectKey));
+ ResponseBuilder response = Response.ok(objectBytes.asUtf8String());
+ response.header("Content-Disposition", "attachment;filename=" + objectKey);
+ response.header("Content-Type", objectBytes.response().contentType());
+ return response.build();
+ }
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public List<FileObject> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder().bucket(bucketName).build();
+
+ //HEAD S3 objects to get metadata
+ return s3.listObjects(listRequest).contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}Both S3 clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
| + + | +
+You need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+add a URL connection client dependency to the pom.xml file:
+ |
+
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>For asynchronous client refer to Going asynchronous for more information.
+If you’re going to use a local S3 instance, configure it as follows:
+quarkus.s3.endpoint-override=http://localhost:4566
+
+quarkus.s3.aws.region=us-east-1
+quarkus.s3.aws.credentials.type=static
+quarkus.s3.aws.credentials.static-provider.access-key-id=test-key
+quarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret
+
+bucket.name=quarkus.s3.quickstartquarkus.s3.aws.region - It’s required by the client, but since you’re using a local S3 instance you can pick any valid AWS region.
quarkus.s3.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.s3.endpoint-override - Override the S3 client to use a local instance instead of an AWS service
bucket.name - Name of the S3 bucket
If you want to work with an AWS account, you’d need to set it with:
+bucket.name=<your-bucket-name>
+
+quarkus.s3.aws.region=<YOUR_REGION>
+quarkus.s3.aws.credentials.type=defaultbucket.name - name of the S3 bucket on your AWS account.
quarkus.s3.aws.region you should set it to the region where your S3 bucket was created,
quarkus.s3.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Now let’s add a simple web page to interact with our S3SyncClientResource.
+Quarkus automatically serves static resources located under the META-INF/resources directory.
+In the src/main/resources/META-INF/resources directory, add a s3.html file with the content from this s3.html file in it.
You can now interact with your REST service:
+start Quarkus with ./mvnw compile quarkus:dev
open a browser to http://localhost:8080/s3.html
upload new file to the current S3 bucket via the form and see the list of files in the bucket
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.s3.S3AsyncClientResource that will be similar to our S3SyncClientResource but using an asynchronous programming model.
package org.acme.s3;
+
+import java.nio.ByteBuffer;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.Status;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+
+import org.jboss.resteasy.reactive.RestMulti;
+import org.reactivestreams.Publisher;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import io.vertx.core.buffer.Buffer;
+import software.amazon.awssdk.core.async.AsyncRequestBody;
+import software.amazon.awssdk.core.async.AsyncResponseTransformer;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.ListObjectsResponse;
+
+@Path("/async-s3")
+public class S3AsyncClientResource extends CommonResource {
+ @Inject
+ S3AsyncClient s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Uni<Response> uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ return Uni.createFrom()
+ .completionStage(() -> {
+ return s3.putObject(buildPutRequest(formData), AsyncRequestBody.fromFile(formData.data));
+ })
+ .onItem().ignore().andSwitchTo(Uni.createFrom().item(Response.created(null).build()))
+ .onFailure().recoverWithItem(th -> {
+ th.printStackTrace();
+ return Response.serverError().build();
+ });
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public RestMulti<Buffer> downloadFile(String objectKey) {
+
+ return RestMulti.fromUniResponse(Uni.createFrom()
+ .completionStage(() -> s3.getObject(buildGetRequest(objectKey),
+ AsyncResponseTransformer.toPublisher())),
+ response -> Multi.createFrom().safePublisher(AdaptersToFlow.publisher((Publisher<ByteBuffer>) response))
+ .map(S3AsyncClientResource::toBuffer),
+ response -> Map.of("Content-Disposition", List.of("attachment;filename=" + objectKey), "Content-Type",
+ List.of(response.response().contentType())));
+ }
+
+ @GET
+ public Uni<List<FileObject>> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder()
+ .bucket(bucketName)
+ .build();
+
+ return Uni.createFrom().completionStage(() -> s3.listObjects(listRequest))
+ .onItem().transform(result -> toFileItems(result));
+ }
+
+ private static Buffer toBuffer(ByteBuffer bytebuffer) {
+ byte[] result = new byte[bytebuffer.remaining()];
+ bytebuffer.get(result);
+ return Buffer.buffer(result);
+ }
+
+ private List<FileObject> toFileItems(ListObjectsResponse objects) {
+ return objects.contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.s3.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you want to use the AWS CRT-based S3 client, add the io.quarkus.amazon.s3.runtime.S3Crt qualifier as follows:
@Inject
+@S3Crt
+S3AsyncClient s3;And add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Amazon S3 Transfer Manager is high-level file transfer utility based on the S3 client. The extension provides functionality that allows to use S3TransferManager when running in Quarkus.
+You can find more information about S3 Transfer Manager at the Amazon S3 website.
S3 Transfer Manager and the Quarkus extension supports only Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client, or AWS CRT-based S3 client.
S3 Transfer Manager share the same configuration as S3 asynchronous client. See above to configure an S3AsyncClient.
If you want to use S3 Transfer Manager, configure an S3AsyncClient`with the desired HTTP client library and simply inject an instance of `S3TransferManager:
// Netty or AWS CRT-based HTTP client
+@Inject
+S3TransferManager transferManager;
+
+// or AWS CRT-based S3 client
+@Inject
+@S3Crt
+S3TransferManager transferManager;And add the following dependency to the application pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-s3-transfer-manager</artifactId>
+</dependency>You can then make call
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Configure the starting buffer size the client will use to buffer the parts downloaded from S3. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the maximum number of S3 connections that should be established during a transfer. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the minimum part size for transfer parts. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The target throughput for transfer requests. +
+
+Environment variable: |
+double |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Secrets Manager enables you to replace hardcoded credentials in your code, including passwords, with an API call to Secrets Manager to retrieve the secret programmatically. +This helps ensure the secret can’t be compromised by someone examining your code, because the secret no longer exists in the code.
+You can find more information about Secrets Manager at the AWS Secrets Manager website.
+| + + | ++The Secrets Manager extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Secrets Manager locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Secrets Manager service
+Docker for your system to run Secrets Manager locally for testing purposes
+The easiest way to start working with Secrets Manager is to run a local instance using Dev Services.
+You can also set up a local version of Secrets Manager manually, first start a LocalStack container:
+docker run --rm --name local-secrets-manager --publish 4566:4584 -e SERVICES=secretsmanager -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Secrets Manager instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve credentials using Secrets Manager.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-secretsmanager-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-secretsmanager-quickstart \
+ -DclassName="org.acme.secretsmanager.QuarkusSecretsManagerSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-secretsmanager,resteasy-mutiny"
+cd amazon-secretsmanager-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Secrets Manager Client extensions.
+After this, the amazon-secretsmanager extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from Secrets Manager store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.secretsmanager.QuarkusSecretsManagerResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.secretsmanager;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.secretsmanager.model.CreateSecretRequest;
+import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueRequest;
+
+public abstract class QuarkusSecretsManagerResource {
+ public static final String VERSION_STAGE = "AWSCURRENT";
+
+ @ConfigProperty(name = "secret.name") (1)
+ String secretName;
+
+ protected GetSecretValueRequest generateGetSecretValueRequest() {
+ return GetSecretValueRequest.builder() (2)
+ .secretId(secretName)
+ .versionStage(VERSION_STAGE)
+ .build();
+ }
+
+ protected CreateSecretRequest generateCreateSecretRequest(String name, String secret) {
+ return CreateSecretRequest.builder() (3)
+ .name(name)
+ .secretString(secret)
+ .build();
+ }
+
+}| 1 | +Inject a configured name under which is stored the secret | +
| 2 | +Generate a request for the credentials with the configured name | +
| 3 | +Generate a request to create a specific secret | +
Now, we can extend the class and create the synchronous implementation in the org.acme.secretsmanager.QuarkusSecretsManagerSyncResource class.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerClient;
+
+@Path("/sync")
+public class QuarkusSecretsManagerSyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject (1)
+ SecretsManagerClient secretsManagerClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public String getSecret() {
+ return secretsManagerClient.getSecretValue(generateGetSecretValueRequest()).secretString();
+ }
+
+ @POST
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void createSecret(String name, String value) {
+ secretsManagerClient.createSecret(generateCreateSecretRequest(name, secret));
+ }
+
+}| 1 | +Inject the client provided by the amazon-secretsmanager extension | +
Using the Amazon Secrets Manager SDK, we can easily store and retrieve secrets.
+Both Secrets Manager clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Secrets Manager instance, configure it as follows:
+quarkus.secretsmanager.endpoint-override=http://localhost:4566 (1)
+
+quarkus.secretsmanager.aws.region=us-east-1 (2)
+quarkus.secretsmanager.aws.credentials.type=static (3)
+quarkus.secretsmanager.aws.credentials.static-provider.access-key-id=test-key
+quarkus.secretsmanager.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Secret Manager client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Secrets Manager related properties. By default, the Secrets Manager client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.secretsmanager.QuarkusSecretsManagerAsyncResource REST resource that will be similar to our QuarkusSecretsManagerSyncResource but using an asynchronous programming model.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerAsyncClient;
+
+@Path("/async")
+public class QuarkusSecretsManagerAsyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject
+ SecretsManagerAsyncClient secretsManagerAsyncClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<String> getSecret() {
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.getSecretValue(generateGetSecretValueRequest()))
+ .onItem().transform(r -> r.secretString());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> createSecret(String name, String value) {
+
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.createSecret(generateCreateSecretRequest(name, secret)))
+ .onItem().transform(r -> null);
+ }
+
+}Note that the SecretsManagerAsyncClient behaves just like the SecretsManagerClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.secretsmanager.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Email Service (SES) is a flexible and highly-scalable email sending and receiving service. +Using SES, you can send emails with any type of correspondence. You can find more information about SES at the Amazon SES website.
+| + + | ++The SES extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SES locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SES service
+Docker for your system to run SES locally for testing purposes
+The easiest way to start working with SES is to run a local instance using Dev Services. +However, local instance of SES is only mocks the SES APIs without the actual email sending capabilities. You can still use it for this guide to verify an API communication or integration test purposes.
+You can also set up a local version of SES manually, first start a LocalStack container:
+docker run --rm --name local-ses -p 4566:4579 -e SERVICES=ses -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SES instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textAmazon applies certain restrictions to new Amazon SES accounts, mainly to prevent fraud and abuse. All new accounts are in the Amazon SES sandbox. +All the features of the Amazon SES are still available while in sandbox, but a following restrictions applies: +- You can send mail to verified email addresses and domains or to the Amazon SES mailbox simulator +- You can only send mail from verified email addresses and domains +- You can send a maximum of 1 message per second.
+Going production, you’d need to get your account of the sandbox following the Amazon procedure.
+We assume you are going to use AWS SES sandbox for the sake of this guide. But before sending any email, you must verify sender and recipient email addresses using AWS CLI. +You can use your personal email or any temporary email service available if you wish.
+aws ses verify-email-identity --email-address <sender@email.address>
+aws ses verify-email-identity --email-address <recipient@email.address>Now, you need to open a mailboxes of those email addresses in order to follow confirmation procedure. Once email is approved you can use it in your application.
+If you are using local SES you still need to verify email addresses, otherwise your send email in order to let local SES accepting your request. +However, no emails to be send as it only mocks the service APIs.
+aws ses verify-email-identity --email-address <sender@email.address> --profile localstack --endpoint-url=http://localhost:4566
+aws ses verify-email-identity --email-address <recipient@email.address> --profile localstack --endpoint-url=http://localhost:4566The application built here allows sending text emails to the recipients that are verified on AWS SES.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ses-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ses-quickstart \
+ -DclassName="org.acme.ses.QuarkusSesSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ses"
+cd amazon-ses-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SES Client extensions.
+After this, the amazon-ses extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Lets create a org.acme.ses.QuarkusSesSyncResource that will provide an API to send emails using the synchronous client.
package org.acme.ses;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesClient;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesSyncResource {
+
+ @Inject
+ SesClient ses;
+
+ @POST
+ @Path("/email")
+ public String encrypt(Email data) {
+ return ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))).messageId();
+ }
+}Both SES clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SES instance, configure it as follows:
+quarkus.ses.endpoint-override=http://localhost:4566
+
+quarkus.ses.aws.region=us-east-1
+quarkus.ses.aws.credentials.type=static
+quarkus.ses.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ses.aws.credentials.static-provider.secret-access-key=test-secretquarkus.ses.aws.region - It’s required by the client, but since you’re using a local SES instance use us-east-1 as it’s a default region of LocalStack’s SES.
quarkus.ses.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.ses.endpoint-override - Override the SES client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon SES related properties. By default, the SES client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ses.QuarkusSesAsyncResource REST resource that will be similar to our QuarkusSesSyncResource but using an asynchronous programming model.
package org.acme.ses;
+
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesAsyncClient;
+import software.amazon.awssdk.services.ses.model.SendEmailResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesAsyncResource {
+
+ @Inject
+ SesAsyncClient ses;
+
+ @POST
+ @Path("/email")
+ public Uni<String> encrypt(Email data) {
+ return Uni.createFrom()
+ .completionStage(
+ ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))))
+ .onItem().apply(SendEmailResponse::messageId);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SES client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ses.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon AWS Step Functions (SFN) is a cloud service that enables you to coordinate and automate the execution of multiple AWS services in a serverless workflow. +It allows you to design, visualize, and execute workflows using a state machine architecture. +With SFN, you can seamlessly integrate various AWS services, including Lambda functions, Amazon S3, Amazon DynamoDB, and others, into a cohesive and scalable workflow.
+You can find more information about SFN at the Amazon SFN website.
+| + + | ++The SFN extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SFN locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SFN service
+Optionally, Docker for your system to run SFN locally for testing purposes
+The easiest way to start working with SFN is to run a local instance using Dev Services.
+You can also set up a local version of SFN manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=stepfunctions -e START_WEB=0 localstack/localstack:3.0.1This starts a SFN instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SFN state machine using AWS CLI and store the state machine ARN in a STATE_MACHINE_ARN variable:
STATE_MACHINE_ARN=$(aws stepfunctions create-state-machine --definition "{\
+ \"Comment\": \"A Hello World example of the Amazon States Language using a Pass state\",\
+ \"StartAt\": \"HelloWorld\",\
+ \"States\": {\
+ \"HelloWorld\": {\
+ \"Type\": \"Pass\",\
+ \"End\": true\
+ }\
+ }}" --name "HelloWorld" --role-arn "arn:aws:iam::012345678901:role/DummyRole" --endpoint-url http://localhost:4566 --profile localstack --query stateMachineArn --output text)Start an execution using the ARN of the state machine you created and store the execution ARN in a EXECUTION_ARN variable:
EXECUTION_ARN=$(aws stepfunctions start-execution --state-machine-arn "$STATE_MACHINE_ARN" --endpoint-url http://localhost:4566 --profile localstack --query executionArn --output text)Finally, get the information about the state machine execution:
+aws stepfunctions describe-execution --execution-arn "$EXECUTION_ARN" --endpoint-url http://localhost:4566 --profile localstackFirst, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sfn-quickstart \
+ -DclassName="org.acme.sfn.QuarkusSfnSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sfn"
+cd amazon-sfn-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SFN Client extensions.
+After this, the amazon-sfn extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both SFN clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default, the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sfn.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sfn.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SFN instance, configure it as follows:
+quarkus.sfn.endpoint-override=http://localhost:4566
+
+quarkus.sfn.aws.region=us-east-1
+quarkus.sfn.aws.credentials.type=static
+quarkus.sfn.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sfn.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sfn.aws.region - It’s required by the client, but since you’re using a local SFN instance you can pick any valid AWS region.
quarkus.sfn.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sfn.endpoint-override - Override the SFN client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sfn.aws.region=<YOUR_REGION>
+quarkus.sfn.aws.credentials.type=defaultquarkus.sfn.aws.region you should set it to the region where you provisioned the SFN state machine,
quarkus.sfn.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sfn.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Notification Service (SNS) is a highly available and fully managed pub/sub messaging service. +It provides topics for high-throughput, push-based, many-to-many messaging. Messages can fan out to a large number of subscriber endpoints for +parallel processing, including Amazon SQS queues, AWS Lambda functions, and HTTP/S webhooks. Additionally, SNS can be used +to fan out notifications to end users using mobile push, SMS and email.
+You can find more information about SNS at the Amazon SNS website.
+| + + | ++The SNS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SNS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SNS service
+Optionally, Docker for your system to run SNS locally for testing purposes
+The easiest way to start working with SNS is to run a local instance using Dev Services.
+You can also set up a local version of SNS manually, first start a LocalStack container:
+docker run -it --publish 4566:4575 -e SERVICES=sns -e START_WEB=0 localstack/localstack:3.0.1This starts a SNS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SNS topic using AWS CLI and store in TOPIC_ARN environment variable
TOPIC_ARN=`aws sns create-topic --name=QuarksCollider --profile localstack --endpoint-url=http://localhost:4566`| + + | +
+
+
+If you are using LocalStack, some additional configuration is needed: +
+
+
+
+Otherwise your service will not receive the notifications. + |
+
If you want to run the demo using SNS on your AWS account, you can create a topic using AWS default profile
+TOPIC_ARN=`aws sns create-topic --name=QuarksCollider`The application built here allows to shoot elementary particles (quarks) into a QuarksCollider topic of the AWS SNS.
+Additionally, we create a resource that allows to subscribe to the QuarksCollider topic in order to receive published quarks.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sns-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sns-quickstart \
+ -DclassName="org.acme.sns.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sns"
+cd amazon-sns-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SNS Client extensions.
+After this, the amazon-sns extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to publish quarks. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sns.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sns.QuarksCannonSyncResource that will provide an API to shoot quarks into the SNS topic via the SNS synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ PublishResponse response = sns.publish(p -> p.topicArn(topicArn).message(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact that messages published must be simply a String we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
The missing piece is the subscriber that will receive the messages published to our topic. Before implementing subscribers, we need to define POJO classes representing messages posted by the AWS SNS.
+Let’s create two classes that represent SNS Notification and SNS Subscription Confirmation messages based on the AWS SNS Message and JSON formats
+Create org.acme.sns.model.SnsNotification class
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class SnsNotification {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signinCertUrl;
+
+ @JsonProperty("Subject")
+ private String subject;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ @JsonProperty("UnsubscribeURL")
+ private String unsubscribeURL;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigninCertUrl() {
+ return signinCertUrl;
+ }
+
+ public void setSigninCertUrl(String signinCertUrl) {
+ this.signinCertUrl = signinCertUrl;
+ }
+
+ public String getSubject() {
+ return subject;
+ }
+
+ public void setSubject(String subject) {
+ this.subject = subject;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+
+ public String getUnsubscribeURL() {
+ return unsubscribeURL;
+ }
+
+ public void setUnsubscribeURL(String unsubscribeURL) {
+ this.unsubscribeURL = unsubscribeURL;
+ }
+}Then, create org.acme.sns.SnsSubscriptionConfirmation
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class SnsSubscriptionConfirmation {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signingCertUrl;
+
+ @JsonProperty("SubscribeURL")
+ private String subscribeUrl;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("Token")
+ private String token;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigningCertUrl() {
+ return signingCertUrl;
+ }
+
+ public void setSigningCertUrl(String signingCertUrl) {
+ this.signingCertUrl = signingCertUrl;
+ }
+
+ public String getSubscribeUrl() {
+ return subscribeUrl;
+ }
+
+ public void setSubscribeUrl(String subscribeUrl) {
+ this.subscribeUrl = subscribeUrl;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getToken() {
+ return token;
+ }
+
+ public void setToken(String token) {
+ this.token = token;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+}Now, create org.acme.QuarksShieldSyncResource REST resources that:
+- Allows to subscribe itself to our SNS topic
+- Unsubscribe from the SNS topic
+- Receive notifications from the subscribed SNS topic
| + + | ++Keep in mind that AWS SNS supports multiple types of subscribers (that is web servers, email addresses, AWS SQS queues, AWS Lambda functions, and many more), but for the sake of the +quickstart we will show how to subscribe an HTTP endpoint served by our application. + | +
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Response notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) throws JsonProcessingException {
+ if (messageType == null) {
+ return Response.status(400).build();
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ SnsNotification notification = readObject(SnsNotification.class, message);
+ Quark quark = readObject(Quark.class, notification.getMessage());
+ LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ SnsSubscriptionConfirmation subConf = readObject(SnsSubscriptionConfirmation.class, message);
+ sns.confirmSubscription(cs -> cs.topicArn(topicArn).token(subConf.getToken()));
+ LOGGER.info("Subscription confirmed. Ready for quarks collisions.");
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ } else {
+ return Response.status(400).entity("Unknown messageType").build();
+ }
+
+ return Response.ok().build();
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Response subscribe() {
+ String notificationEndpoint = notificationEndpoint();
+ SubscribeResponse response = sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint));
+ subscriptionArn = response.subscriptionArn();
+ LOGGER.infov("Subscribed Quarks shield <{0}> : {1} ", notificationEndpoint, response.subscriptionArn());
+ return Response.ok().entity(response.subscriptionArn()).build();
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Response unsubscribe() {
+ if (subscriptionArn != null) {
+ sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn));
+ LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn);
+ return Response.ok().build();
+ } else {
+ LOGGER.info("Not subscribed yet");
+ return Response.status(400).entity("Not subscribed yet").build();
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/sync/shield";
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}subscribe() endpoint subscribes to our topic by providing the URL to the POST endpoint receiving SNS notification requests.
unsubscribe() simply removes our subscription, so any messages published to the topic will not be routed to our endpoint anymore
notificationEndpoint() is called by SNS on new message if endpoint is subscribed.
+See Amazon SNS message and JSON formats for details about the format of the messages SNS can submit.
Both SNS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SNS instance, configure it as follows:
+quarkus.sns.endpoint-override=http://localhost:4566
+
+quarkus.sns.aws.region=us-east-1
+quarkus.sns.aws.credentials.type=static
+quarkus.sns.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sns.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sns.aws.region - It’s required by the client, but since you’re using a local SNS instance you can pick any valid AWS region.
quarkus.sns.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sns.endpoint-override - Override the SNS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sns.aws.region=<YOUR_REGION>
+quarkus.sns.aws.credentials.type=defaultquarkus.sns.aws.region you should set it to the region where you provisioned the SNS table,
quarkus.sns.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dtopic.arn=$TOPIC_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sns.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sns.publish(p -> p.topicArn(topicArn).message(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(PublishResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SNS client, and then transform the emitted item.
And corresponding async subscriber org.acme.sns.QuarksShieldAsyncResource
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Uni<Response> notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) {
+ if (messageType == null) {
+ return Uni.createFrom().item(Response.status(400).build());
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsNotification.class, message))
+ .onItem().transform(notification -> readObject(Quark.class, notification.getMessage()))
+ .onItem().invoke(quark -> LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(quark -> Response.ok().build());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsSubscriptionConfirmation.class, message))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(
+ sns.confirmSubscription(confirm -> confirm.topicArn(topicArn).token(msg.getToken())))
+ )
+ .onItem().invoke(resp -> LOGGER.info("Subscription confirmed. Ready for quarks collisions."))
+ .onItem().transform(resp -> Response.ok().build());
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ return Uni.createFrom().item(Response.ok().build());
+ }
+
+ return Uni.createFrom().item(Response.status(400).entity("Unknown messageType").build());
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Uni<Response> subscribe() {
+ return Uni.createFrom()
+ .completionStage(sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint())))
+ .onItem().transform(SubscribeResponse::subscriptionArn)
+ .onItem().invoke(this::setSubscriptionArn)
+ .onItem().invoke(arn -> LOGGER.infov("Subscribed Quarks shield with id = {0} ", arn))
+ .onItem().transform(arn -> Response.ok().entity(arn).build());
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Uni<Response> unsubscribe() {
+ if (subscriptionArn != null) {
+ return Uni.createFrom()
+ .completionStage(sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn)))
+ .onItem().invoke(arn -> LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn))
+ .onItem().invoke(arn -> subscriptionArn = null)
+ .onItem().transform(arn -> Response.ok().build());
+ } else {
+ return Uni.createFrom().item(Response.status(400).entity("Not subscribed yet").build());
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/async/shield";
+ }
+
+ private void setSubscriptionArn(String arn) {
+ this.subscriptionArn = arn;
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}And we need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sns.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Queue Service (SQS) is a fully managed message queuing service. +Using SQS, you can send, store, and receive messages between software components at any volume, without losing messages or requiring other +services to be available. +SQS offers two types of message queues. Standard queues offer maximum throughput, best-effort ordering and at-least-once delivery. +SQS FIFO queues are designed to guarantee that messages are processes exactly once, on the exact order that they were sent.
+You can find more information about SQS at the Amazon SQS website.
+| + + | ++The SQS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SQS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SQS service
+Docker for your system to run SQS locally for testing purposes
+The easiest way to start working with SQS is to run a local instance using Dev Services.
+You can optionally configure the queues that are created on startup with the quarkus.sqs.devservices.queues config property.
You can also set up a local version of SQS manually, first start a LocalStack container:
+docker run --rm --name local-sqs -p 4566:4566 -e SERVICES=sqs -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SQS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SQS queue using AWS CLI and store in QUEUE_URL environment variable.
QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue --profile localstack --endpoint-url=http://localhost:4566`Or, if you want to use your SQS queue on your AWS account create a queue using your default profile
+QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue`The application built here allows shooting an elementary particles (quarks) into a ColliderQueue queue of the AWS SQS.
+Additionally, we create a resource that allows receiving those quarks from the ColliderQueue queue in the order they were sent.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sqs-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sqs-quickstart \
+ -DclassName="org.acme.sqs.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sqs"
+cd amazon-sqs-quickstartThis command generates a Maven structure importing the RESTEasy Reactive and Amazon SQS Client extensions.
+After this, the amazon-sqs extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that sends quarks via the queue. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sqs.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sqs.QuarksCannonSyncResource that will provide an API to shoot quarks into the SQS queue using the synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ SendMessageResponse response = sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact messages sent to the queue must be a String, we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
Now, create the org.acme.QuarksShieldSyncResource REST resources that provides an endpoint to read the messages from the ColliderQueue queue.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public List<Quark> receive() {
+ List<Message> messages = sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)).messages();
+
+ return messages.stream()
+ .map(Message::body)
+ .map(this::toQuark)
+ .collect(Collectors.toList());
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}We are using here a Jackson’s ObjectReader in order to deserialize queue messages into our Quark POJOs.
Both SQS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SQS instance, configure it as follows:
+quarkus.sqs.endpoint-override=http://localhost:4566
+
+quarkus.sqs.aws.region=us-east-1
+quarkus.sqs.aws.credentials.type=static
+quarkus.sqs.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sqs.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sqs.aws.region - It’s required by the client, but since you’re using a local SQS instance use us-east-1 as it’s a default region of LocalStack’s SQS.
quarkus.sqs.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sqs.endpoint-override - Override the SQS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all SQS related properties. By default, the SQS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dqueue.url=$QUEUE_URL -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sqs.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(SendMessageResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SQS client, and then transform the emitted item.
And the corresponding async receiver of the queue messages org.acme.sqs.QuarksShieldAsyncResource
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+import software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public Uni<List<Quark>> receive() {
+ return Uni.createFrom()
+ .completionStage(sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)))
+ .onItem().transform(ReceiveMessageResponse::messages)
+ .onItem().transform(m -> m.stream().map(Message::body).map(this::toQuark).collect(Collectors.toList()));
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sqs.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Systems Manager (formerly Amazon Simple Systems Manager, or SSM) is a service that you can use to view and control your infrastructure on AWS. +One of the most useful features of SSM for microservices is the Parameter Store, which provides secure, hierarchical storage for configuration data management and secrets management..
+You can find more information about SSM at the AWS Systems Manager website.
+| + + | ++The SSM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SSM locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SSM service
+Docker for your system to run SSM locally for testing purposes
+The easiest way to start working with SSM is to run a local instance using Dev Services.
+You can also set up a local version of SSM manually, first start a LocalStack container:
+docker run --rm --name local-ssm --publish 4566:4583 -e SERVICES=ssm -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SSM instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve parameters using the SSM parameter store.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ssm-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ssm-quickstart \
+ -DclassName="org.acme.ssm.QuarkusSsmSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ssm"
+cd amazon-ssm-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SSM Client extensions.
+After this, the amazon-ssm extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from SSM parameter store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.ssm.QuarkusSsmResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.ssm;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.ssm.model.GetParameterRequest;
+import software.amazon.awssdk.services.ssm.model.GetParametersByPathRequest;
+import software.amazon.awssdk.services.ssm.model.Parameter;
+import software.amazon.awssdk.services.ssm.model.ParameterType;
+import software.amazon.awssdk.services.ssm.model.PutParameterRequest;
+
+public abstract class QuarkusSsmResource {
+
+ @ConfigProperty(name = "parameters.path") (1)
+ String parametersPath;
+
+ @PostConstruct (2)
+ void normalizePath() {
+ if (!parametersPath.startsWith("/")) {
+ parametersPath = "/" + parametersPath;
+ }
+ if (!parametersPath.endsWith("/")) {
+ parametersPath = parametersPath + "/";
+ }
+ }
+
+ protected Collector<Parameter, ?, Map<String, String>> parametersToMap() { (3)
+ return toMap(p -> p.name().substring(parametersPath.length()), Parameter::value);
+ }
+
+ protected GetParametersByPathRequest generateGetParametersByPathRequest() {
+ return GetParametersByPathRequest.builder() (4)
+ .path(parametersPath)
+ .withDecryption(TRUE)
+ .build();
+ }
+
+ protected PutParameterRequest generatePutParameterRequest(String name, String value, boolean secure) {
+ return PutParameterRequest.builder() (5)
+ .name(parametersPath + name)
+ .value(value)
+ .type(secure ? ParameterType.SECURE_STRING : ParameterType.STRING)
+ .overwrite(TRUE)
+ .build();
+ }
+
+ protected GetParameterRequest generateGetParameterRequest(String name) {
+ return GetParameterRequest.builder() (6)
+ .name(parametersPath + name)
+ .withDecryption(TRUE)
+ .build();
+ }
+}| 1 | +Inject a configured path under which to store parameters | +
| 2 | +Ensure the path starts and ends with / |
+
| 3 | +Collect parameters into a map of simple names and values | +
| 4 | +Generate a request for all parameters under the configured path | +
| 5 | +Generate a request to set a specific parameter | +
| 6 | +Generate a request to get a specific parameter value | +
Now, we can extend the class and create the synchronous implementation in the org.acme.ssm.QuarkusSsmSyncResource class.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.resteasy.reactive.RestQuery;
+
+import software.amazon.awssdk.services.ssm.SsmClient;
+
+@Path("/sync")
+public class QuarkusSsmSyncResource extends QuarkusSsmResource {
+
+ @Inject (1)
+ SsmClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Map<String, String> getParameters() {
+ return ssm.getParametersByPath(generateGetParametersByPathRequest())
+ .parameters().stream().collect(parametersToMap());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ ssm.putParameter(generatePutParameterRequest(name, value, secure));
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String getParameter(String name) {
+ return ssm.getParameter(generateGetParameterRequest(name))
+ .parameter().value();
+ }
+}| 1 | +Inject the client provided by the amazon-ssm extension | +
Using the Amazon SSM SDK, we can easily store and retrieve arbitrary name/value pairs, and we can optionally store the values in a secure manner.
+Both SSM clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SSM instance, configure it as follows:
+quarkus.ssm.endpoint-override=http://localhost:4566 (1)
+
+quarkus.ssm.aws.region=us-east-1 (2)
+quarkus.ssm.aws.credentials.type=static (3)
+quarkus.ssm.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ssm.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the SSM client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon SSM related properties. By default, the SSM client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ssm.QuarkusSsmAsyncResource REST resource that will be similar to our QuarkusSsmSyncResource but using an asynchronous programming model.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import org.jboss.resteasy.reactive.RestQuery;
+import software.amazon.awssdk.services.ssm.SsmAsyncClient;
+
+@Path("/async")
+public class QuarkusSsmAsyncResource extends QuarkusSsmResource {
+
+ @Inject
+ SsmAsyncClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<Map<String, String>> getParameters() {
+ return Uni.createFrom().completionStage(ssm.getParametersByPath(generateGetParametersByPathRequest()))
+ .onItem().transform(r -> r.parameters().stream().collect(parametersToMap()));
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ return Uni.createFrom().completionStage(ssm.putParameter(generatePutParameterRequest(name, value, secure)))
+ .onItem().transform(r -> null);
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> getParameter(String name) {
+ return Uni.createFrom().completionStage(ssm.getParameter(generateGetParameterRequest(name)))
+ .onItem().transform(r -> r.parameter().value());
+ }
+}Note that the SsmAsyncClient behaves just like the SsmClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ssm.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege credentials for users.
+You can find more information about STS at AWS Security Token Service API Reference.
+| + + | ++The STS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use STS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the STS service
+Docker for your system to run STS locally for testing purposes
+The easiest way to start working with STS is to run a local instance using Dev Services.
+You can also set up a local version of STS manually, first start a LocalStack container:
+docker run --rm --name local-sts --publish 4592:4592 -e SERVICES=sts -e START_WEB=0 -d localstack/localstack:3.0.1This starts a STS instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sts-quickstart \
+ -DclassName="org.acme.sts.QuarkusStsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sts"
+cd amazon-sts-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon STS Client extensions.
+After this, the amazon-sts extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both STS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local STS instance, configure it as follows:
+quarkus.sts.endpoint-override=http://localhost:4592 (1)
+
+quarkus.sts.aws.region=us-east-1 (2)
+quarkus.sts.aws.credentials.type=static (3)
+quarkus.sts.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sts.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the STS client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon STS related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sts.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Quarkus Amazon Services automatically starts a LocalStack container in dev mode and when running tests. So, you don’t have to start one manually. The extension client is configured automatically.
+Dev Services for Amazon Services is automatically enabled for each extensions added to pom.xml except in the following situations:
quarkus.devservices.enabled is set to false
devservices.enabled is set to false per extension (eg. quarkus.s3.devservices.enabled=false)
the endpoint-override is configured (eg. quarkus.s3.endpoint-override=http://localhost:4566)
Your environment does not support Docker. In test mode, it will cause the test to fail. Either disable Dev Services or configure the endpoint-override.
By default, Dev Services for Amazon Services will start one LocalStack container with only the needed services.
+If you need to share a particular service between applications, Dev Services for Amazon Services implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single container.
+Dev Services for Amazon Services starts the container with the quarkus-dev-service-localstack label and service name as the value, which is used to identify the container.
+If you need multiple (shared) container, you can configure the devservices.service-name attribute for a given extension (eg. quarkus.s3.devservices.service-name) and indicate the container name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is localstack.
By default, to ease sharing containers across multiple applications, each service will be started in its own container (the value of the quarkus-dev-service-localstack label is suffixed by the extension name). However, sometimes, some services need to communicate with each other inside the same container (e.g., subscribing an Amazon SQS queue to an Amazon SNS topic). In this case, you can disable this behavior by setting the devservices.isolated attribute for a given extension to false.
Sharing is disabled by default in dev mode, and is always disabled in test mode. You can enable the sharing with devservices.shared=true for a given extension (e.g. quarkus.s3.devservices.shared=true). All other non-shared services will be grouped in another container.
Dev Services for Amazon Services uses localstack/localstack image. You can configure the image and version using the quarkus.aws.devservices.localstack.image-name property:
quarkus.aws.devservices.localstack.image-name=localstack/localstack:3.0.1Dev Services for Amazon Services can support specific properties sent to the container. It can be globally applied to all containers or be specified per service as follows:
+quarkus.aws.devservices.localstack.container-properties.START_WEB=0
+quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1GRefer to the LocalStack documentation for more configuration : https://docs.localstack.cloud/localstack/configuration/#local-aws-services. Note that not all environment variables are supported and some may affect Dev Services for Amazon Services.
+To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:
quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
+quarkus.aws.devservices.localstack.additional-services."redshift".enabled=trueThe key is the name of the service to enable and must be a valid LocalStack service name.
+Some extensions support additional configuration to be applied at startup. Refer to the extension documentation.
+The Cognito extension is not using LocalStack but Moto.
+Dev Services for Amazon Services uses the latest motoserver/moto image. You can configure the image and version using the quarkus.aws.devservices.moto.image-name property:
quarkus.aws.devservices.moto.image-name=motoserver/moto:3.0.2Dev Services for Amazon Services can support specific properties sent to the container as follows:
+quarkus.aws.devservices.moto.container-properties.MOTO_COGNITO_IDP_USER_POOL_ID_STRATEGY=HASHConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Classpath to init scripts folder executed during localstack startup. initScriptsFolder has higher precedence. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Configure the starting buffer size the client will use to buffer the parts downloaded from S3. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the maximum number of S3 connections that should be established during a transfer. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the minimum part size for transfer parts. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The target throughput for transfer requests. +
+
+Environment variable: |
+double |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Classpath to init scripts folder executed during localstack startup. initScriptsFolder has higher precedence. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
This set of extensions expose AWS services through configuration properties and CDI injection.
+You can find the full set of supported services and documentation for each of them in the navigation on the left.
+Service client for accessing Amazon Cognito user pools (Identity Provider).
+Using the Amazon Cognito user pools API, you can create a user pool to manage directories and users. +You can authenticate a user to obtain tokens related to user identity and access policies.
+For more information, see the Amazon Cognito user pools (AWS Java SDK 2.x docs).
+| + + | ++The Cognito User Pools extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Cognito User Pool locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+One of:
+An AWS Account to access the Cognito service
+Or Docker for your system to run Cognito locally for testing purposes
+The easiest way to start working with Cognito is to run a local instance using Dev Services.
+You can also set up a local version of Cognito manually, first start a local instance as a container:
+docker run --rm --name moto -p 5000:5000 -d motoserver/moto:3.0.2This starts a Cognito mock instance that is accessible on port 5000.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile moto
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: testCreate a Cognito user pool using AWS CLI.
+aws --profile moto --endpoint-url=http://localhost:5000 cognito-idp create-user-pool --pool-name quarkus-users-devOr, if you want to use your Cognito user pool on your AWS account create a user pool using your default profile
+aws cognito-user-pools cognito-idp --pool-name quarkus-users-devThe application built here shows the count of Cognito User Pools in the current region.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-cognito-user-pools-quickstart \
+ -DclassName="org.acme.cognitouserpools.CognitoExampleResource" \
+ -Dpath="/cognito-example" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-cognito-user-pools,resteasy-mutiny"
+cd amazon-cognito-user-pools-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Cognito User Pool extensions.
+After this, the amazon-cognito-user-pools extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Edit a org.acme.cognitouserpools.CognitoExampleResource that will provide an API return count of Cognito User Pools using the synchronous client.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsResponse;
+
+@Path("/cognito-example")
+public class CognitoExampleResource {
+ @Inject
+ CognitoIdentityProviderClient cognitoClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ ListUserPoolsResponse response = cognitoClient.listUserPools(request);
+ return String.format("You have %d user pools", response.userPools().size());
+ }
+}And update test class:
+package org.acme.cognitouserpools;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.Test;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+
+@QuarkusTest
+public class CognitoExampleResourceTest {
+
+ @Test
+ public void testHelloEndpoint() {
+ given()
+ .when().get("/cognito-example")
+ .then()
+ .statusCode(200)
+ .body(is("You have 1 user pools"));
+ }
+
+}Both Cognito clients (sync and async) are configurable via the application.properties file that
+can be provided in the src/main/resources directory.
Additionally, you need to add to the classpath a proper implementation of the sync client.
+By default the extension uses the URL connection HTTP client, so you need to add a URL connection
+client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local Cognito mock instance, configure it as follows:
+quarkus.cognito-user-pools.endpoint-override=http://localhost:5000
+
+quarkus.cognito-user-pools.aws.region=eu-west-1
+quarkus.cognito-user-pools.aws.credentials.type=static
+quarkus.cognito-user-pools.aws.credentials.static-provider.access-key-id=test-key
+quarkus.cognito-user-pools.aws.credentials.static-provider.secret-access-key=test-secretquarkus.cognito-user-pools.aws.region - It’s required by the client, but since you’re using a local Cognito mock instance use us-east-1 as it’s a default region of moto.
quarkus.cognito-user-pools.aws.credentials - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.cognito-user-pools.endpoint-override - Override the Cognito User Pools client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Cognito User Pools
+related properties. By default, the Cognito User Pools client extension will use the default
+credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.cognitouserpools.CognitoAsyncExampleResource REST resource that will be similar to our
+CognitoExampleResource but using an asynchronous programming model.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderAsyncClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+
+@Path("/cognito-async-example")
+public class CognitoAsyncExampleResource {
+ @Inject
+ CognitoIdentityProviderAsyncClient cognitoAsyncClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ return Uni
+ .createFrom()
+ .completionStage(cognitoAsyncClient.listUserPools(request))
+ .map(response -> {
+ return String.format("You have %d user pools", response.userPools().size());
+ });
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous Cognito
+Identity Provider client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+DynamoDB is a scalable AWS managed NoSQL database. +It supports both key-value and document data models, that enables to have a flexible schema for your data. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about DynamoDB at the Amazon DynamoDB website.
+| + + | ++The DynamoDB extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). +Keep in mind it’s actively developed and does not support yet all the features available in SDK 1.x such as Document APIs + | +
The Quarkus extension supports the traditional DynamoDB client as well as the enhanced client.
+It supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the DynamoDB service
+Optionally, Docker for your system to run DynamoDB locally for testing purposes
+The easiest way to start working with DynamoDB is to run a local instance using Dev Services.
+You can also set up a local version of DynamoDB manually, first start a local instance as a container:
+docker run --publish 4566:8000 amazon/dynamodb-local:1.19.0 -jar DynamoDBLocal.jar -inMemory -sharedDbThis starts a DynamoDB instance that is accessible on port 4566.
+You can check if it’s working with aws dynamodb list-tables --endpoint-url http://localhost:4566.
{
+ "TableNames": []
+}You should see the output above in your terminal. That’s it, DynamoDB runs locally.
+Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.
+Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. +For more information, see Setting Up DynamoDB (Web Service).
+We recommend to use the AWS CLI to provision the table:
+The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-dynamodb-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-dynamodb-quickstart \
+ -DclassName="org.acme.dynamodb.FruitResource" \
+ -Dpath="/fruits" \
+ -Dextensions="resteasy-reactive-jackson,amazon-dynamodb"
+cd amazon-dynamodb-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and DynamoDB Client extensions.
+After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Fruit bean as follows:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ public static Fruit from(Map<String, AttributeValue> item) {
+ Fruit fruit = new Fruit();
+ if (item != null && !item.isEmpty()) {
+ fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
+ fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
+ }
+ return fruit;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map
+object provided by the DynamoDB client response.
Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.
package org.acme.dynamodb;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.ScanRequest;
+
+public abstract class AbstractService {
+
+ public final static String FRUIT_NAME_COL = "fruitName";
+ public final static String FRUIT_DESC_COL = "fruitDescription";
+ public final static String FRUIT_TABLE_NAME = "QuarkusFruits";
+
+ protected ScanRequest scanRequest() {
+ return ScanRequest.builder().tableName(FRUIT_TABLE_NAME)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
+ }
+
+ protected PutItemRequest putRequest(Fruit fruit) {
+ Map<String, AttributeValue> item = new HashMap<>();
+ item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
+ item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());
+
+ return PutItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .item(item)
+ .build();
+ }
+
+ protected GetItemRequest getRequest(String name) {
+ Map<String, AttributeValue> key = new HashMap<>();
+ key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());
+
+ return GetItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .key(key)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
+ .build();
+ }
+}Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ DynamoDbClient dynamoDB;
+
+ public List<Fruit> findAll() {
+ return dynamoDB.scanPaginator(scanRequest()).items().stream()
+ .map(Fruit::from)
+ .collect(Collectors.toList());
+ }
+
+ public void add(Fruit fruit) {
+ dynamoDB.putItem(putRequest(fruit));
+ }
+
+ public Fruit get(String name) {
+ return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
+ }
+}Now, edit the org.acme.dynamodb.FruitResource class as follows:
package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/fruits")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class FruitResource {
+
+ @Inject
+ FruitSyncService service;
+
+ @GET
+ public List<Fruit> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Fruit getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public List<Fruit> add(Fruit fruit) {
+ service.add(fruit);
+ return getAll();
+ }
+}The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.
DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local DynamoDB instance, configure it as follows:
+quarkus.dynamodb.endpoint-override=http://localhost:4566
+
+quarkus.dynamodb.aws.region=eu-central-1
+quarkus.dynamodb.aws.credentials.type=static
+quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
+quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secretquarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.
quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.dynamodb.aws.region=<YOUR_REGION>
+quarkus.dynamodb.aws.credentials.type=defaultquarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,
quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ @Inject
+ DynamoDbAsyncClient dynamoDB;
+
+ public Uni<List<Fruit>> findAll() {
+ return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
+ .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
+ }
+
+ public Uni<Void> add(Fruit fruit) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit))).replaceWithVoid();
+ }
+
+ public Uni<Fruit> get(String name) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
+ .onItem().transform(resp -> Fruit.from(resp.item()));
+ }
+}In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.
Then, create an asynchronous REST resource that consumes this async service:
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+import io.smallrye.mutiny.Uni;
+
+@Path("/async-fruits")
+public class FruitAsyncResource {
+
+ @Inject
+ FruitAsyncService service;
+
+ @GET
+ public Uni<List<Fruit>> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Uni<Fruit> getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public Uni<List<Fruit>> add(Fruit fruit) {
+ return service.add(fruit)
+ .onItem().ignore().andSwitchTo(this::getAll);
+ }
+}And add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.dynamodb.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>The DynamoDB enhanced client is part of the AWS SDK for Java version 2 and makes the mapping between DynamoDB Tables and Java beans very easy.
+The Enhanced Client requires a TableSchema which can be generated from a bean class annotated with DynamoDbBean or DynamoDbImmutable or generated from code.
+By default, TableSchemas generated from bean classes are registered and cached at startup. You don’t need to explicitely instantiate them at class-load time.
+It has both a sync and an async variants.
To use the enhanced client, add the quarkus-amazon-dynamodb-enhanced extension to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-dynamodb-enhanced</artifactId>
+</dependency>The Fruit bean would look like this:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+@DynamoDbBean
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ @DynamoDbPartitionKey
+ @DynamoDbAttribute(AbstractService.FRUIT_NAME_COL)
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ @DynamoDbAttribute(AbstractService.FRUIT_DESC_COL)
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}Note that you don’t need to add @RegisterForReflection anymore.
The FruitSyncService would need to use the DynamoDbEnhancedClient as well as create a TableSchema:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ private DynamoDbTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedSyncService(DynamoDbEnhancedClient dynamoEnhancedClient) {
+ fruitTable = dynamoEnhancedClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}The same goes for the asynchronous version with DynamoDbEnhanceAsyncdClient:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedAsyncService(DynamoDbEnhancedAsyncClient dynamoEnhancedAsyncClient) {
+ fruitTable = dynamoEnhancedAsyncClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}Resource classes remain unchanged.
+Alternatively, if you only need to use the DynamoDbTable instance, you can inject it directly with a @NamedDynamoDbTable annotation.
The synchronous version would be :
+package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ DynamoDbTable<Fruit> fruitTable;
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}And the asynchronous version :
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitEnhancedAsyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}You can find more information about the DynamoDB enhanced client in the AWS documentation:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Amazon Identity and Access Management (IAM) enables users to manage access to AWS services and resources securely.
+You can find more information about IAM at the Amazon IAM website.
+| + + | ++The IAM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Key Management Service (KMS) is a service that allows you to create and control the keys used to encrypt or digitally sign your data. +Using KMS, you can create and manage cryptographic keys and control their use across a wide range of AWS services and in your application.
+You can find more information about KMS at the AWS KMS website.
+| + + | ++The KMS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use KMS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the KMS service
+Docker for your system to run KMS locally for testing purposes
+The easiest way to start working with KMS is to run a local instance using Dev Services.
+You can also set up a local version of KMS manually, first start a LocalStack container:
+docker run --rm --name local-kms --publish 4566:4599 -e SERVICES=kms -e START_WEB=0 -d localstack/localstack:1.4.0This starts a KMS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a KMS master key queue using AWS CLI and store in MASTER_KEY_ARN environment variable.
MASTER_KEY_ARN=`aws kms create-key --profile localstack --endpoint-url=http://localhost:4566 | cut -f3`Generate a key data as 256-bit symmetric key (AES 256)
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256 --profile localstack --endpoint-url=http://localhost:4566Or, if you want to use your AWS account create a key using your default profile
+MASTER_KEY_ARN=`aws kms create-key | cut -f3`
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256The application built here allows to encrypt and decrypt text messages using a master key created on AWS KMS.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-kms-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kms-quickstart \
+ -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kms"
+cd amazon-kms-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon KMS Client extensions.
+After this, the amazon-kms extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to encrypt and decrypt text message provided in the request. +The example application will demonstrate the two programming models supported by the extension.
+Let’s create a org.acme.kms.QuarkusKmsSyncResource that will provide an API to encrypt and decrypt message using the synchronous client.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsSyncResource {
+
+ @Inject
+ KmsClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public String encrypt(String data) {
+ SdkBytes encryptedBytes = kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))).ciphertextBlob();
+
+ return Base64.getEncoder().encodeToString(encryptedBytes.asByteArray());
+ }
+
+ @POST
+ @Path("/decrypt")
+ public String decrypt(String data) {
+ SdkBytes encryptedData = SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes()));
+ DecryptResponse decrypted = kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(encryptedData));
+
+ return decrypted.plaintext().asUtf8String();
+ }
+}An encrypted message is in the form of a bytes array. To return it to the user we need to encode it as Base64 string in the encrypt endpoint.
+On the decrypt endpoint we need to decode from the Base64 string back to the bytes array before sending it out to the KMS client.
Both KMS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local KMS instance, configure it as follows:
+quarkus.kms.endpoint-override=http://localhost:4566
+
+quarkus.kms.aws.region=us-east-1
+quarkus.kms.aws.credentials.type=static
+quarkus.kms.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kms.aws.credentials.static-provider.secret-access-key=test-secretquarkus.kms.aws.region - It’s required by the client, but since you’re using a local KMS instance use us-east-1 as it’s a default region of LocalStack’s KMS.
quarkus.kms.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.kms.endpoint-override - Override the KMS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon KMS related properties. By default, the KMS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dkey.arn=$MASTER_KEY_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.kms.QuarkusKmsAsyncResource REST resource that will be similar to our QuarkusKmsSyncResource but using an asynchronous programming model.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsAsyncClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+import software.amazon.awssdk.services.kms.model.EncryptResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsAsyncResource {
+
+ @Inject
+ KmsAsyncClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public Uni<String> encrypt(String data) {
+ return Uni.createFrom().completionStage(kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))))
+ .onItem().transform(EncryptResponse::ciphertextBlob)
+ .onItem().transform(blob -> Base64.getEncoder().encodeToString(blob.asByteArray()));
+ }
+
+ @POST
+ @Path("/decrypt")
+ public Uni<String> decrypt(String data) {
+ return Uni.createFrom().item(SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes())))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg)))
+ )
+ .onItem().transform(DecryptResponse::plaintext)
+ .onItem().transform(SdkBytes::asUtf8String);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous KMS client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kms.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon S3 is an object storage service. It can be employed to store any type of object which allows for uses like storage for Internet applications, +backup and recovery, disaster recovery, data archives, data lakes for analytics, any hybrid cloud storage. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about S3 at the Amazon S3 website.
+| + + | ++The S3 extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use S3 locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the S3 service. Before you can use the AWS SDKs with Amazon S3, you must get an AWS access key ID and secret access key.
+Optionally, Docker for your system to run S3 locally for testing purposes
+The easiest way to start working with S3 is to run a local instance using Dev Services.
+You can optionally configure the buckets that are created on startup with the quarkus.s3.devservices.buckets config property.
You can also setup a local version of S3 manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=s3 -e START_WEB=0 localstack/localstack:1.4.0This starts a S3 instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to manage files stored in Amazon S3.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-s3-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-s3-quickstart \
+ -DclassName="org.acme.s3.S3SyncClientResource" \
+ -Dpath="/s3" \
+ -Dextensions="resteasy-reactive-jackson,amazon-s3"
+cd amazon-s3-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and S3 Client extensions.
+After this, the amazon-s3 extension has been added to your pom.xml.
| + + | +
+The default setting for quarkus.http.limits.max-body-size is 10240K. This may limit your ability to upload multipart files larger than the default. If you want to upload larger files, you will need to set this limit explicitly.
+ |
+
In this example, we will create an application to manage a list of files. The example application will demonstrate the two programming models supported by the extension.
+Because the primary goal of our application is to upload a file into the S3 bucket, we need to setup the model we will be using to define the multipart/form-data payload,
+in the form of a @MultipartForm POJO.
Create a org.acme.s3.FormData class as follows:
package org.acme.s3;
+
+import java.io.File;
+import jakarta.ws.rs.core.MediaType;
+import org.jboss.resteasy.reactive.PartType;
+import org.jboss.resteasy.reactive.RestForm;
+
+public class FormData {
+
+ @RestForm("file")
+ public File data;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String filename;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String mimetype;
+
+}The class defines three fields:
+data that fill capture stream of uploaded bytes from the client
fileName that captures a filename as provided by the submited form
mimeType content type of the uploaded file
In the second step let’s create a bean that will represent a file in a Amazon S3 bucket as follows:
+package org.acme.s3;
+
+import software.amazon.awssdk.services.s3.model.S3Object;
+
+public class FileObject {
+ private String objectKey;
+
+ private Long size;
+
+ public FileObject() {
+ }
+
+ public static FileObject from(S3Object s3Object) {
+ FileObject file = new FileObject();
+ if (s3Object != null) {
+ file.setObjectKey(s3Object.key());
+ file.setSize(s3Object.size());
+ }
+ return file;
+ }
+
+ public String getObjectKey() {
+ return objectKey;
+ }
+
+ public Long getSize() {
+ return size;
+ }
+
+ public FileObject setObjectKey(String objectKey) {
+ this.objectKey = objectKey;
+ return this;
+ }
+
+ public FileObject setSize(Long size) {
+ this.size = size;
+ return this;
+ }
+}Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the S3Object
+object provided by the S3 client response when listing all the objects in a bucket.
Now create a org.acme.s3.CommonResource that will consist of methods to prepare S3 request to get object from a S3 bucket, or to put file into a S3 bucket.
+Note a configuration property bucket.name is defined here as the request method required name of the S3 bucket.
package org.acme.s3;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+
+abstract public class CommonResource {
+
+ @ConfigProperty(name = "bucket.name")
+ String bucketName;
+
+ protected PutObjectRequest buildPutRequest(FormData formData) {
+ return PutObjectRequest.builder()
+ .bucket(bucketName)
+ .key(formData.filename)
+ .contentType(formData.mimetype)
+ .build();
+ }
+
+ protected GetObjectRequest buildGetRequest(String objectKey) {
+ return GetObjectRequest.builder()
+ .bucket(bucketName)
+ .key(objectKey)
+ .build();
+ }
+
+}Then, create a org.acme.s3.S3SyncClientResource that will provides an API to upload/download files as well as to list all the files in a bucket.
package org.acme.s3;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.ResponseBuilder;
+import jakarta.ws.rs.core.Response.Status;
+import software.amazon.awssdk.core.ResponseBytes;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectResponse;
+
+
+@Path("/s3")
+public class S3SyncClientResource extends CommonResource {
+ @Inject
+ S3Client s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Response uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ PutObjectResponse putResponse = s3.putObject(buildPutRequest(formData),
+ RequestBody.fromFile(formData.data));
+ if (putResponse != null) {
+ return Response.ok().status(Status.CREATED).build();
+ } else {
+ return Response.serverError().build();
+ }
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public Response downloadFile(String objectKey) {
+ ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(buildGetRequest(objectKey));
+ ResponseBuilder response = Response.ok(objectBytes.asUtf8String());
+ response.header("Content-Disposition", "attachment;filename=" + objectKey);
+ response.header("Content-Type", objectBytes.response().contentType());
+ return response.build();
+ }
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public List<FileObject> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder().bucket(bucketName).build();
+
+ //HEAD S3 objects to get metadata
+ return s3.listObjects(listRequest).contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}Both S3 clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
| + + | +
+You need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+add a URL connection client dependency to the pom.xml file:
+ |
+
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>For asynchronous client refer to Going asynchronous for more information.
+If you’re going to use a local S3 instance, configure it as follows:
+quarkus.s3.endpoint-override=http://localhost:4566
+
+quarkus.s3.aws.region=us-east-1
+quarkus.s3.aws.credentials.type=static
+quarkus.s3.aws.credentials.static-provider.access-key-id=test-key
+quarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret
+
+bucket.name=quarkus.s3.quickstartquarkus.s3.aws.region - It’s required by the client, but since you’re using a local S3 instance you can pick any valid AWS region.
quarkus.s3.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.s3.endpoint-override - Override the S3 client to use a local instance instead of an AWS service
bucket.name - Name of the S3 bucket
If you want to work with an AWS account, you’d need to set it with:
+bucket.name=<your-bucket-name>
+
+quarkus.s3.aws.region=<YOUR_REGION>
+quarkus.s3.aws.credentials.type=defaultbucket.name - name of the S3 bucket on your AWS account.
quarkus.s3.aws.region you should set it to the region where your S3 bucket was created,
quarkus.s3.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Now let’s add a simple web page to interact with our S3SyncClientResource.
+Quarkus automatically serves static resources located under the META-INF/resources directory.
+In the src/main/resources/META-INF/resources directory, add a s3.html file with the content from this s3.html file in it.
You can now interact with your REST service:
+start Quarkus with ./mvnw compile quarkus:dev
open a browser to http://localhost:8080/s3.html
upload new file to the current S3 bucket via the form and see the list of files in the bucket
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.s3.S3AsyncClientResource that will be similar to our S3SyncClientResource but using an asynchronous programming model.
package org.acme.s3;
+
+import java.nio.ByteBuffer;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.Status;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+
+import org.jboss.resteasy.reactive.RestMulti;
+import org.reactivestreams.Publisher;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import io.vertx.core.buffer.Buffer;
+import software.amazon.awssdk.core.async.AsyncRequestBody;
+import software.amazon.awssdk.core.async.AsyncResponseTransformer;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.ListObjectsResponse;
+
+@Path("/async-s3")
+public class S3AsyncClientResource extends CommonResource {
+ @Inject
+ S3AsyncClient s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Uni<Response> uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ return Uni.createFrom()
+ .completionStage(() -> {
+ return s3.putObject(buildPutRequest(formData), AsyncRequestBody.fromFile(formData.data));
+ })
+ .onItem().ignore().andSwitchTo(Uni.createFrom().item(Response.created(null).build()))
+ .onFailure().recoverWithItem(th -> {
+ th.printStackTrace();
+ return Response.serverError().build();
+ });
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public RestMulti<Buffer> downloadFile(String objectKey) {
+
+ return RestMulti.fromUniResponse(Uni.createFrom()
+ .completionStage(() -> s3.getObject(buildGetRequest(objectKey),
+ AsyncResponseTransformer.toPublisher())),
+ response -> Multi.createFrom().safePublisher(AdaptersToFlow.publisher((Publisher<ByteBuffer>) response))
+ .map(S3AsyncClientResource::toBuffer),
+ response -> Map.of("Content-Disposition", List.of("attachment;filename=" + objectKey), "Content-Type",
+ List.of(response.response().contentType())));
+ }
+
+ @GET
+ public Uni<List<FileObject>> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder()
+ .bucket(bucketName)
+ .build();
+
+ return Uni.createFrom().completionStage(() -> s3.listObjects(listRequest))
+ .onItem().transform(result -> toFileItems(result));
+ }
+
+ private static Buffer toBuffer(ByteBuffer bytebuffer) {
+ byte[] result = new byte[bytebuffer.remaining()];
+ bytebuffer.get(result);
+ return Buffer.buffer(result);
+ }
+
+ private List<FileObject> toFileItems(ListObjectsResponse objects) {
+ return objects.contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.s3.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Secrets Manager enables you to replace hardcoded credentials in your code, including passwords, with an API call to Secrets Manager to retrieve the secret programmatically. +This helps ensure the secret can’t be compromised by someone examining your code, because the secret no longer exists in the code.
+You can find more information about Secrets Manager at the AWS Secrets Manager website.
+| + + | ++The Secrets Manager extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Secrets Manager locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Secrets Manager service
+Docker for your system to run Secrets Manager locally for testing purposes
+The easiest way to start working with Secrets Manager is to run a local instance using Dev Services.
+You can also set up a local version of Secrets Manager manually, first start a LocalStack container:
+docker run --rm --name local-secrets-manager --publish 4566:4584 -e SERVICES=secretsmanager -e START_WEB=0 -d localstack/localstack:1.4.0This starts a Secrets Manager instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve credentials using Secrets Manager.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-secretsmanager-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-secretsmanager-quickstart \
+ -DclassName="org.acme.secretsmanager.QuarkusSecretsManagerSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-secretsmanager,resteasy-mutiny"
+cd amazon-secretsmanager-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Secrets Manager Client extensions.
+After this, the amazon-secretsmanager extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from Secrets Manager store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.secretsmanager.QuarkusSecretsManagerResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.secretsmanager;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.secretsmanager.model.CreateSecretRequest;
+import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueRequest;
+
+public abstract class QuarkusSecretsManagerResource {
+ public static final String VERSION_STAGE = "AWSCURRENT";
+
+ @ConfigProperty(name = "secret.name") (1)
+ String secretName;
+
+ protected GetSecretValueRequest generateGetSecretValueRequest() {
+ return GetSecretValueRequest.builder() (2)
+ .secretId(secretName)
+ .versionStage(VERSION_STAGE)
+ .build();
+ }
+
+ protected CreateSecretRequest generateCreateSecretRequest(String name, String secret) {
+ return CreateSecretRequest.builder() (3)
+ .name(name)
+ .secretString(secret)
+ .build();
+ }
+
+}| 1 | +Inject a configured name under which is stored the secret | +
| 2 | +Generate a request for the credentials with the configured name | +
| 3 | +Generate a request to create a specific secret | +
Now, we can extend the class and create the synchronous implementation in the org.acme.secretsmanager.QuarkusSecretsManagerSyncResource class.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerClient;
+
+@Path("/sync")
+public class QuarkusSecretsManagerSyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject (1)
+ SecretsManagerClient secretsManagerClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public String getSecret() {
+ return secretsManagerClient.getSecretValue(generateGetSecretValueRequest()).secretString();
+ }
+
+ @POST
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void createSecret(String name, String value) {
+ secretsManagerClient.createSecret(generateCreateSecretRequest(name, secret));
+ }
+
+}| 1 | +Inject the client provided by the amazon-secretsmanager extension | +
Using the Amazon Secrets Manager SDK, we can easily store and retrieve secrets.
+Both Secrets Manager clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local Secrets Manager instance, configure it as follows:
+quarkus.secretsmanager.endpoint-override=http://localhost:4566 (1)
+
+quarkus.secretsmanager.aws.region=us-east-1 (2)
+quarkus.secretsmanager.aws.credentials.type=static (3)
+quarkus.secretsmanager.aws.credentials.static-provider.access-key-id=test-key
+quarkus.secretsmanager.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Secret Manager client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Secrets Manager related properties. By default, the Secrets Manager client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.secretsmanager.QuarkusSecretsManagerAsyncResource REST resource that will be similar to our QuarkusSecretsManagerSyncResource but using an asynchronous programming model.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerAsyncClient;
+
+@Path("/async")
+public class QuarkusSecretsManagerAsyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject
+ SecretsManagerAsyncClient secretsManagerAsyncClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<String> getSecret() {
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.getSecretValue(generateGetSecretValueRequest()))
+ .onItem().transform(r -> r.secretString());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> createSecret(String name, String value) {
+
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.createSecret(generateCreateSecretRequest(name, secret)))
+ .onItem().transform(r -> null);
+ }
+
+}Note that the SecretsManagerAsyncClient behaves just like the SecretsManagerClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.secretsmanager.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Email Service (SES) is a flexible and highly-scalable email sending and receiving service. +Using SES, you can send emails with any type of correspondence. You can find more information about SES at the Amazon SES website.
+| + + | ++The SES extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SES locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SES service
+Docker for your system to run SES locally for testing purposes
+The easiest way to start working with SES is to run a local instance using Dev Services. +However, local instance of SES is only mocks the SES APIs without the actual email sending capabilities. You can still use it for this guide to verify an API communication or integration test purposes.
+You can also set up a local version of SES manually, first start a LocalStack container:
+docker run --rm --name local-ses -p 4566:4579 -e SERVICES=ses -e START_WEB=0 -d localstack/localstack:1.4.0This starts a SES instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textAmazon applies certain restrictions to new Amazon SES accounts, mainly to prevent fraud and abuse. All new accounts are in the Amazon SES sandbox. +All the features of the Amazon SES are still available while in sandbox, but a following restrictions applies: +- You can send mail to verified email addresses and domains or to the Amazon SES mailbox simulator +- You can only send mail from verified email addresses and domains +- You can send a maximum of 1 message per second.
+Going production, you’d need to get your account of the sandbox following the Amazon procedure.
+We assume you are going to use AWS SES sandbox for the sake of this guide. But before sending any email, you must verify sender and recipient email addresses using AWS CLI. +You can use your personal email or any temporary email service available if you wish.
+aws ses verify-email-identity --email-address <sender@email.address>
+aws ses verify-email-identity --email-address <recipient@email.address>Now, you need to open a mailboxes of those email addresses in order to follow confirmation procedure. Once email is approved you can use it in your application.
+If you are using local SES you still need to verify email addresses, otherwise your send email in order to let local SES accepting your request. +However, no emails to be send as it only mocks the service APIs.
+aws ses verify-email-identity --email-address <sender@email.address> --profile localstack --endpoint-url=http://localhost:4566
+aws ses verify-email-identity --email-address <recipient@email.address> --profile localstack --endpoint-url=http://localhost:4566The application built here allows sending text emails to the recipients that are verified on AWS SES.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ses-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ses-quickstart \
+ -DclassName="org.acme.ses.QuarkusSesSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ses"
+cd amazon-ses-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SES Client extensions.
+After this, the amazon-ses extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Lets create a org.acme.ses.QuarkusSesSyncResource that will provide an API to send emails using the synchronous client.
package org.acme.ses;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesClient;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesSyncResource {
+
+ @Inject
+ SesClient ses;
+
+ @POST
+ @Path("/email")
+ public String encrypt(Email data) {
+ return ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))).messageId();
+ }
+}Both SES clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SES instance, configure it as follows:
+quarkus.ses.endpoint-override=http://localhost:4566
+
+quarkus.ses.aws.region=us-east-1
+quarkus.ses.aws.credentials.type=static
+quarkus.ses.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ses.aws.credentials.static-provider.secret-access-key=test-secretquarkus.ses.aws.region - It’s required by the client, but since you’re using a local SES instance use us-east-1 as it’s a default region of LocalStack’s SES.
quarkus.ses.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.ses.endpoint-override - Override the SES client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon SES related properties. By default, the SES client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ses.QuarkusSesAsyncResource REST resource that will be similar to our QuarkusSesSyncResource but using an asynchronous programming model.
package org.acme.ses;
+
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesAsyncClient;
+import software.amazon.awssdk.services.ses.model.SendEmailResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesAsyncResource {
+
+ @Inject
+ SesAsyncClient ses;
+
+ @POST
+ @Path("/email")
+ public Uni<String> encrypt(Email data) {
+ return Uni.createFrom()
+ .completionStage(
+ ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))))
+ .onItem().apply(SendEmailResponse::messageId);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SES client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ses.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Notification Service (SNS) is a highly available and fully managed pub/sub messaging service. +It provides topics for high-throughput, push-based, many-to-many messaging. Messages can fan out to a large number of subscriber endpoints for +parallel processing, including Amazon SQS queues, AWS Lambda functions, and HTTP/S webhooks. Additionally, SNS can be used +to fan out notifications to end users using mobile push, SMS and email.
+You can find more information about SNS at the Amazon SNS website.
+| + + | ++The SNS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SNS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SNS service
+Optionally, Docker for your system to run SNS locally for testing purposes
+The easiest way to start working with SNS is to run a local instance using Dev Services.
+You can also set up a local version of SNS manually, first start a LocalStack container:
+docker run -it --publish 4566:4575 -e SERVICES=sns -e START_WEB=0 localstack/localstack:1.4.0This starts a SNS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SNS topic using AWS CLI and store in TOPIC_ARN environment variable
TOPIC_ARN=`aws sns create-topic --name=QuarksCollider --profile localstack --endpoint-url=http://localhost:4566`| + + | +
+
+
+If you are using LocalStack, some additional configuration is needed: +
+
+
+
+Otherwise your service will not receive the notifications. + |
+
If you want to run the demo using SNS on your AWS account, you can create a topic using AWS default profile
+TOPIC_ARN=`aws sns create-topic --name=QuarksCollider`The application built here allows to shoot elementary particles (quarks) into a QuarksCollider topic of the AWS SNS.
+Additionally, we create a resource that allows to subscribe to the QuarksCollider topic in order to receive published quarks.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sns-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sns-quickstart \
+ -DclassName="org.acme.sns.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sns"
+cd amazon-sns-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SNS Client extensions.
+After this, the amazon-sns extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to publish quarks. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sns.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sns.QuarksCannonSyncResource that will provide an API to shoot quarks into the SNS topic via the SNS synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ PublishResponse response = sns.publish(p -> p.topicArn(topicArn).message(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact that messages published must be simply a String we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
The missing piece is the subscriber that will receive the messages published to our topic. Before implementing subscribers, we need to define POJO classes representing messages posted by the AWS SNS.
+Let’s create two classes that represent SNS Notification and SNS Subscription Confirmation messages based on the AWS SNS Message and JSON formats
+Create org.acme.sns.model.SnsNotification class
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class SnsNotification {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signinCertUrl;
+
+ @JsonProperty("Subject")
+ private String subject;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ @JsonProperty("UnsubscribeURL")
+ private String unsubscribeURL;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigninCertUrl() {
+ return signinCertUrl;
+ }
+
+ public void setSigninCertUrl(String signinCertUrl) {
+ this.signinCertUrl = signinCertUrl;
+ }
+
+ public String getSubject() {
+ return subject;
+ }
+
+ public void setSubject(String subject) {
+ this.subject = subject;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+
+ public String getUnsubscribeURL() {
+ return unsubscribeURL;
+ }
+
+ public void setUnsubscribeURL(String unsubscribeURL) {
+ this.unsubscribeURL = unsubscribeURL;
+ }
+}Then, create org.acme.sns.SnsSubscriptionConfirmation
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class SnsSubscriptionConfirmation {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signingCertUrl;
+
+ @JsonProperty("SubscribeURL")
+ private String subscribeUrl;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("Token")
+ private String token;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigningCertUrl() {
+ return signingCertUrl;
+ }
+
+ public void setSigningCertUrl(String signingCertUrl) {
+ this.signingCertUrl = signingCertUrl;
+ }
+
+ public String getSubscribeUrl() {
+ return subscribeUrl;
+ }
+
+ public void setSubscribeUrl(String subscribeUrl) {
+ this.subscribeUrl = subscribeUrl;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getToken() {
+ return token;
+ }
+
+ public void setToken(String token) {
+ this.token = token;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+}Now, create org.acme.QuarksShieldSyncResource REST resources that:
+- Allows to subscribe itself to our SNS topic
+- Unsubscribe from the SNS topic
+- Receive notifications from the subscribed SNS topic
| + + | ++Keep in mind that AWS SNS supports multiple types of subscribers (that is web servers, email addresses, AWS SQS queues, AWS Lambda functions, and many more), but for the sake of the +quickstart we will show how to subscribe an HTTP endpoint served by our application. + | +
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Response notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) throws JsonProcessingException {
+ if (messageType == null) {
+ return Response.status(400).build();
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ SnsNotification notification = readObject(SnsNotification.class, message);
+ Quark quark = readObject(Quark.class, notification.getMessage());
+ LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ SnsSubscriptionConfirmation subConf = readObject(SnsSubscriptionConfirmation.class, message);
+ sns.confirmSubscription(cs -> cs.topicArn(topicArn).token(subConf.getToken()));
+ LOGGER.info("Subscription confirmed. Ready for quarks collisions.");
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ } else {
+ return Response.status(400).entity("Unknown messageType").build();
+ }
+
+ return Response.ok().build();
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Response subscribe() {
+ String notificationEndpoint = notificationEndpoint();
+ SubscribeResponse response = sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint));
+ subscriptionArn = response.subscriptionArn();
+ LOGGER.infov("Subscribed Quarks shield <{0}> : {1} ", notificationEndpoint, response.subscriptionArn());
+ return Response.ok().entity(response.subscriptionArn()).build();
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Response unsubscribe() {
+ if (subscriptionArn != null) {
+ sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn));
+ LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn);
+ return Response.ok().build();
+ } else {
+ LOGGER.info("Not subscribed yet");
+ return Response.status(400).entity("Not subscribed yet").build();
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/sync/shield";
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}subscribe() endpoint subscribes to our topic by providing the URL to the POST endpoint receiving SNS notification requests.
unsubscribe() simply removes our subscription, so any messages published to the topic will not be routed to our endpoint anymore
notificationEndpoint() is called by SNS on new message if endpoint is subscribed.
+See Amazon SNS message and JSON formats for details about the format of the messages SNS can submit.
Both SNS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SNS instance, configure it as follows:
+quarkus.sns.endpoint-override=http://localhost:4566
+
+quarkus.sns.aws.region=us-east-1
+quarkus.sns.aws.credentials.type=static
+quarkus.sns.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sns.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sns.aws.region - It’s required by the client, but since you’re using a local SNS instance you can pick any valid AWS region.
quarkus.sns.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sns.endpoint-override - Override the SNS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sns.aws.region=<YOUR_REGION>
+quarkus.sns.aws.credentials.type=defaultquarkus.sns.aws.region you should set it to the region where you provisioned the SNS table,
quarkus.sns.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dtopic.arn=$TOPIC_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sns.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sns.publish(p -> p.topicArn(topicArn).message(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(PublishResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SNS client, and then transform the emitted item.
And corresponding async subscriber org.acme.sns.QuarksShieldAsyncResource
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Uni<Response> notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) {
+ if (messageType == null) {
+ return Uni.createFrom().item(Response.status(400).build());
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsNotification.class, message))
+ .onItem().transform(notification -> readObject(Quark.class, notification.getMessage()))
+ .onItem().invoke(quark -> LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(quark -> Response.ok().build());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsSubscriptionConfirmation.class, message))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(
+ sns.confirmSubscription(confirm -> confirm.topicArn(topicArn).token(msg.getToken())))
+ )
+ .onItem().invoke(resp -> LOGGER.info("Subscription confirmed. Ready for quarks collisions."))
+ .onItem().transform(resp -> Response.ok().build());
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ return Uni.createFrom().item(Response.ok().build());
+ }
+
+ return Uni.createFrom().item(Response.status(400).entity("Unknown messageType").build());
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Uni<Response> subscribe() {
+ return Uni.createFrom()
+ .completionStage(sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint())))
+ .onItem().transform(SubscribeResponse::subscriptionArn)
+ .onItem().invoke(this::setSubscriptionArn)
+ .onItem().invoke(arn -> LOGGER.infov("Subscribed Quarks shield with id = {0} ", arn))
+ .onItem().transform(arn -> Response.ok().entity(arn).build());
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Uni<Response> unsubscribe() {
+ if (subscriptionArn != null) {
+ return Uni.createFrom()
+ .completionStage(sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn)))
+ .onItem().invoke(arn -> LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn))
+ .onItem().invoke(arn -> subscriptionArn = null)
+ .onItem().transform(arn -> Response.ok().build());
+ } else {
+ return Uni.createFrom().item(Response.status(400).entity("Not subscribed yet").build());
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/async/shield";
+ }
+
+ private void setSubscriptionArn(String arn) {
+ this.subscriptionArn = arn;
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}And we need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sns.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Queue Service (SQS) is a fully managed message queuing service. +Using SQS, you can send, store, and receive messages between software components at any volume, without losing messages or requiring other +services to be available. +SQS offers two types of message queues. Standard queues offer maximum throughput, best-effort ordering and at-least-once delivery. +SQS FIFO queues are designed to guarantee that messages are processes exactly once, on the exact order that they were sent.
+You can find more information about SQS at the Amazon SQS website.
+| + + | ++The SQS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SQS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SQS service
+Docker for your system to run SQS locally for testing purposes
+The easiest way to start working with SQS is to run a local instance using Dev Services.
+You can optionally configure the queues that are created on startup with the quarkus.sqs.devservices.queues config property.
You can also set up a local version of SQS manually, first start a LocalStack container:
+docker run --rm --name local-sqs -p 4566:4566 -e SERVICES=sqs -e START_WEB=0 -d localstack/localstack:1.4.0This starts a SQS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SQS queue using AWS CLI and store in QUEUE_URL environment variable.
QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue --profile localstack --endpoint-url=http://localhost:4566`Or, if you want to use your SQS queue on your AWS account create a queue using your default profile
+QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue`The application built here allows shooting an elementary particles (quarks) into a ColliderQueue queue of the AWS SQS.
+Additionally, we create a resource that allows receiving those quarks from the ColliderQueue queue in the order they were sent.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sqs-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sqs-quickstart \
+ -DclassName="org.acme.sqs.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sqs"
+cd amazon-sqs-quickstartThis command generates a Maven structure importing the RESTEasy Reactive and Amazon SQS Client extensions.
+After this, the amazon-sqs extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that sends quarks via the queue. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sqs.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sqs.QuarksCannonSyncResource that will provide an API to shoot quarks into the SQS queue using the synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ SendMessageResponse response = sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact messages sent to the queue must be a String, we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
Now, create the org.acme.QuarksShieldSyncResource REST resources that provides an endpoint to read the messages from the ColliderQueue queue.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public List<Quark> receive() {
+ List<Message> messages = sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)).messages();
+
+ return messages.stream()
+ .map(Message::body)
+ .map(this::toQuark)
+ .collect(Collectors.toList());
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}We are using here a Jackson’s ObjectReader in order to deserialize queue messages into our Quark POJOs.
Both SQS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SQS instance, configure it as follows:
+quarkus.sqs.endpoint-override=http://localhost:4566
+
+quarkus.sqs.aws.region=us-east-1
+quarkus.sqs.aws.credentials.type=static
+quarkus.sqs.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sqs.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sqs.aws.region - It’s required by the client, but since you’re using a local SQS instance use us-east-1 as it’s a default region of LocalStack’s SQS.
quarkus.sqs.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sqs.endpoint-override - Override the SQS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all SQS related properties. By default, the SQS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dqueue.url=$QUEUE_URL -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sqs.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(SendMessageResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SQS client, and then transform the emitted item.
And the corresponding async receiver of the queue messages org.acme.sqs.QuarksShieldAsyncResource
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+import software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public Uni<List<Quark>> receive() {
+ return Uni.createFrom()
+ .completionStage(sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)))
+ .onItem().transform(ReceiveMessageResponse::messages)
+ .onItem().transform(m -> m.stream().map(Message::body).map(this::toQuark).collect(Collectors.toList()));
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sqs.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Systems Manager (formerly Amazon Simple Systems Manager, or SSM) is a service that you can use to view and control your infrastructure on AWS. +One of the most useful features of SSM for microservices is the Parameter Store, which provides secure, hierarchical storage for configuration data management and secrets management..
+You can find more information about SSM at the AWS Systems Manager website.
+| + + | ++The SSM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SSM locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SSM service
+Docker for your system to run SSM locally for testing purposes
+The easiest way to start working with SSM is to run a local instance using Dev Services.
+You can also set up a local version of SSM manually, first start a LocalStack container:
+docker run --rm --name local-ssm --publish 4566:4583 -e SERVICES=ssm -e START_WEB=0 -d localstack/localstack:1.4.0This starts a SSM instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve parameters using the SSM parameter store.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ssm-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ssm-quickstart \
+ -DclassName="org.acme.ssm.QuarkusSsmSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ssm"
+cd amazon-ssm-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SSM Client extensions.
+After this, the amazon-ssm extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from SSM parameter store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.ssm.QuarkusSsmResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.ssm;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.ssm.model.GetParameterRequest;
+import software.amazon.awssdk.services.ssm.model.GetParametersByPathRequest;
+import software.amazon.awssdk.services.ssm.model.Parameter;
+import software.amazon.awssdk.services.ssm.model.ParameterType;
+import software.amazon.awssdk.services.ssm.model.PutParameterRequest;
+
+public abstract class QuarkusSsmResource {
+
+ @ConfigProperty(name = "parameters.path") (1)
+ String parametersPath;
+
+ @PostConstruct (2)
+ void normalizePath() {
+ if (!parametersPath.startsWith("/")) {
+ parametersPath = "/" + parametersPath;
+ }
+ if (!parametersPath.endsWith("/")) {
+ parametersPath = parametersPath + "/";
+ }
+ }
+
+ protected Collector<Parameter, ?, Map<String, String>> parametersToMap() { (3)
+ return toMap(p -> p.name().substring(parametersPath.length()), Parameter::value);
+ }
+
+ protected GetParametersByPathRequest generateGetParametersByPathRequest() {
+ return GetParametersByPathRequest.builder() (4)
+ .path(parametersPath)
+ .withDecryption(TRUE)
+ .build();
+ }
+
+ protected PutParameterRequest generatePutParameterRequest(String name, String value, boolean secure) {
+ return PutParameterRequest.builder() (5)
+ .name(parametersPath + name)
+ .value(value)
+ .type(secure ? ParameterType.SECURE_STRING : ParameterType.STRING)
+ .overwrite(TRUE)
+ .build();
+ }
+
+ protected GetParameterRequest generateGetParameterRequest(String name) {
+ return GetParameterRequest.builder() (6)
+ .name(parametersPath + name)
+ .withDecryption(TRUE)
+ .build();
+ }
+}| 1 | +Inject a configured path under which to store parameters | +
| 2 | +Ensure the path starts and ends with / |
+
| 3 | +Collect parameters into a map of simple names and values | +
| 4 | +Generate a request for all parameters under the configured path | +
| 5 | +Generate a request to set a specific parameter | +
| 6 | +Generate a request to get a specific parameter value | +
Now, we can extend the class and create the synchronous implementation in the org.acme.ssm.QuarkusSsmSyncResource class.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.resteasy.reactive.RestQuery;
+
+import software.amazon.awssdk.services.ssm.SsmClient;
+
+@Path("/sync")
+public class QuarkusSsmSyncResource extends QuarkusSsmResource {
+
+ @Inject (1)
+ SsmClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Map<String, String> getParameters() {
+ return ssm.getParametersByPath(generateGetParametersByPathRequest())
+ .parameters().stream().collect(parametersToMap());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ ssm.putParameter(generatePutParameterRequest(name, value, secure));
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String getParameter(String name) {
+ return ssm.getParameter(generateGetParameterRequest(name))
+ .parameter().value();
+ }
+}| 1 | +Inject the client provided by the amazon-ssm extension | +
Using the Amazon SSM SDK, we can easily store and retrieve arbitrary name/value pairs, and we can optionally store the values in a secure manner.
+Both SSM clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local SSM instance, configure it as follows:
+quarkus.ssm.endpoint-override=http://localhost:4566 (1)
+
+quarkus.ssm.aws.region=us-east-1 (2)
+quarkus.ssm.aws.credentials.type=static (3)
+quarkus.ssm.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ssm.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the SSM client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon SSM related properties. By default, the SSM client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ssm.QuarkusSsmAsyncResource REST resource that will be similar to our QuarkusSsmSyncResource but using an asynchronous programming model.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import org.jboss.resteasy.reactive.RestQuery;
+import software.amazon.awssdk.services.ssm.SsmAsyncClient;
+
+@Path("/async")
+public class QuarkusSsmAsyncResource extends QuarkusSsmResource {
+
+ @Inject
+ SsmAsyncClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<Map<String, String>> getParameters() {
+ return Uni.createFrom().completionStage(ssm.getParametersByPath(generateGetParametersByPathRequest()))
+ .onItem().transform(r -> r.parameters().stream().collect(parametersToMap()));
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ return Uni.createFrom().completionStage(ssm.putParameter(generatePutParameterRequest(name, value, secure)))
+ .onItem().transform(r -> null);
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> getParameter(String name) {
+ return Uni.createFrom().completionStage(ssm.getParameter(generateGetParameterRequest(name)))
+ .onItem().transform(r -> r.parameter().value());
+ }
+}Note that the SsmAsyncClient behaves just like the SsmClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ssm.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege credentials for users.
+You can find more information about STS at AWS Security Token Service API Reference.
+| + + | ++The STS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use STS locally and on AWS.
+To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the STS service
+Docker for your system to run STS locally for testing purposes
+The easiest way to start working with STS is to run a local instance using Dev Services.
+You can also set up a local version of STS manually, first start a LocalStack container:
+docker run --rm --name local-sts --publish 4592:4592 -e SERVICES=sts -e START_WEB=0 -d localstack/localstack:1.0.3This starts a STS instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.3.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sts-quickstart \
+ -DclassName="org.acme.sts.QuarkusStsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sts"
+cd amazon-sts-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon STS Client extensions.
+After this, the amazon-sts extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both STS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use Apache HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you’re going to use a local STS instance, configure it as follows:
+quarkus.sts.endpoint-override=http://localhost:4592 (1)
+
+quarkus.sts.aws.region=us-east-1 (2)
+quarkus.sts.aws.credentials.type=static (3)
+quarkus.sts.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sts.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the STS client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon STS related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sts.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Quarkus Amazon Services automatically starts a LocalStack container in dev mode and when running tests. So, you don’t have to start one manually. The extension client is configured automatically.
+Dev Services for Amazon Services is automatically enabled for each extensions added to pom.xml except in the following situations:
quarkus.devservices.enabled is set to false
devservices.enabled is set to false per extension (eg. quarkus.s3.devservices.enabled=false)
the endpoint-override is configured (eg. quarkus.s3.endpoint-override=http://localhost:4566)
Your environment does not support Docker
+By default, Dev Services for Amazon Services will start one LocalStack container with only the needed services.
+If you need to share a particular service between applications, Dev Services for Amazon Services implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single container. To ease sharing, each service will be started in its own container.
+Dev Services for Amazon Services starts the container with the quarkus-dev-service-localstack label and service name as the value, which is used to identify the container.
+If you need multiple (shared) container, you can configure the devservices.service-name attribute for a given extension (eg. quarkus.s3.devservices.services-name) and indicate the container name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is localstack.
Sharing is disabled by default in dev mode, and is always disabled in test mode. You can enable the sharing with devservices.shared=true for a given extension (e.g. quarkus.s3.devservices.shared=true). All other non-shared services will be grouped in another container.
Dev Services for Amazon Services uses localstack/localstack image. You can configure the image and version using the quarkus.aws.devservices.localstack.image-name property:
quarkus.aws.devservices.localstack.image-name=localstack/localstack:1.4.0Dev Services for Amazon Services can support specific properties sent to the container. It can be globally applied to all containers or be specified per service as follows:
+quarkus.aws.devservices.localstack.container-properties.START_WEB=0
+quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1GRefer to the LocalStack documentation for more configuration : https://docs.localstack.cloud/localstack/configuration/#local-aws-services. Note that not all environment variables are supported and some may affect Dev Services for Amazon Services.
+To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:
quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
+quarkus.aws.devservices.localstack.additional-services."redshift".enabled=trueThe key is the name of the service to enable and must be a valid LocalStack service name.
+Some extensions support additional configuration to be applied at startup. Refer to the extension documentation.
+The Cognito extension is not using LocalStack but Moto.
+Dev Services for Amazon Services uses the latest motoserver/moto image. You can configure the image and version using the quarkus.aws.devservices.moto.image-name property:
quarkus.aws.devservices.moto.image-name=motoserver/moto:3.0.2Dev Services for Amazon Services can support specific properties sent to the container as follows:
+quarkus.aws.devservices.moto.container-properties.MOTO_COGNITO_IDP_USER_POOL_ID_STRATEGY=HASHConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
This set of extensions expose AWS services through configuration properties and CDI injection.
+You can find the full set of supported services and documentation for each of them in the navigation on the left.
+Service client for accessing Amazon Cognito user pools (Identity Provider).
+Using the Amazon Cognito user pools API, you can create a user pool to manage directories and users. +You can authenticate a user to obtain tokens related to user identity and access policies.
+For more information, see the Amazon Cognito user pools (AWS Java SDK 2.x docs).
+| + + | ++The Cognito User Pools extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Cognito User Pool locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+One of:
+An AWS Account to access the Cognito service
+Or Docker for your system to run Cognito locally for testing purposes
+The easiest way to start working with Cognito is to run a local instance using Dev Services.
+You can also set up a local version of Cognito manually, first start a local instance as a container:
+docker run --rm --name moto -p 5000:5000 -d motoserver/moto:3.0.2This starts a Cognito mock instance that is accessible on port 5000.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile moto
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: testCreate a Cognito user pool using AWS CLI.
+aws --profile moto --endpoint-url=http://localhost:5000 cognito-idp create-user-pool --pool-name quarkus-users-devOr, if you want to use your Cognito user pool on your AWS account create a user pool using your default profile
+aws cognito-user-pools cognito-idp --pool-name quarkus-users-devThe application built here shows the count of Cognito User Pools in the current region.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-cognito-user-pools-quickstart \
+ -DclassName="org.acme.cognitouserpools.CognitoExampleResource" \
+ -Dpath="/cognito-example" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-cognito-user-pools,resteasy-mutiny"
+cd amazon-cognito-user-pools-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Cognito User Pool extensions.
+After this, the amazon-cognito-user-pools extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Edit a org.acme.cognitouserpools.CognitoExampleResource that will provide an API return count of Cognito User Pools using the synchronous client.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsResponse;
+
+@Path("/cognito-example")
+public class CognitoExampleResource {
+ @Inject
+ CognitoIdentityProviderClient cognitoClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ ListUserPoolsResponse response = cognitoClient.listUserPools(request);
+ return String.format("You have %d user pools", response.userPools().size());
+ }
+}And update test class:
+package org.acme.cognitouserpools;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.Test;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+
+@QuarkusTest
+public class CognitoExampleResourceTest {
+
+ @Test
+ public void testHelloEndpoint() {
+ given()
+ .when().get("/cognito-example")
+ .then()
+ .statusCode(200)
+ .body(is("You have 1 user pools"));
+ }
+
+}Both Cognito clients (sync and async) are configurable via the application.properties file that
+can be provided in the src/main/resources directory.
Additionally, you need to add to the classpath a proper implementation of the sync client.
+By default the extension uses the URL connection HTTP client, so you need to add a URL connection
+client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Cognito mock instance, configure it as follows:
+quarkus.cognito-user-pools.endpoint-override=http://localhost:5000
+
+quarkus.cognito-user-pools.aws.region=eu-west-1
+quarkus.cognito-user-pools.aws.credentials.type=static
+quarkus.cognito-user-pools.aws.credentials.static-provider.access-key-id=test-key
+quarkus.cognito-user-pools.aws.credentials.static-provider.secret-access-key=test-secretquarkus.cognito-user-pools.aws.region - It’s required by the client, but since you’re using a local Cognito mock instance use us-east-1 as it’s a default region of moto.
quarkus.cognito-user-pools.aws.credentials - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.cognito-user-pools.endpoint-override - Override the Cognito User Pools client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Cognito User Pools
+related properties. By default, the Cognito User Pools client extension will use the default
+credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.cognitouserpools.CognitoAsyncExampleResource REST resource that will be similar to our
+CognitoExampleResource but using an asynchronous programming model.
package org.acme.cognitouserpools;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderAsyncClient;
+import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUserPoolsRequest;
+
+@Path("/cognito-async-example")
+public class CognitoAsyncExampleResource {
+ @Inject
+ CognitoIdentityProviderAsyncClient cognitoAsyncClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> hello() {
+ ListUserPoolsRequest request = ListUserPoolsRequest.builder().build();
+ return Uni
+ .createFrom()
+ .completionStage(cognitoAsyncClient.listUserPools(request))
+ .map(response -> {
+ return String.format("You have %d user pools", response.userPools().size());
+ });
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous Cognito
+Identity Provider client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.cognito-user-pools.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+DynamoDB is a scalable AWS managed NoSQL database. +It supports both key-value and document data models, that enables to have a flexible schema for your data. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about DynamoDB at the Amazon DynamoDB website.
+| + + | ++The DynamoDB extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). +Keep in mind it’s actively developed and does not support yet all the features available in SDK 1.x such as Document APIs + | +
The Quarkus extension supports the traditional DynamoDB client as well as the enhanced client.
+It supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the DynamoDB service
+Optionally, Docker for your system to run DynamoDB locally for testing purposes
+The easiest way to start working with DynamoDB is to run a local instance using Dev Services.
+You can also set up a local version of DynamoDB manually, first start a local instance as a container:
+docker run --publish 4566:8000 amazon/dynamodb-local:1.19.0 -jar DynamoDBLocal.jar -inMemory -sharedDbThis starts a DynamoDB instance that is accessible on port 4566.
+You can check if it’s working with aws dynamodb list-tables --endpoint-url http://localhost:4566.
{
+ "TableNames": []
+}You should see the output above in your terminal. That’s it, DynamoDB runs locally.
+Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.
+Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. +For more information, see Setting Up DynamoDB (Web Service).
+We recommend to use the AWS CLI to provision the table:
+The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-dynamodb-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-dynamodb-quickstart \
+ -DclassName="org.acme.dynamodb.FruitResource" \
+ -Dpath="/fruits" \
+ -Dextensions="resteasy-reactive-jackson,amazon-dynamodb"
+cd amazon-dynamodb-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and DynamoDB Client extensions.
+After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Fruit bean as follows:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ public static Fruit from(Map<String, AttributeValue> item) {
+ Fruit fruit = new Fruit();
+ if (item != null && !item.isEmpty()) {
+ fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
+ fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
+ }
+ return fruit;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map
+object provided by the DynamoDB client response.
Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.
package org.acme.dynamodb;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
+import software.amazon.awssdk.services.dynamodb.model.ScanRequest;
+
+public abstract class AbstractService {
+
+ public final static String FRUIT_NAME_COL = "fruitName";
+ public final static String FRUIT_DESC_COL = "fruitDescription";
+ public final static String FRUIT_TABLE_NAME = "QuarkusFruits";
+
+ protected ScanRequest scanRequest() {
+ return ScanRequest.builder().tableName(FRUIT_TABLE_NAME)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
+ }
+
+ protected PutItemRequest putRequest(Fruit fruit) {
+ Map<String, AttributeValue> item = new HashMap<>();
+ item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
+ item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());
+
+ return PutItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .item(item)
+ .build();
+ }
+
+ protected GetItemRequest getRequest(String name) {
+ Map<String, AttributeValue> key = new HashMap<>();
+ key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());
+
+ return GetItemRequest.builder()
+ .tableName(FRUIT_TABLE_NAME)
+ .key(key)
+ .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
+ .build();
+ }
+}Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ DynamoDbClient dynamoDB;
+
+ public List<Fruit> findAll() {
+ return dynamoDB.scanPaginator(scanRequest()).items().stream()
+ .map(Fruit::from)
+ .collect(Collectors.toList());
+ }
+
+ public void add(Fruit fruit) {
+ dynamoDB.putItem(putRequest(fruit));
+ }
+
+ public Fruit get(String name) {
+ return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
+ }
+}Now, edit the org.acme.dynamodb.FruitResource class as follows:
package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/fruits")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class FruitResource {
+
+ @Inject
+ FruitSyncService service;
+
+ @GET
+ public List<Fruit> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Fruit getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public List<Fruit> add(Fruit fruit) {
+ service.add(fruit);
+ return getAll();
+ }
+}The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.
DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.dynamodb.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local DynamoDB instance, configure it as follows:
+quarkus.dynamodb.endpoint-override=http://localhost:4566
+
+quarkus.dynamodb.aws.region=eu-central-1
+quarkus.dynamodb.aws.credentials.type=static
+quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
+quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secretquarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.
quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.dynamodb.aws.region=<YOUR_REGION>
+quarkus.dynamodb.aws.credentials.type=defaultquarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,
quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ @Inject
+ DynamoDbAsyncClient dynamoDB;
+
+ public Uni<List<Fruit>> findAll() {
+ return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
+ .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
+ }
+
+ public Uni<Void> add(Fruit fruit) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit))).replaceWithVoid();
+ }
+
+ public Uni<Fruit> get(String name) {
+ return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
+ .onItem().transform(resp -> Fruit.from(resp.item()));
+ }
+}In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.
Then, create an asynchronous REST resource that consumes this async service:
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+import io.smallrye.mutiny.Uni;
+
+@Path("/async-fruits")
+public class FruitAsyncResource {
+
+ @Inject
+ FruitAsyncService service;
+
+ @GET
+ public Uni<List<Fruit>> getAll() {
+ return service.findAll();
+ }
+
+ @GET
+ @Path("{name}")
+ public Uni<Fruit> getSingle(String name) {
+ return service.get(name);
+ }
+
+ @POST
+ public Uni<List<Fruit>> add(Fruit fruit) {
+ return service.add(fruit)
+ .onItem().ignore().andSwitchTo(this::getAll);
+ }
+}And add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.dynamodb.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>The DynamoDB enhanced client is part of the AWS SDK for Java version 2 and makes the mapping between DynamoDB Tables and Java beans very easy.
+The Enhanced Client requires a TableSchema which can be generated from a bean class annotated with DynamoDbBean or DynamoDbImmutable or generated from code.
+By default, TableSchemas generated from bean classes are registered and cached at startup. You don’t need to explicitely instantiate them at class-load time.
+It has both a sync and an async variants.
To use the enhanced client, add the quarkus-amazon-dynamodb-enhanced extension to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-dynamodb-enhanced</artifactId>
+</dependency>The Fruit bean would look like this:
package org.acme.dynamodb;
+
+import java.util.Map;
+import java.util.Objects;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
+import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
+import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
+
+@RegisterForReflection
+@DynamoDbBean
+public class Fruit {
+
+ private String name;
+ private String description;
+
+ public Fruit() {
+ }
+
+ @DynamoDbPartitionKey
+ @DynamoDbAttribute(AbstractService.FRUIT_NAME_COL)
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ @DynamoDbAttribute(AbstractService.FRUIT_DESC_COL)
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.name, this.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.name);
+ }
+}Note that you don’t need to add @RegisterForReflection anymore.
The FruitSyncService would need to use the DynamoDbEnhancedClient as well as create a TableSchema:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ private DynamoDbTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedSyncService(DynamoDbEnhancedClient dynamoEnhancedClient) {
+ fruitTable = dynamoEnhancedClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}The same goes for the asynchronous version with DynamoDbEnhanceAsyncdClient:
package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitAsyncService extends AbstractService {
+
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ @Inject
+ FruitEnhancedAsyncService(DynamoDbEnhancedAsyncClient dynamoEnhancedAsyncClient) {
+ fruitTable = dynamoEnhancedAsyncClient.table(FRUIT_TABLE_NAME,
+ TableSchema.fromClass(Fruit.class));
+ }
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}Resource classes remain unchanged.
+Alternatively, if you only need to use the DynamoDbTable instance, you can inject it directly with a @NamedDynamoDbTable annotation.
The synchronous version would be :
+package org.acme.dynamodb;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+
+@ApplicationScoped
+public class FruitSyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ DynamoDbTable<Fruit> fruitTable;
+
+ public List<Fruit> findAll() {
+ return fruitTable.scan().items().stream().collect(Collectors.toList());
+ }
+
+ public List<Fruit> add(Fruit fruit) {
+ fruitTable.putItem(fruit);
+ return findAll();
+ }
+
+ public Fruit get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return fruitTable.getItem(partitionKey);
+ }
+}And the asynchronous version :
+package org.acme.dynamodb;
+
+import java.util.List;
+
+import io.quarkus.amazon.dynamodb.enhanced.runtime.NamedDynamoDbTable;
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable;
+import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
+import software.amazon.awssdk.enhanced.dynamodb.Key;
+import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
+
+@ApplicationScoped
+public class FruitEnhancedAsyncService extends AbstractService {
+
+ @Inject
+ @NamedDynamoDbTable(FRUIT_TABLE_NAME)
+ private DynamoDbAsyncTable<Fruit> fruitTable;
+
+ public Uni<List<Fruit>> findAll() {
+ return Multi.createFrom().publisher(AdaptersToFlow.publisher(fruitTable.scan().items())).collect().asList();
+ }
+
+ public Uni<Void> add(Fruit fruit){
+ return Uni.createFrom().completionStage(() -> fruitTable.putItem(fruit));
+}
+
+ public Uni<Fruit> get(String name) {
+ Key partitionKey = Key.builder().partitionValue(name).build();
+ return Uni.createFrom().completionStage(() -> fruitTable.getItem(partitionKey));
+ }
+}You can find more information about the DynamoDB enhanced client in the AWS documentation:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Amazon EventBridge is a serverless event bus service that makes it easy to connect your applications with data from a variety of sources.
+You can find more information about EventBridge at AWS EventBridge Data Streams Service API Reference.
+| + + | ++The EventBridge extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use EventBridge locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the EventBridge service
+Docker for your system to run EventBridge locally for testing purposes
+The easiest way to start working with EventBridge is to run a local instance using Dev Services.
+You can also set up a local version of EventBridge manually, first start a LocalStack container:
+docker run --rm --name local-eventbridge --publish 4592:4592 -e SERVICES=events -e START_WEB=0 -d localstack/localstack:3.0.1This starts a EventBridge instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-eventbridge-quickstart \
+ -DclassName="org.acme.eventbridge.QuarkusEventBridgeSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-eventbridge"
+cd amazon-eventbridge-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon EventBridge Client extensions.
+After this, the amazon-eventbridge extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both EventBridge clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.eventbridge.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.eventbridge.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local EventBridge instance, configure it as follows:
+quarkus.eventbridge.endpoint-override=http://localhost:4592 (1)
+
+quarkus.eventbridge.aws.region=us-east-1 (2)
+quarkus.eventbridge.aws.credentials.type=static (3)
+quarkus.eventbridge.aws.credentials.static-provider.access-key-id=test-key
+quarkus.eventbridge.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the EventBridge client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon EventBridge related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.eventbridge.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Identity and Access Management (IAM) enables users to manage access to AWS services and resources securely.
+You can find more information about IAM at the Amazon IAM website.
+| + + | ++The IAM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Kinesis Data Streams is a managed service provided by Amazon Web Services (AWS) that scales elastically for real-time processing of streaming big data.
+You can find more information about Kinesis at AWS Kinesis Data Streams Service API Reference.
+| + + | ++The Kinesis extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use Kinesis locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Kinesis service
+Docker for your system to run Kinesis locally for testing purposes
+The easiest way to start working with Kinesis is to run a local instance using Dev Services.
+You can also set up a local version of Kinesis manually, first start a LocalStack container:
+docker run --rm --name local-kinesis --publish 4592:4592 -e SERVICES=kinesis -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Kinesis instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kinesis-quickstart \
+ -DclassName="org.acme.kinesis.QuarkusKinesisSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kinesis"
+cd amazon-kinesis-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon Kinesis Client extensions.
+After this, the amazon-kinesis extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both Kinesis clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.kinesis.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kinesis.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Kinesis instance, configure it as follows:
+quarkus.kinesis.endpoint-override=http://localhost:4592 (1)
+
+quarkus.kinesis.aws.region=us-east-1 (2)
+quarkus.kinesis.aws.credentials.type=static (3)
+quarkus.kinesis.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kinesis.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Kinesis client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Kinesis related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kinesis.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Key Management Service (KMS) is a service that allows you to create and control the keys used to encrypt or digitally sign your data. +Using KMS, you can create and manage cryptographic keys and control their use across a wide range of AWS services and in your application.
+You can find more information about KMS at the AWS KMS website.
+| + + | ++The KMS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use KMS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the KMS service
+Docker for your system to run KMS locally for testing purposes
+The easiest way to start working with KMS is to run a local instance using Dev Services.
+You can also set up a local version of KMS manually, first start a LocalStack container:
+docker run --rm --name local-kms --publish 4566:4599 -e SERVICES=kms -e START_WEB=0 -d localstack/localstack:3.0.1This starts a KMS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a KMS master key queue using AWS CLI and store in MASTER_KEY_ARN environment variable.
MASTER_KEY_ARN=`aws kms create-key --profile localstack --endpoint-url=http://localhost:4566 | cut -f3`Generate a key data as 256-bit symmetric key (AES 256)
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256 --profile localstack --endpoint-url=http://localhost:4566Or, if you want to use your AWS account create a key using your default profile
+MASTER_KEY_ARN=`aws kms create-key | cut -f3`
+aws kms generate-data-key --key-id $MASTER_KEY_ARN --key-spec AES_256The application built here allows to encrypt and decrypt text messages using a master key created on AWS KMS.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-kms-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-kms-quickstart \
+ -DclassName="org.acme.kms.QuarkusKmsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-kms"
+cd amazon-kms-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon KMS Client extensions.
+After this, the amazon-kms extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to encrypt and decrypt text message provided in the request. +The example application will demonstrate the two programming models supported by the extension.
+Let’s create a org.acme.kms.QuarkusKmsSyncResource that will provide an API to encrypt and decrypt message using the synchronous client.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsSyncResource {
+
+ @Inject
+ KmsClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public String encrypt(String data) {
+ SdkBytes encryptedBytes = kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))).ciphertextBlob();
+
+ return Base64.getEncoder().encodeToString(encryptedBytes.asByteArray());
+ }
+
+ @POST
+ @Path("/decrypt")
+ public String decrypt(String data) {
+ SdkBytes encryptedData = SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes()));
+ DecryptResponse decrypted = kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(encryptedData));
+
+ return decrypted.plaintext().asUtf8String();
+ }
+}An encrypted message is in the form of a bytes array. To return it to the user we need to encode it as Base64 string in the encrypt endpoint.
+On the decrypt endpoint we need to decode from the Base64 string back to the bytes array before sending it out to the KMS client.
Both KMS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kms.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local KMS instance, configure it as follows:
+quarkus.kms.endpoint-override=http://localhost:4566
+
+quarkus.kms.aws.region=us-east-1
+quarkus.kms.aws.credentials.type=static
+quarkus.kms.aws.credentials.static-provider.access-key-id=test-key
+quarkus.kms.aws.credentials.static-provider.secret-access-key=test-secretquarkus.kms.aws.region - It’s required by the client, but since you’re using a local KMS instance use us-east-1 as it’s a default region of LocalStack’s KMS.
quarkus.kms.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.kms.endpoint-override - Override the KMS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon KMS related properties. By default, the KMS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dkey.arn=$MASTER_KEY_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.kms.QuarkusKmsAsyncResource REST resource that will be similar to our QuarkusKmsSyncResource but using an asynchronous programming model.
package org.acme.kms;
+
+import java.util.Base64;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.kms.KmsAsyncClient;
+import software.amazon.awssdk.services.kms.model.DecryptResponse;
+import software.amazon.awssdk.services.kms.model.EncryptResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.TEXT_PLAIN)
+public class QuarkusKmsAsyncResource {
+
+ @Inject
+ KmsAsyncClient kms;
+
+ @ConfigProperty(name = "key.arn")
+ String keyArn;
+
+ @POST
+ @Path("/encrypt")
+ public Uni<String> encrypt(String data) {
+ return Uni.createFrom().completionStage(kms.encrypt(req -> req.keyId(keyArn).plaintext(SdkBytes.fromUtf8String(data))))
+ .onItem().transform(EncryptResponse::ciphertextBlob)
+ .onItem().transform(blob -> Base64.getEncoder().encodeToString(blob.asByteArray()));
+ }
+
+ @POST
+ @Path("/decrypt")
+ public Uni<String> decrypt(String data) {
+ return Uni.createFrom().item(SdkBytes.fromByteArray(Base64.getDecoder().decode(data.getBytes())))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(kms.decrypt(req -> req.keyId(keyArn).ciphertextBlob(msg)))
+ )
+ .onItem().transform(DecryptResponse::plaintext)
+ .onItem().transform(SdkBytes::asUtf8String);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous KMS client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.kms.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Service client for accessing Amazon Lambda.
+Using the Amazon Lambda API, you can manage your AWS Lambdas.
+You can find more information about Lambda at the AWS Lambda website.
+| + + | ++The Lambda extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Lambda locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Lambda service
+Docker for your system to run Lambda locally for testing purposes
+The easiest way to start working with Lambda is to run a local instance using Dev Services.
+You can also set up a local version of Lambda manually, first start a LocalStack container:
+docker run --rm --name local-lambda --publish 4566:4583 -e SERVICES=lambda -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Lambda instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-lambda-quickstart \
+ -DclassName="org.acme.lambda.QuarkusLambdaSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-lambda"
+cd amazon-lambda-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon Lambda Client extensions.
+After this, the amazon-lambda extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both Lambda clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.lambda.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.lambda.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Lambda instance, configure it as follows:
+quarkus.lambda.endpoint-override=http://localhost:4566 (1)
+
+quarkus.lambda.aws.region=us-east-1 (2)
+quarkus.lambda.aws.credentials.type=static (3)
+quarkus.lambda.aws.credentials.static-provider.access-key-id=test-key
+quarkus.lambda.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Lambda client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Lambda related properties. By default, the Lambda client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.lambda.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon S3 is an object storage service. It can be employed to store any type of object which allows for uses like storage for Internet applications, +backup and recovery, disaster recovery, data archives, data lakes for analytics, any hybrid cloud storage. +This extension provides functionality that allows the client to communicate with the service when running in Quarkus. +You can find more information about S3 at the Amazon S3 website.
+| + + | ++The S3 extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use S3 locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the S3 service. Before you can use the AWS SDKs with Amazon S3, you must get an AWS access key ID and secret access key.
+Optionally, Docker for your system to run S3 locally for testing purposes
+The easiest way to start working with S3 is to run a local instance using Dev Services.
+You can optionally configure the buckets that are created on startup with the quarkus.s3.devservices.buckets config property.
You can also setup a local version of S3 manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=s3 -e START_WEB=0 localstack/localstack:3.0.1This starts a S3 instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to manage files stored in Amazon S3.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-s3-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-s3-quickstart \
+ -DclassName="org.acme.s3.S3SyncClientResource" \
+ -Dpath="/s3" \
+ -Dextensions="resteasy-reactive-jackson,amazon-s3"
+cd amazon-s3-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and S3 Client extensions.
+After this, the amazon-s3 extension has been added to your pom.xml.
| + + | +
+The default setting for quarkus.http.limits.max-body-size is 10240K. This may limit your ability to upload multipart files larger than the default. If you want to upload larger files, you will need to set this limit explicitly.
+ |
+
In this example, we will create an application to manage a list of files. The example application will demonstrate the two programming models supported by the extension.
+Because the primary goal of our application is to upload a file into the S3 bucket, we need to setup the model we will be using to define the multipart/form-data payload,
+in the form of a @MultipartForm POJO.
Create a org.acme.s3.FormData class as follows:
package org.acme.s3;
+
+import java.io.File;
+import jakarta.ws.rs.core.MediaType;
+import org.jboss.resteasy.reactive.PartType;
+import org.jboss.resteasy.reactive.RestForm;
+
+public class FormData {
+
+ @RestForm("file")
+ public File data;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String filename;
+
+ @RestForm
+ @PartType(MediaType.TEXT_PLAIN)
+ public String mimetype;
+
+}The class defines three fields:
+data that fill capture stream of uploaded bytes from the client
fileName that captures a filename as provided by the submited form
mimeType content type of the uploaded file
In the second step let’s create a bean that will represent a file in a Amazon S3 bucket as follows:
+package org.acme.s3;
+
+import software.amazon.awssdk.services.s3.model.S3Object;
+
+public class FileObject {
+ private String objectKey;
+
+ private Long size;
+
+ public FileObject() {
+ }
+
+ public static FileObject from(S3Object s3Object) {
+ FileObject file = new FileObject();
+ if (s3Object != null) {
+ file.setObjectKey(s3Object.key());
+ file.setSize(s3Object.size());
+ }
+ return file;
+ }
+
+ public String getObjectKey() {
+ return objectKey;
+ }
+
+ public Long getSize() {
+ return size;
+ }
+
+ public FileObject setObjectKey(String objectKey) {
+ this.objectKey = objectKey;
+ return this;
+ }
+
+ public FileObject setSize(Long size) {
+ this.size = size;
+ return this;
+ }
+}Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the S3Object
+object provided by the S3 client response when listing all the objects in a bucket.
Now create a org.acme.s3.CommonResource that will consist of methods to prepare S3 request to get object from a S3 bucket, or to put file into a S3 bucket.
+Note a configuration property bucket.name is defined here as the request method required name of the S3 bucket.
package org.acme.s3;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+
+abstract public class CommonResource {
+
+ @ConfigProperty(name = "bucket.name")
+ String bucketName;
+
+ protected PutObjectRequest buildPutRequest(FormData formData) {
+ return PutObjectRequest.builder()
+ .bucket(bucketName)
+ .key(formData.filename)
+ .contentType(formData.mimetype)
+ .build();
+ }
+
+ protected GetObjectRequest buildGetRequest(String objectKey) {
+ return GetObjectRequest.builder()
+ .bucket(bucketName)
+ .key(objectKey)
+ .build();
+ }
+
+}Then, create a org.acme.s3.S3SyncClientResource that will provides an API to upload/download files as well as to list all the files in a bucket.
package org.acme.s3;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.ResponseBuilder;
+import jakarta.ws.rs.core.Response.Status;
+import software.amazon.awssdk.core.ResponseBytes;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.PutObjectResponse;
+
+
+@Path("/s3")
+public class S3SyncClientResource extends CommonResource {
+ @Inject
+ S3Client s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Response uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Response.status(Status.BAD_REQUEST).build();
+ }
+
+ PutObjectResponse putResponse = s3.putObject(buildPutRequest(formData),
+ RequestBody.fromFile(formData.data));
+ if (putResponse != null) {
+ return Response.ok().status(Status.CREATED).build();
+ } else {
+ return Response.serverError().build();
+ }
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public Response downloadFile(String objectKey) {
+ ResponseBytes<GetObjectResponse> objectBytes = s3.getObjectAsBytes(buildGetRequest(objectKey));
+ ResponseBuilder response = Response.ok(objectBytes.asUtf8String());
+ response.header("Content-Disposition", "attachment;filename=" + objectKey);
+ response.header("Content-Type", objectBytes.response().contentType());
+ return response.build();
+ }
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public List<FileObject> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder().bucket(bucketName).build();
+
+ //HEAD S3 objects to get metadata
+ return s3.listObjects(listRequest).contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}Both S3 clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
| + + | +
+You need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+add a URL connection client dependency to the pom.xml file:
+ |
+
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=apacheAnd add following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.s3.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>For asynchronous client refer to Going asynchronous for more information.
+If you’re going to use a local S3 instance, configure it as follows:
+quarkus.s3.endpoint-override=http://localhost:4566
+
+quarkus.s3.aws.region=us-east-1
+quarkus.s3.aws.credentials.type=static
+quarkus.s3.aws.credentials.static-provider.access-key-id=test-key
+quarkus.s3.aws.credentials.static-provider.secret-access-key=test-secret
+
+bucket.name=quarkus.s3.quickstartquarkus.s3.aws.region - It’s required by the client, but since you’re using a local S3 instance you can pick any valid AWS region.
quarkus.s3.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.s3.endpoint-override - Override the S3 client to use a local instance instead of an AWS service
bucket.name - Name of the S3 bucket
If you want to work with an AWS account, you’d need to set it with:
+bucket.name=<your-bucket-name>
+
+quarkus.s3.aws.region=<YOUR_REGION>
+quarkus.s3.aws.credentials.type=defaultbucket.name - name of the S3 bucket on your AWS account.
quarkus.s3.aws.region you should set it to the region where your S3 bucket was created,
quarkus.s3.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Now let’s add a simple web page to interact with our S3SyncClientResource.
+Quarkus automatically serves static resources located under the META-INF/resources directory.
+In the src/main/resources/META-INF/resources directory, add a s3.html file with the content from this s3.html file in it.
You can now interact with your REST service:
+start Quarkus with ./mvnw compile quarkus:dev
open a browser to http://localhost:8080/s3.html
upload new file to the current S3 bucket via the form and see the list of files in the bucket
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.s3.S3AsyncClientResource that will be similar to our S3SyncClientResource but using an asynchronous programming model.
package org.acme.s3;
+
+import java.nio.ByteBuffer;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.Status;
+import mutiny.zero.flow.adapters.AdaptersToFlow;
+
+import org.jboss.resteasy.reactive.RestMulti;
+import org.reactivestreams.Publisher;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+import io.vertx.core.buffer.Buffer;
+import software.amazon.awssdk.core.async.AsyncRequestBody;
+import software.amazon.awssdk.core.async.AsyncResponseTransformer;
+import software.amazon.awssdk.services.s3.S3AsyncClient;
+import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
+import software.amazon.awssdk.services.s3.model.ListObjectsResponse;
+
+@Path("/async-s3")
+public class S3AsyncClientResource extends CommonResource {
+ @Inject
+ S3AsyncClient s3;
+
+ @POST
+ @Path("upload")
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ public Uni<Response> uploadFile(FormData formData) throws Exception {
+
+ if (formData.filename == null || formData.filename.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ if (formData.mimetype == null || formData.mimetype.isEmpty()) {
+ return Uni.createFrom().item(Response.status(Status.BAD_REQUEST).build());
+ }
+
+ return Uni.createFrom()
+ .completionStage(() -> {
+ return s3.putObject(buildPutRequest(formData), AsyncRequestBody.fromFile(formData.data));
+ })
+ .onItem().ignore().andSwitchTo(Uni.createFrom().item(Response.created(null).build()))
+ .onFailure().recoverWithItem(th -> {
+ th.printStackTrace();
+ return Response.serverError().build();
+ });
+ }
+
+ @GET
+ @Path("download/{objectKey}")
+ @Produces(MediaType.APPLICATION_OCTET_STREAM)
+ public RestMulti<Buffer> downloadFile(String objectKey) {
+
+ return RestMulti.fromUniResponse(Uni.createFrom()
+ .completionStage(() -> s3.getObject(buildGetRequest(objectKey),
+ AsyncResponseTransformer.toPublisher())),
+ response -> Multi.createFrom().safePublisher(AdaptersToFlow.publisher((Publisher<ByteBuffer>) response))
+ .map(S3AsyncClientResource::toBuffer),
+ response -> Map.of("Content-Disposition", List.of("attachment;filename=" + objectKey), "Content-Type",
+ List.of(response.response().contentType())));
+ }
+
+ @GET
+ public Uni<List<FileObject>> listFiles() {
+ ListObjectsRequest listRequest = ListObjectsRequest.builder()
+ .bucket(bucketName)
+ .build();
+
+ return Uni.createFrom().completionStage(() -> s3.listObjects(listRequest))
+ .onItem().transform(result -> toFileItems(result));
+ }
+
+ private static Buffer toBuffer(ByteBuffer bytebuffer) {
+ byte[] result = new byte[bytebuffer.remaining()];
+ bytebuffer.get(result);
+ return Buffer.buffer(result);
+ }
+
+ private List<FileObject> toFileItems(ListObjectsResponse objects) {
+ return objects.contents().stream()
+ .map(FileObject::from)
+ .sorted(Comparator.comparing(FileObject::getObjectKey))
+ .collect(Collectors.toList());
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.s3.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you want to use the AWS CRT-based S3 client, add the io.quarkus.amazon.s3.runtime.S3Crt qualifier as follows:
@Inject
+@S3Crt
+S3AsyncClient s3;And add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Amazon S3 Transfer Manager is high-level file transfer utility based on the S3 client. The extension provides functionality that allows to use S3TransferManager when running in Quarkus.
+You can find more information about S3 Transfer Manager at the Amazon S3 website.
S3 Transfer Manager and the Quarkus extension supports only Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client, or AWS CRT-based S3 client.
S3 Transfer Manager share the same configuration as S3 asynchronous client. See above to configure an S3AsyncClient.
If you want to use S3 Transfer Manager, configure an S3AsyncClient`with the desired HTTP client library and simply inject an instance of `S3TransferManager:
// Netty or AWS CRT-based HTTP client
+@Inject
+S3TransferManager transferManager;
+
+// or AWS CRT-based S3 client
+@Inject
+@S3Crt
+S3TransferManager transferManager;And add the following dependency to the application pom.xml:
<dependency>
+ <groupId>io.quarkiverse.amazonservices</groupId>
+ <artifactId>quarkus-amazon-s3-transfer-manager</artifactId>
+</dependency>You can then make call
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Configure the starting buffer size the client will use to buffer the parts downloaded from S3. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the maximum number of S3 connections that should be established during a transfer. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the minimum part size for transfer parts. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The target throughput for transfer requests. +
+
+Environment variable: |
+double |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Secrets Manager enables you to replace hardcoded credentials in your code, including passwords, with an API call to Secrets Manager to retrieve the secret programmatically. +This helps ensure the secret can’t be compromised by someone examining your code, because the secret no longer exists in the code.
+You can find more information about Secrets Manager at the AWS Secrets Manager website.
+| + + | ++The Secrets Manager extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use Secrets Manager locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the Secrets Manager service
+Docker for your system to run Secrets Manager locally for testing purposes
+The easiest way to start working with Secrets Manager is to run a local instance using Dev Services.
+You can also set up a local version of Secrets Manager manually, first start a LocalStack container:
+docker run --rm --name local-secrets-manager --publish 4566:4584 -e SERVICES=secretsmanager -e START_WEB=0 -d localstack/localstack:3.0.1This starts a Secrets Manager instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve credentials using Secrets Manager.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-secretsmanager-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-secretsmanager-quickstart \
+ -DclassName="org.acme.secretsmanager.QuarkusSecretsManagerSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy,resteasy-jackson,amazon-secretsmanager,resteasy-mutiny"
+cd amazon-secretsmanager-quickstartThis command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and Amazon Secrets Manager Client extensions.
+After this, the amazon-secretsmanager extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from Secrets Manager store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.secretsmanager.QuarkusSecretsManagerResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.secretsmanager;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.secretsmanager.model.CreateSecretRequest;
+import software.amazon.awssdk.services.secretsmanager.model.GetSecretValueRequest;
+
+public abstract class QuarkusSecretsManagerResource {
+ public static final String VERSION_STAGE = "AWSCURRENT";
+
+ @ConfigProperty(name = "secret.name") (1)
+ String secretName;
+
+ protected GetSecretValueRequest generateGetSecretValueRequest() {
+ return GetSecretValueRequest.builder() (2)
+ .secretId(secretName)
+ .versionStage(VERSION_STAGE)
+ .build();
+ }
+
+ protected CreateSecretRequest generateCreateSecretRequest(String name, String secret) {
+ return CreateSecretRequest.builder() (3)
+ .name(name)
+ .secretString(secret)
+ .build();
+ }
+
+}| 1 | +Inject a configured name under which is stored the secret | +
| 2 | +Generate a request for the credentials with the configured name | +
| 3 | +Generate a request to create a specific secret | +
Now, we can extend the class and create the synchronous implementation in the org.acme.secretsmanager.QuarkusSecretsManagerSyncResource class.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerClient;
+
+@Path("/sync")
+public class QuarkusSecretsManagerSyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject (1)
+ SecretsManagerClient secretsManagerClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public String getSecret() {
+ return secretsManagerClient.getSecretValue(generateGetSecretValueRequest()).secretString();
+ }
+
+ @POST
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void createSecret(String name, String value) {
+ secretsManagerClient.createSecret(generateCreateSecretRequest(name, secret));
+ }
+
+}| 1 | +Inject the client provided by the amazon-secretsmanager extension | +
Using the Amazon Secrets Manager SDK, we can easily store and retrieve secrets.
+Both Secrets Manager clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.secretsmanager.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local Secrets Manager instance, configure it as follows:
+quarkus.secretsmanager.endpoint-override=http://localhost:4566 (1)
+
+quarkus.secretsmanager.aws.region=us-east-1 (2)
+quarkus.secretsmanager.aws.credentials.type=static (3)
+quarkus.secretsmanager.aws.credentials.static-provider.access-key-id=test-key
+quarkus.secretsmanager.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the Secret Manager client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon Secrets Manager related properties. By default, the Secrets Manager client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.secretsmanager.QuarkusSecretsManagerAsyncResource REST resource that will be similar to our QuarkusSecretsManagerSyncResource but using an asynchronous programming model.
package org.acme.secretsmanager;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import software.amazon.awssdk.services.secretsmanager.SecretsManagerAsyncClient;
+
+@Path("/async")
+public class QuarkusSecretsManagerAsyncResource extends QuarkusSecretsManagerResource {
+
+ @Inject
+ SecretsManagerAsyncClient secretsManagerAsyncClient;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<String> getSecret() {
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.getSecretValue(generateGetSecretValueRequest()))
+ .onItem().transform(r -> r.secretString());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> createSecret(String name, String value) {
+
+ return Uni.createFrom().completionStage(secretsManagerAsyncClient.createSecret(generateCreateSecretRequest(name, secret)))
+ .onItem().transform(r -> null);
+ }
+
+}Note that the SecretsManagerAsyncClient behaves just like the SecretsManagerClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.secretsmanager.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Email Service (SES) is a flexible and highly-scalable email sending and receiving service. +Using SES, you can send emails with any type of correspondence. You can find more information about SES at the Amazon SES website.
+| + + | ++The SES extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SES locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SES service
+Docker for your system to run SES locally for testing purposes
+The easiest way to start working with SES is to run a local instance using Dev Services. +However, local instance of SES is only mocks the SES APIs without the actual email sending capabilities. You can still use it for this guide to verify an API communication or integration test purposes.
+You can also set up a local version of SES manually, first start a LocalStack container:
+docker run --rm --name local-ses -p 4566:4579 -e SERVICES=ses -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SES instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textAmazon applies certain restrictions to new Amazon SES accounts, mainly to prevent fraud and abuse. All new accounts are in the Amazon SES sandbox. +All the features of the Amazon SES are still available while in sandbox, but a following restrictions applies: +- You can send mail to verified email addresses and domains or to the Amazon SES mailbox simulator +- You can only send mail from verified email addresses and domains +- You can send a maximum of 1 message per second.
+Going production, you’d need to get your account of the sandbox following the Amazon procedure.
+We assume you are going to use AWS SES sandbox for the sake of this guide. But before sending any email, you must verify sender and recipient email addresses using AWS CLI. +You can use your personal email or any temporary email service available if you wish.
+aws ses verify-email-identity --email-address <sender@email.address>
+aws ses verify-email-identity --email-address <recipient@email.address>Now, you need to open a mailboxes of those email addresses in order to follow confirmation procedure. Once email is approved you can use it in your application.
+If you are using local SES you still need to verify email addresses, otherwise your send email in order to let local SES accepting your request. +However, no emails to be send as it only mocks the service APIs.
+aws ses verify-email-identity --email-address <sender@email.address> --profile localstack --endpoint-url=http://localhost:4566
+aws ses verify-email-identity --email-address <recipient@email.address> --profile localstack --endpoint-url=http://localhost:4566The application built here allows sending text emails to the recipients that are verified on AWS SES.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ses-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ses-quickstart \
+ -DclassName="org.acme.ses.QuarkusSesSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ses"
+cd amazon-ses-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SES Client extensions.
+After this, the amazon-ses extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Lets create a org.acme.ses.QuarkusSesSyncResource that will provide an API to send emails using the synchronous client.
package org.acme.ses;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesClient;
+
+@Path("/sync")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesSyncResource {
+
+ @Inject
+ SesClient ses;
+
+ @POST
+ @Path("/email")
+ public String encrypt(Email data) {
+ return ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))).messageId();
+ }
+}Both SES clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ses.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SES instance, configure it as follows:
+quarkus.ses.endpoint-override=http://localhost:4566
+
+quarkus.ses.aws.region=us-east-1
+quarkus.ses.aws.credentials.type=static
+quarkus.ses.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ses.aws.credentials.static-provider.secret-access-key=test-secretquarkus.ses.aws.region - It’s required by the client, but since you’re using a local SES instance use us-east-1 as it’s a default region of LocalStack’s SES.
quarkus.ses.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.ses.endpoint-override - Override the SES client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all Amazon SES related properties. By default, the SES client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ses.QuarkusSesAsyncResource REST resource that will be similar to our QuarkusSesSyncResource but using an asynchronous programming model.
package org.acme.ses;
+
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.ses.model.Email;
+import software.amazon.awssdk.services.ses.SesAsyncClient;
+import software.amazon.awssdk.services.ses.model.SendEmailResponse;
+
+@Path("/async")
+@Produces(MediaType.TEXT_PLAIN)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarkusSesAsyncResource {
+
+ @Inject
+ SesAsyncClient ses;
+
+ @POST
+ @Path("/email")
+ public Uni<String> encrypt(Email data) {
+ return Uni.createFrom()
+ .completionStage(
+ ses.sendEmail(req -> req
+ .source(data.getFrom())
+ .destination(d -> d.toAddresses(data.getTo()))
+ .message(msg -> msg
+ .subject(sub -> sub.data(data.getSubject()))
+ .body(b -> b.text(txt -> txt.data(data.getBody()))))))
+ .onItem().apply(SendEmailResponse::messageId);
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SES client, and then transform the emitted item.
And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ses.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon AWS Step Functions (SFN) is a cloud service that enables you to coordinate and automate the execution of multiple AWS services in a serverless workflow. +It allows you to design, visualize, and execute workflows using a state machine architecture. +With SFN, you can seamlessly integrate various AWS services, including Lambda functions, Amazon S3, Amazon DynamoDB, and others, into a cohesive and scalable workflow.
+You can find more information about SFN at the Amazon SFN website.
+| + + | ++The SFN extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SFN locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SFN service
+Optionally, Docker for your system to run SFN locally for testing purposes
+The easiest way to start working with SFN is to run a local instance using Dev Services.
+You can also set up a local version of SFN manually, first start a LocalStack container:
+docker run -it --publish 4566:4566 -e SERVICES=stepfunctions -e START_WEB=0 localstack/localstack:3.0.1This starts a SFN instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SFN state machine using AWS CLI and store the state machine ARN in a STATE_MACHINE_ARN variable:
STATE_MACHINE_ARN=$(aws stepfunctions create-state-machine --definition "{\
+ \"Comment\": \"A Hello World example of the Amazon States Language using a Pass state\",\
+ \"StartAt\": \"HelloWorld\",\
+ \"States\": {\
+ \"HelloWorld\": {\
+ \"Type\": \"Pass\",\
+ \"End\": true\
+ }\
+ }}" --name "HelloWorld" --role-arn "arn:aws:iam::012345678901:role/DummyRole" --endpoint-url http://localhost:4566 --profile localstack --query stateMachineArn --output text)Start an execution using the ARN of the state machine you created and store the execution ARN in a EXECUTION_ARN variable:
EXECUTION_ARN=$(aws stepfunctions start-execution --state-machine-arn "$STATE_MACHINE_ARN" --endpoint-url http://localhost:4566 --profile localstack --query executionArn --output text)Finally, get the information about the state machine execution:
+aws stepfunctions describe-execution --execution-arn "$EXECUTION_ARN" --endpoint-url http://localhost:4566 --profile localstackFirst, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sfn-quickstart \
+ -DclassName="org.acme.sfn.QuarkusSfnSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sfn"
+cd amazon-sfn-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SFN Client extensions.
+After this, the amazon-sfn extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both SFN clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default, the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sfn.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sfn.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SFN instance, configure it as follows:
+quarkus.sfn.endpoint-override=http://localhost:4566
+
+quarkus.sfn.aws.region=us-east-1
+quarkus.sfn.aws.credentials.type=static
+quarkus.sfn.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sfn.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sfn.aws.region - It’s required by the client, but since you’re using a local SFN instance you can pick any valid AWS region.
quarkus.sfn.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sfn.endpoint-override - Override the SFN client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sfn.aws.region=<YOUR_REGION>
+quarkus.sfn.aws.credentials.type=defaultquarkus.sfn.aws.region you should set it to the region where you provisioned the SFN state machine,
quarkus.sfn.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sfn.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Notification Service (SNS) is a highly available and fully managed pub/sub messaging service. +It provides topics for high-throughput, push-based, many-to-many messaging. Messages can fan out to a large number of subscriber endpoints for +parallel processing, including Amazon SQS queues, AWS Lambda functions, and HTTP/S webhooks. Additionally, SNS can be used +to fan out notifications to end users using mobile push, SMS and email.
+You can find more information about SNS at the Amazon SNS website.
+| + + | ++The SNS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SNS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SNS service
+Optionally, Docker for your system to run SNS locally for testing purposes
+The easiest way to start working with SNS is to run a local instance using Dev Services.
+You can also set up a local version of SNS manually, first start a LocalStack container:
+docker run -it --publish 4566:4575 -e SERVICES=sns -e START_WEB=0 localstack/localstack:3.0.1This starts a SNS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SNS topic using AWS CLI and store in TOPIC_ARN environment variable
TOPIC_ARN=`aws sns create-topic --name=QuarksCollider --profile localstack --endpoint-url=http://localhost:4566`| + + | +
+
+
+If you are using LocalStack, some additional configuration is needed: +
+
+
+
+Otherwise your service will not receive the notifications. + |
+
If you want to run the demo using SNS on your AWS account, you can create a topic using AWS default profile
+TOPIC_ARN=`aws sns create-topic --name=QuarksCollider`The application built here allows to shoot elementary particles (quarks) into a QuarksCollider topic of the AWS SNS.
+Additionally, we create a resource that allows to subscribe to the QuarksCollider topic in order to receive published quarks.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sns-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sns-quickstart \
+ -DclassName="org.acme.sns.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sns"
+cd amazon-sns-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SNS Client extensions.
+After this, the amazon-sns extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows to publish quarks. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sns.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sns.QuarksCannonSyncResource that will provide an API to shoot quarks into the SNS topic via the SNS synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ PublishResponse response = sns.publish(p -> p.topicArn(topicArn).message(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact that messages published must be simply a String we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
The missing piece is the subscriber that will receive the messages published to our topic. Before implementing subscribers, we need to define POJO classes representing messages posted by the AWS SNS.
+Let’s create two classes that represent SNS Notification and SNS Subscription Confirmation messages based on the AWS SNS Message and JSON formats
+Create org.acme.sns.model.SnsNotification class
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class SnsNotification {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signinCertUrl;
+
+ @JsonProperty("Subject")
+ private String subject;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ @JsonProperty("UnsubscribeURL")
+ private String unsubscribeURL;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigninCertUrl() {
+ return signinCertUrl;
+ }
+
+ public void setSigninCertUrl(String signinCertUrl) {
+ this.signinCertUrl = signinCertUrl;
+ }
+
+ public String getSubject() {
+ return subject;
+ }
+
+ public void setSubject(String subject) {
+ this.subject = subject;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+
+ public String getUnsubscribeURL() {
+ return unsubscribeURL;
+ }
+
+ public void setUnsubscribeURL(String unsubscribeURL) {
+ this.unsubscribeURL = unsubscribeURL;
+ }
+}Then, create org.acme.sns.SnsSubscriptionConfirmation
package org.acme.sns.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class SnsSubscriptionConfirmation {
+
+ @JsonProperty("Message")
+ private String message;
+
+ @JsonProperty("MessageId")
+ private String messageId;
+
+ @JsonProperty("Signature")
+ private String signature;
+
+ @JsonProperty("SignatureVersion")
+ private String signatureVersion;
+
+ @JsonProperty("SigningCertURL")
+ private String signingCertUrl;
+
+ @JsonProperty("SubscribeURL")
+ private String subscribeUrl;
+
+ @JsonProperty("Timestamp")
+ private String timestamp;
+
+ @JsonProperty("Token")
+ private String token;
+
+ @JsonProperty("TopicArn")
+ private String topicArn;
+
+ @JsonProperty("Type")
+ private String type;
+
+ public String getMessage() {
+ return message;
+ }
+
+ public void setMessage(String message) {
+ this.message = message;
+ }
+
+ public String getMessageId() {
+ return messageId;
+ }
+
+ public void setMessageId(String messageId) {
+ this.messageId = messageId;
+ }
+
+ public String getSignature() {
+ return signature;
+ }
+
+ public void setSignature(String signature) {
+ this.signature = signature;
+ }
+
+ public String getSignatureVersion() {
+ return signatureVersion;
+ }
+
+ public void setSignatureVersion(String signatureVersion) {
+ this.signatureVersion = signatureVersion;
+ }
+
+ public String getSigningCertUrl() {
+ return signingCertUrl;
+ }
+
+ public void setSigningCertUrl(String signingCertUrl) {
+ this.signingCertUrl = signingCertUrl;
+ }
+
+ public String getSubscribeUrl() {
+ return subscribeUrl;
+ }
+
+ public void setSubscribeUrl(String subscribeUrl) {
+ this.subscribeUrl = subscribeUrl;
+ }
+
+ public String getTimestamp() {
+ return timestamp;
+ }
+
+ public void setTimestamp(String timestamp) {
+ this.timestamp = timestamp;
+ }
+
+ public String getToken() {
+ return token;
+ }
+
+ public void setToken(String token) {
+ this.token = token;
+ }
+
+ public String getTopicArn() {
+ return topicArn;
+ }
+
+ public void setTopicArn(String topicArn) {
+ this.topicArn = topicArn;
+ }
+
+ public String getType() {
+ return type;
+ }
+
+ public void setType(String type) {
+ this.type = type;
+ }
+}Now, create org.acme.QuarksShieldSyncResource REST resources that:
+- Allows to subscribe itself to our SNS topic
+- Unsubscribe from the SNS topic
+- Receive notifications from the subscribed SNS topic
| + + | ++Keep in mind that AWS SNS supports multiple types of subscribers (that is web servers, email addresses, AWS SQS queues, AWS Lambda functions, and many more), but for the sake of the +quickstart we will show how to subscribe an HTTP endpoint served by our application. + | +
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Response notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) throws JsonProcessingException {
+ if (messageType == null) {
+ return Response.status(400).build();
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ SnsNotification notification = readObject(SnsNotification.class, message);
+ Quark quark = readObject(Quark.class, notification.getMessage());
+ LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ SnsSubscriptionConfirmation subConf = readObject(SnsSubscriptionConfirmation.class, message);
+ sns.confirmSubscription(cs -> cs.topicArn(topicArn).token(subConf.getToken()));
+ LOGGER.info("Subscription confirmed. Ready for quarks collisions.");
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ } else {
+ return Response.status(400).entity("Unknown messageType").build();
+ }
+
+ return Response.ok().build();
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Response subscribe() {
+ String notificationEndpoint = notificationEndpoint();
+ SubscribeResponse response = sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint));
+ subscriptionArn = response.subscriptionArn();
+ LOGGER.infov("Subscribed Quarks shield <{0}> : {1} ", notificationEndpoint, response.subscriptionArn());
+ return Response.ok().entity(response.subscriptionArn()).build();
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Response unsubscribe() {
+ if (subscriptionArn != null) {
+ sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn));
+ LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn);
+ return Response.ok().build();
+ } else {
+ LOGGER.info("Not subscribed yet");
+ return Response.status(400).entity("Not subscribed yet").build();
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/sync/shield";
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}subscribe() endpoint subscribes to our topic by providing the URL to the POST endpoint receiving SNS notification requests.
unsubscribe() simply removes our subscription, so any messages published to the topic will not be routed to our endpoint anymore
notificationEndpoint() is called by SNS on new message if endpoint is subscribed.
+See Amazon SNS message and JSON formats for details about the format of the messages SNS can submit.
Both SNS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sns.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SNS instance, configure it as follows:
+quarkus.sns.endpoint-override=http://localhost:4566
+
+quarkus.sns.aws.region=us-east-1
+quarkus.sns.aws.credentials.type=static
+quarkus.sns.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sns.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sns.aws.region - It’s required by the client, but since you’re using a local SNS instance you can pick any valid AWS region.
quarkus.sns.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sns.endpoint-override - Override the SNS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you’d need to set it with:
+quarkus.sns.aws.region=<YOUR_REGION>
+quarkus.sns.aws.credentials.type=defaultquarkus.sns.aws.region you should set it to the region where you provisioned the SNS table,
quarkus.sns.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dtopic.arn=$TOPIC_ARN -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sns.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sns;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.PublishResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> publish(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sns.publish(p -> p.topicArn(topicArn).message(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(PublishResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SNS client, and then transform the emitted item.
And corresponding async subscriber org.acme.sns.QuarksShieldAsyncResource
package org.acme.sns;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.HashMap;
+import java.util.Map;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sns.model.Quark;
+import org.acme.sns.model.SnsNotification;
+import org.acme.sns.model.SnsSubscriptionConfirmation;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sns.SnsAsyncClient;
+import software.amazon.awssdk.services.sns.model.SubscribeResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ private static final String NOTIFICATION_TYPE = "Notification";
+ private static final String SUBSCRIPTION_CONFIRMATION_TYPE = "SubscriptionConfirmation";
+ private static final String UNSUBSCRIPTION_CONFIRMATION_TYPE = "UnsubscribeConfirmation";
+
+ @Inject
+ SnsAsyncClient sns;
+
+ @ConfigProperty(name = "topic.arn")
+ String topicArn;
+
+ @ConfigProperty(name = "quarks.shield.base.url")
+ String quarksShieldBaseUrl;
+
+ private volatile String subscriptionArn;
+
+ static Map<Class<?>, ObjectReader> READERS = new HashMap<>();
+
+ static {
+ READERS.put(SnsNotification.class, new ObjectMapper().readerFor(SnsNotification.class));
+ READERS.put(SnsSubscriptionConfirmation.class, new ObjectMapper().readerFor(SnsSubscriptionConfirmation.class));
+ READERS.put(Quark.class, new ObjectMapper().readerFor(Quark.class));
+ }
+
+ @POST
+ @Consumes({MediaType.TEXT_PLAIN})
+ public Uni<Response> notificationEndpoint(@HeaderParam("x-amz-sns-message-type") String messageType, String message) {
+ if (messageType == null) {
+ return Uni.createFrom().item(Response.status(400).build());
+ }
+
+ if (messageType.equals(NOTIFICATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsNotification.class, message))
+ .onItem().transform(notification -> readObject(Quark.class, notification.getMessage()))
+ .onItem().invoke(quark -> LOGGER.infov("Quark[{0}, {1}] collision with the shield.", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(quark -> Response.ok().build());
+ } else if (messageType.equals(SUBSCRIPTION_CONFIRMATION_TYPE)) {
+ return Uni.createFrom().item(readObject(SnsSubscriptionConfirmation.class, message))
+ .onItem().transformToUni(msg ->
+ Uni.createFrom().completionStage(
+ sns.confirmSubscription(confirm -> confirm.topicArn(topicArn).token(msg.getToken())))
+ )
+ .onItem().invoke(resp -> LOGGER.info("Subscription confirmed. Ready for quarks collisions."))
+ .onItem().transform(resp -> Response.ok().build());
+ } else if (messageType.equals(UNSUBSCRIPTION_CONFIRMATION_TYPE)) {
+ LOGGER.info("We are unsubscribed");
+ return Uni.createFrom().item(Response.ok().build());
+ }
+
+ return Uni.createFrom().item(Response.status(400).entity("Unknown messageType").build());
+ }
+
+ @POST
+ @Path("/subscribe")
+ public Uni<Response> subscribe() {
+ return Uni.createFrom()
+ .completionStage(sns.subscribe(s -> s.topicArn(topicArn).protocol("http").endpoint(notificationEndpoint())))
+ .onItem().transform(SubscribeResponse::subscriptionArn)
+ .onItem().invoke(this::setSubscriptionArn)
+ .onItem().invoke(arn -> LOGGER.infov("Subscribed Quarks shield with id = {0} ", arn))
+ .onItem().transform(arn -> Response.ok().entity(arn).build());
+ }
+
+ @POST
+ @Path("/unsubscribe")
+ public Uni<Response> unsubscribe() {
+ if (subscriptionArn != null) {
+ return Uni.createFrom()
+ .completionStage(sns.unsubscribe(s -> s.subscriptionArn(subscriptionArn)))
+ .onItem().invoke(arn -> LOGGER.infov("Unsubscribed quarks shield for id = {0}", subscriptionArn))
+ .onItem().invoke(arn -> subscriptionArn = null)
+ .onItem().transform(arn -> Response.ok().build());
+ } else {
+ return Uni.createFrom().item(Response.status(400).entity("Not subscribed yet").build());
+ }
+ }
+
+ private String notificationEndpoint() {
+ return quarksShieldBaseUrl + "/async/shield";
+ }
+
+ private void setSubscriptionArn(String arn) {
+ this.subscriptionArn = arn;
+ }
+
+ private <T> T readObject(Class<T> clazz, String message) {
+ T object = null;
+ try {
+ object = READERS.get(clazz).readValue(message);
+ } catch (JsonProcessingException e) {
+ LOGGER.errorv("Unable to deserialize message <{0}> to Class <{1}>", message, clazz.getSimpleName());
+ throw new RuntimeException(e);
+ }
+ return object;
+ }
+}And we need to add Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sns.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Amazon Simple Queue Service (SQS) is a fully managed message queuing service. +Using SQS, you can send, store, and receive messages between software components at any volume, without losing messages or requiring other +services to be available. +SQS offers two types of message queues. Standard queues offer maximum throughput, best-effort ordering and at-least-once delivery. +SQS FIFO queues are designed to guarantee that messages are processes exactly once, on the exact order that they were sent.
+You can find more information about SQS at the Amazon SQS website.
+| + + | ++The SQS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SQS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SQS service
+Docker for your system to run SQS locally for testing purposes
+The easiest way to start working with SQS is to run a local instance using Dev Services.
+You can optionally configure the queues that are created on startup with the quarkus.sqs.devservices.queues config property.
You can also set up a local version of SQS manually, first start a LocalStack container:
+docker run --rm --name local-sqs -p 4566:4566 -e SERVICES=sqs -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SQS instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]: textCreate a SQS queue using AWS CLI and store in QUEUE_URL environment variable.
QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue --profile localstack --endpoint-url=http://localhost:4566`Or, if you want to use your SQS queue on your AWS account create a queue using your default profile
+QUEUE_URL=`aws sqs create-queue --queue-name=ColliderQueue`The application built here allows shooting an elementary particles (quarks) into a ColliderQueue queue of the AWS SQS.
+Additionally, we create a resource that allows receiving those quarks from the ColliderQueue queue in the order they were sent.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-sqs-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sqs-quickstart \
+ -DclassName="org.acme.sqs.QuarksCannonSyncResource" \
+ -Dpath="/sync-cannon" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sqs"
+cd amazon-sqs-quickstartThis command generates a Maven structure importing the RESTEasy Reactive and Amazon SQS Client extensions.
+After this, the amazon-sqs extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that sends quarks via the queue. The example application will demonstrate the two programming models supported by the extension.
+First, let’s create the Quark bean as follows:
package org.acme.sqs.model;
+
+import io.quarkus.runtime.annotations.RegisterForReflection;
+import java.util.Objects;
+
+@RegisterForReflection
+public class Quark {
+
+ private String flavor;
+ private String spin;
+
+ public Quark() {
+ }
+
+ public String getFlavor() {
+ return flavor;
+ }
+
+ public void setFlavor(String flavor) {
+ this.flavor = flavor;
+ }
+
+ public String getSpin() {
+ return spin;
+ }
+
+ public void setSpin(String spin) {
+ this.spin = spin;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Quark)) {
+ return false;
+ }
+
+ Quark other = (Quark) obj;
+
+ return Objects.equals(other.flavor, this.flavor);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.flavor);
+ }
+}Then, create a org.acme.sqs.QuarksCannonSyncResource that will provide an API to shoot quarks into the SQS queue using the synchronous client.
| + + | +
+The @RegisterForReflection annotation instructs Quarkus to keep the class and its members during the native compilation. More details about the @RegisterForReflection annotation can be found on the native application tips page.
+ |
+
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/sync/cannon")
+@Produces(MediaType.TEXT_PLAIN)
+public class QuarksCannonSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ SendMessageResponse response = sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message));
+ LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin());
+ return Response.ok().entity(response.messageId()).build();
+ }
+}Because of the fact messages sent to the queue must be a String, we’re using Jackson’s ObjectWriter in order to serialize our Quark objects into a String.
Now, create the org.acme.QuarksShieldSyncResource REST resources that provides an endpoint to read the messages from the ColliderQueue queue.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+
+@Path("/sync/shield")
+public class QuarksShieldSyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldSyncResource.class);
+
+ @Inject
+ SqsClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public List<Quark> receive() {
+ List<Message> messages = sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)).messages();
+
+ return messages.stream()
+ .map(Message::body)
+ .map(this::toQuark)
+ .collect(Collectors.toList());
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}We are using here a Jackson’s ObjectReader in order to deserialize queue messages into our Quark POJOs.
Both SQS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sqs.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SQS instance, configure it as follows:
+quarkus.sqs.endpoint-override=http://localhost:4566
+
+quarkus.sqs.aws.region=us-east-1
+quarkus.sqs.aws.credentials.type=static
+quarkus.sqs.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sqs.aws.credentials.static-provider.secret-access-key=test-secretquarkus.sqs.aws.region - It’s required by the client, but since you’re using a local SQS instance use us-east-1 as it’s a default region of LocalStack’s SQS.
quarkus.sqs.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key
quarkus.sqs.endpoint-override - Override the SQS client to use a local instance instead of an AWS service
If you want to work with an AWS account, you can simply remove or comment out all SQS related properties. By default, the SQS client extension
+will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -Dqueue.url=$QUEUE_URL -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.sqs.QuarksCannonAsyncResource REST resource that will be similar to our QuarksCannonSyncResource but using an asynchronous programming model.
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectWriter;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.SendMessageResponse;
+
+@Path("/async/cannon")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+public class QuarksCannonAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksCannonAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectWriter QUARK_WRITER = new ObjectMapper().writerFor(Quark.class);
+
+ @POST
+ @Path("/shoot")
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Uni<Response> sendMessage(Quark quark) throws Exception {
+ String message = QUARK_WRITER.writeValueAsString(quark);
+ return Uni.createFrom()
+ .completionStage(sqs.sendMessage(m -> m.queueUrl(queueUrl).messageBody(message)))
+ .onItem().invoke(item -> LOGGER.infov("Fired Quark[{0}, {1}}]", quark.getFlavor(), quark.getSpin()))
+ .onItem().transform(SendMessageResponse::messageId)
+ .onItem().transform(id -> Response.ok().entity(id).build());
+ }
+}We create Uni instances from the CompletionStage objects returned by the asynchronous SQS client, and then transform the emitted item.
And the corresponding async receiver of the queue messages org.acme.sqs.QuarksShieldAsyncResource
package org.acme.sqs;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.ObjectReader;
+import io.smallrye.mutiny.Uni;
+import java.util.List;
+import java.util.stream.Collectors;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.acme.sqs.model.Quark;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+import software.amazon.awssdk.services.sqs.SqsAsyncClient;
+import software.amazon.awssdk.services.sqs.model.Message;
+import software.amazon.awssdk.services.sqs.model.ReceiveMessageResponse;
+
+@Path("/async/shield")
+public class QuarksShieldAsyncResource {
+
+ private static final Logger LOGGER = Logger.getLogger(QuarksShieldAsyncResource.class);
+
+ @Inject
+ SqsAsyncClient sqs;
+
+ @ConfigProperty(name = "queue.url")
+ String queueUrl;
+
+ static ObjectReader QUARK_READER = new ObjectMapper().readerFor(Quark.class);
+
+ @GET
+ public Uni<List<Quark>> receive() {
+ return Uni.createFrom()
+ .completionStage(sqs.receiveMessage(m -> m.maxNumberOfMessages(10).queueUrl(queueUrl)))
+ .onItem().transform(ReceiveMessageResponse::messages)
+ .onItem().transform(m -> m.stream().map(Message::body).map(this::toQuark).collect(Collectors.toList()));
+ }
+
+ private Quark toQuark(String message) {
+ Quark quark = null;
+ try {
+ quark = QUARK_READER.readValue(message);
+ } catch (Exception e) {
+ LOGGER.error("Error decoding message", e);
+ throw new RuntimeException(e);
+ }
+ return quark;
+ }
+}And we need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sqs.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Systems Manager (formerly Amazon Simple Systems Manager, or SSM) is a service that you can use to view and control your infrastructure on AWS. +One of the most useful features of SSM for microservices is the Parameter Store, which provides secure, hierarchical storage for configuration data management and secrets management..
+You can find more information about SSM at the AWS Systems Manager website.
+| + + | ++The SSM extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client (by default) or the AWS CRT-based HTTP client
In this guide, we see how you can get your REST services to use SSM locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the SSM service
+Docker for your system to run SSM locally for testing purposes
+The easiest way to start working with SSM is to run a local instance using Dev Services.
+You can also set up a local version of SSM manually, first start a LocalStack container:
+docker run --rm --name local-ssm --publish 4566:4583 -e SERVICES=ssm -e START_WEB=0 -d localstack/localstack:3.0.1This starts a SSM instance that is accessible on port 4566.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:The application built here allows to store and retrieve parameters using the SSM parameter store.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the amazon-ssm-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-ssm-quickstart \
+ -DclassName="org.acme.ssm.QuarkusSsmSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-ssm"
+cd amazon-ssm-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon SSM Client extensions.
+After this, the amazon-ssm extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
In this example, we will create an application that allows us to store and retrieve parameters to and from SSM parameter store using a RESTful API. +The example application will demonstrate the two programming models supported by the extension.
+Let’s start with an abstract org.acme.ssm.QuarkusSsmResource class to provide the common functionality we will need for both the synchronous and asynchrounous exposures.
package org.acme.ssm;
+
+import static java.lang.Boolean.TRUE;
+import static java.util.stream.Collectors.toMap;
+
+import java.util.Map;
+import java.util.stream.Collector;
+
+import jakarta.annotation.PostConstruct;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import software.amazon.awssdk.services.ssm.model.GetParameterRequest;
+import software.amazon.awssdk.services.ssm.model.GetParametersByPathRequest;
+import software.amazon.awssdk.services.ssm.model.Parameter;
+import software.amazon.awssdk.services.ssm.model.ParameterType;
+import software.amazon.awssdk.services.ssm.model.PutParameterRequest;
+
+public abstract class QuarkusSsmResource {
+
+ @ConfigProperty(name = "parameters.path") (1)
+ String parametersPath;
+
+ @PostConstruct (2)
+ void normalizePath() {
+ if (!parametersPath.startsWith("/")) {
+ parametersPath = "/" + parametersPath;
+ }
+ if (!parametersPath.endsWith("/")) {
+ parametersPath = parametersPath + "/";
+ }
+ }
+
+ protected Collector<Parameter, ?, Map<String, String>> parametersToMap() { (3)
+ return toMap(p -> p.name().substring(parametersPath.length()), Parameter::value);
+ }
+
+ protected GetParametersByPathRequest generateGetParametersByPathRequest() {
+ return GetParametersByPathRequest.builder() (4)
+ .path(parametersPath)
+ .withDecryption(TRUE)
+ .build();
+ }
+
+ protected PutParameterRequest generatePutParameterRequest(String name, String value, boolean secure) {
+ return PutParameterRequest.builder() (5)
+ .name(parametersPath + name)
+ .value(value)
+ .type(secure ? ParameterType.SECURE_STRING : ParameterType.STRING)
+ .overwrite(TRUE)
+ .build();
+ }
+
+ protected GetParameterRequest generateGetParameterRequest(String name) {
+ return GetParameterRequest.builder() (6)
+ .name(parametersPath + name)
+ .withDecryption(TRUE)
+ .build();
+ }
+}| 1 | +Inject a configured path under which to store parameters | +
| 2 | +Ensure the path starts and ends with / |
+
| 3 | +Collect parameters into a map of simple names and values | +
| 4 | +Generate a request for all parameters under the configured path | +
| 5 | +Generate a request to set a specific parameter | +
| 6 | +Generate a request to get a specific parameter value | +
Now, we can extend the class and create the synchronous implementation in the org.acme.ssm.QuarkusSsmSyncResource class.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.resteasy.reactive.RestQuery;
+
+import software.amazon.awssdk.services.ssm.SsmClient;
+
+@Path("/sync")
+public class QuarkusSsmSyncResource extends QuarkusSsmResource {
+
+ @Inject (1)
+ SsmClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Map<String, String> getParameters() {
+ return ssm.getParametersByPath(generateGetParametersByPathRequest())
+ .parameters().stream().collect(parametersToMap());
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public void setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ ssm.putParameter(generatePutParameterRequest(name, value, secure));
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String getParameter(String name) {
+ return ssm.getParameter(generateGetParameterRequest(name))
+ .parameter().value();
+ }
+}| 1 | +Inject the client provided by the amazon-ssm extension | +
Using the Amazon SSM SDK, we can easily store and retrieve arbitrary name/value pairs, and we can optionally store the values in a secure manner.
+Both SSM clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ssm.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local SSM instance, configure it as follows:
+quarkus.ssm.endpoint-override=http://localhost:4566 (1)
+
+quarkus.ssm.aws.region=us-east-1 (2)
+quarkus.ssm.aws.credentials.type=static (3)
+quarkus.ssm.aws.credentials.static-provider.access-key-id=test-key
+quarkus.ssm.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the SSM client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon SSM related properties. By default, the SSM client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+Create a org.acme.ssm.QuarkusSsmAsyncResource REST resource that will be similar to our QuarkusSsmSyncResource but using an asynchronous programming model.
package org.acme.ssm;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.smallrye.mutiny.Uni;
+import org.jboss.resteasy.reactive.RestQuery;
+import software.amazon.awssdk.services.ssm.SsmAsyncClient;
+
+@Path("/async")
+public class QuarkusSsmAsyncResource extends QuarkusSsmResource {
+
+ @Inject
+ SsmAsyncClient ssm;
+
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public Uni<Map<String, String>> getParameters() {
+ return Uni.createFrom().completionStage(ssm.getParametersByPath(generateGetParametersByPathRequest()))
+ .onItem().transform(r -> r.parameters().stream().collect(parametersToMap()));
+ }
+
+ @PUT
+ @Path("/{name}")
+ @Consumes(MediaType.TEXT_PLAIN)
+ public Uni<Void> setParameter(String name,
+ @RestQuery("secure") @DefaultValue("false") boolean secure,
+ String value) {
+
+ return Uni.createFrom().completionStage(ssm.putParameter(generatePutParameterRequest(name, value, secure)))
+ .onItem().transform(r -> null);
+ }
+
+ @GET
+ @Path("/{name}")
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<String> getParameter(String name) {
+ return Uni.createFrom().completionStage(ssm.getParameter(generateGetParameterRequest(name)))
+ .onItem().transform(r -> r.parameter().value());
+ }
+}Note that the SsmAsyncClient behaves just like the SsmClient, but returns CompletionStage objects which we use to create Uni instances, and then transform the emitted item.
To enable the asynchronous client, we also need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.ssm.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege credentials for users.
+You can find more information about STS at AWS Security Token Service API Reference.
+| + + | ++The STS extension is based on AWS Java SDK 2.x. +It’s a major rewrite of the 1.x code base that offers two programming models (Blocking & Async). + | +
The Quarkus extension supports two programming models:
+Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client
+Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.
In this guide, we see how you can get your REST services to use STS locally and on AWS.
+To complete this guide, you need:
+JDK 17+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+An AWS Account to access the STS service
+Docker for your system to run STS locally for testing purposes
+The easiest way to start working with STS is to run a local instance using Dev Services.
+You can also set up a local version of STS manually, first start a LocalStack container:
+docker run --rm --name local-sts --publish 4592:4592 -e SERVICES=sts -e START_WEB=0 -d localstack/localstack:3.0.1This starts a STS instance that is accessible on port 4592.
Create an AWS profile for your local instance using AWS CLI:
+$ aws configure --profile localstack
+AWS Access Key ID [None]: test-key
+AWS Secret Access Key [None]: test-secret
+Default region name [None]: us-east-1
+Default output format [None]:First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=amazon-sts-quickstart \
+ -DclassName="org.acme.sts.QuarkusStsSyncResource" \
+ -Dpath="/sync" \
+ -Dextensions="resteasy-reactive-jackson,amazon-sts"
+cd amazon-sts-quickstartThis command generates a Maven structure importing the RESTEasy Reactive/JAX-RS and Amazon STS Client extensions.
+After this, the amazon-sts extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.
Both STS clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory.
+Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the URL connection HTTP client, so
+you need to add a URL connection client dependency to the pom.xml file:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>url-connection-client</artifactId>
+</dependency>If you want to use the Apache HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=apacheAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>apache-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sts.sync-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>If you’re going to use a local STS instance, configure it as follows:
+quarkus.sts.endpoint-override=http://localhost:4592 (1)
+
+quarkus.sts.aws.region=us-east-1 (2)
+quarkus.sts.aws.credentials.type=static (3)
+quarkus.sts.aws.credentials.static-provider.access-key-id=test-key
+quarkus.sts.aws.credentials.static-provider.secret-access-key=test-secret| 1 | +Override the STS client to use LocalStack instead of the actual AWS service | +
| 2 | +Localstack defaults to us-east-1 |
+
| 3 | +The static credentials provider lets you set the access-key-id and secret-access-key directly |
+
If you want to work with an AWS account, you can simply remove or comment out all Amazon STS related properties. By default, the ST client extension will use the default credentials provider chain that looks for credentials in this order:
Java System Properties - aws.accessKeyId and aws.secretAccessKey
Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,
Instance profile credentials delivered through the Amazon EC2 metadata service
+And the region from your AWS CLI profile will be used.
+Packaging your application is as simple as ./mvnw clean package.
+It can then be run with java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.
+We need to add the Netty HTTP client dependency to the pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>netty-nio-client</artifactId>
+</dependency>If you want to use the AWS CRT-based HTTP client instead, configure it as follows:
+quarkus.sts.async-client.type=aws-crtAnd add the following dependency to the application pom.xml:
<dependency>
+ <groupId>software.amazon.awssdk</groupId>
+ <artifactId>aws-crt-client</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Quarkus Amazon Services automatically starts a LocalStack container in dev mode and when running tests. So, you don’t have to start one manually. The extension client is configured automatically.
+Dev Services for Amazon Services is automatically enabled for each extensions added to pom.xml except in the following situations:
quarkus.devservices.enabled is set to false
devservices.enabled is set to false per extension (eg. quarkus.s3.devservices.enabled=false)
the endpoint-override is configured (eg. quarkus.s3.endpoint-override=http://localhost:4566)
Your environment does not support Docker. In test mode, it will cause the test to fail. Either disable Dev Services or configure the endpoint-override.
By default, Dev Services for Amazon Services will start one LocalStack container with only the needed services.
+If you need to share a particular service between applications, Dev Services for Amazon Services implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single container.
+Dev Services for Amazon Services starts the container with the quarkus-dev-service-localstack label and service name as the value, which is used to identify the container.
+If you need multiple (shared) container, you can configure the devservices.service-name attribute for a given extension (eg. quarkus.s3.devservices.service-name) and indicate the container name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is localstack.
By default, to ease sharing containers across multiple applications, each service will be started in its own container (the value of the quarkus-dev-service-localstack label is suffixed by the extension name). However, sometimes, some services need to communicate with each other inside the same container (e.g., subscribing an Amazon SQS queue to an Amazon SNS topic). In this case, you can disable this behavior by setting the devservices.isolated attribute for a given extension to false.
Sharing is disabled by default in dev mode, and is always disabled in test mode. You can enable the sharing with devservices.shared=true for a given extension (e.g. quarkus.s3.devservices.shared=true). All other non-shared services will be grouped in another container.
Dev Services for Amazon Services uses localstack/localstack image. You can configure the image and version using the quarkus.aws.devservices.localstack.image-name property:
quarkus.aws.devservices.localstack.image-name=localstack/localstack:3.0.1Dev Services for Amazon Services can support specific properties sent to the container. It can be globally applied to all containers or be specified per service as follows:
+quarkus.aws.devservices.localstack.container-properties.START_WEB=0
+quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1GRefer to the LocalStack documentation for more configuration : https://docs.localstack.cloud/localstack/configuration/#local-aws-services. Note that not all environment variables are supported and some may affect Dev Services for Amazon Services.
+To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:
quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
+quarkus.aws.devservices.localstack.additional-services."redshift".enabled=trueThe key is the name of the service to enable and must be a valid LocalStack service name.
+Some extensions support additional configuration to be applied at startup. Refer to the extension documentation.
+The Cognito extension is not using LocalStack but Moto.
+Dev Services for Amazon Services uses the latest motoserver/moto image. You can configure the image and version using the quarkus.aws.devservices.moto.image-name property:
quarkus.aws.devservices.moto.image-name=motoserver/moto:3.0.2Dev Services for Amazon Services can support specific properties sent to the container as follows:
+quarkus.aws.devservices.moto.container-properties.MOTO_COGNITO_IDP_USER_POOL_ID_STRATEGY=HASHConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Classpath to init scripts folder executed during localstack startup. initScriptsFolder has higher precedence. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port localstack will listen to. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of extensions to load with the enhanced client. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether a
+
+
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable DynamoDB service endpoint discovery. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The buckets to create on startup. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable using the accelerate endpoint when accessing S3. +
+
+Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront’s globally distributed edge locations. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable doing a validation of the checksum of an object stored in S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using chunked encoding when signing the request payload for
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable dualstack mode for accessing S3. If you want to use IPv6 when accessing S3, dualstack must be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable using path style access for accessing S3 objects instead of DNS style access. DNS style access is preferred as it will result in better load balancing when accessing S3. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable cross-region call to the region specified in the S3 resource ARN different than the region the client was configured with. If this flag is not set to 'true', the cross-region call will throw an exception. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Define the profile name that should be consulted to determine the default value of
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Configure the starting buffer size the client will use to buffer the parts downloaded from S3. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the maximum number of S3 connections that should be established during a transfer. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the minimum part size for transfer parts. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The target throughput for transfer requests. +
+
+Environment variable: |
+double |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The queues to create on startup. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+List of execution interceptors that will have access to read and modify the request and response objects as they are processed by the AWS SDK. +
+
+The list should consists of class names which implements
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+OpenTelemetry AWS SDK instrumentation will be enabled if the OpenTelemetry extension is present and this value is true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Type of the sync HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Type of the async HTTP client implementation +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The endpoint URI with which the SDK should communicate. +
+
+If not specified, an appropriate endpoint to be used for the given service and region. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The amount of time to allow the client to complete the execution of an API call. +
+
+This timeout covers the entire client execution except for marshalling. This includes request handler execution, all HTTP requests including retries, unmarshalling, etc. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The amount of time to wait for the HTTP request to complete before giving up and timing out. +
+
+This value should always be positive, if present. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Whether the Quarkus thread pool should be used for scheduling tasks such as async retry attempts and timeout task. +
+
+When disabled, the default sdk behavior is to create a dedicated thread pool for each client, resulting in competition for CPU resources among these thread pools. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+An Amazon Web Services region that hosts the given service. +
+
+It overrides region provider chain with static value of +region with which the service client should communicate. +
+
+If not set, region is retrieved via the default providers chain in the following order: +
+
+
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time to establish a connection before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for data to be transferred over an established, open connection before the connection is timed out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum number of connections allowed in the connection pool. +
+
+Each built HTTP client has its own private connection pool. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the client should send an HTTP expect-continue handshake before each request. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed asynchronously. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows domain name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+For NTLM proxies - the Windows workstation name to use when authenticating with the proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether to attempt to authenticate preemptively against the proxy server using basic authentication. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable HTTP proxy +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The username to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password to use when connecting through a proxy. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The maximum number of allowed concurrent requests. +
+
+For HTTP/1.1 this is the same as max connections. For HTTP/2 the number of connections that will be used depends on the max streams allowed per connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of pending acquires allowed. +
+
+Once this exceeds, acquire tries will be failed. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a write on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait when acquiring a connection from the pool before giving up and timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The maximum amount of time that a connection should be allowed to remain open while idle. +
+
+Currently has no effect if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the idle connections in the connection pool should be closed. +
+
+When enabled, connections left idling for longer than
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure whether to enable or disable TCP KeepAlive. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The HTTP protocol to use. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SSL Provider to be used in the Netty client. +
+
+Default is
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The maximum number of concurrent streams for an HTTP/2 connection. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The initial window size for an HTTP/2 stream. +
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the period that the Netty client will send
+
+This setting is only respected when the HTTP/2 protocol is used. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Enable HTTP proxy. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The endpoint of the proxy server that the SDK should connect through. +
+
+Currently, the endpoint is limited to a host and port. Any other URI components will result in an exception being raised. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The hosts that the client is allowed to access without going through the proxy. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+TLS key managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TLS trust managers provider type. +
+
+Available providers: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Path to the key store. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Key store type. +
+
+See the KeyStore section in the https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[Java Cryptography Architecture Standard Algorithm Name Documentation] for information about standard keystore types. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable the custom configuration of the Netty event loop group. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Number of threads to use for the event loop group. +
+
+If not set, the default Netty thread count is used (which is double the number of available processors unless the
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The thread name prefix for threads created by this thread factory used by event loop group. +
+
+The prefix will be appended with a number unique to the thread factory and a number unique to the thread. +
+
+If not specified it defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the default thread pool should be used to complete the futures returned from the HTTP client request. +
+
+When disabled, futures will be completed on the Netty event loop thread. +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The LocalStack container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path to init scripts folder executed during localstack startup. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Classpath to init scripts folder executed during localstack startup. initScriptsFolder has higher precedence. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specific container log message to be waiting for localstack init scripts completion. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port localstack will listen to. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+If a local AWS stack should be used. (default to true) If this is true and endpoint-override is not configured then a local AWS stack will be started and will be used instead of the given configuration. For all services but Cognito, the local AWS stack will be provided by LocalStack. Otherwise, it will be provided by Moto +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Indicates if the LocalStack container managed by Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services starts a new container. +
+
+The discovery uses the
+
+Sharing is not supported for the Cognito extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicates if shared LocalStack services managed by Dev Services should be isolated. When true, the service will be started in its own container and the value of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared LocalStack instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Moto container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Generic properties that are pass for additional container configuration. +
+
+Environment variable: |
+
|
++ |
This set of extensions expose AWS services through configuration properties and CDI injection.
+You can find the full set of supported services and documentation for each of them in the navigation on the left.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If Dev Services for ClamAV has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The ClamAV container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicates if the ClamAV server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ClamAV starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ClamAV servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The ClamAV container image to use. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Flag to enable the FreshClam daemon to update the virus database daily. Default it is disabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable ClamAV container logging +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If ClamAv registers in the health check by pinging the service. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Property to enable or disable the virus scanner. Useful for developers who don’t want to scan files locally. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The IP Address of the machine where ClamAV is running. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Port of the machine where ClamAV is running. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The timeout of how much time to give CLamAV to scan the virus before failing. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Size in bytes of the chunks of data to stream to the scanner at a time. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The timeout of how much time to give CLamAV to scan the virus before failing. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Property to enable or disable the virus scanner. Useful for developers who don’t want to scan files locally. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The API endpoint for VirusTotal. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The API key for VirusTotal. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+VirusTotal checks over 70+ different engine for virus and collates a count of how many of those 70 reported a file as malicious. This number lets you control how many engines have to report a file is malicious to raise an exception. +
+
+Environment variable: |
+int |
+
|
+
A Quarkus extension that lets you scan files for viruses using a pluggable engine architecture.
+Out of the box these engines are supported by this extension:
+ClamAV which is a Linux Native antivirus server
+VirusTotal which is a REST API to check the Hash of a file to see if it has already been reported for viruses
+If you want to use this extension, you need to add the io.quarkiverse.antivirus:quarkus-antivirus extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.antivirus</groupId>
+ <artifactId>quarkus-antivirus</artifactId>
+ <version>0.0.5</version>
+</dependency>Now that you configured your POM to use the service, now you need to configure which scanner(s) you want to use in application.properties:
ClamAV is an open source Linux based virus scanning engine. If you configure quarkus.antivirus.clamav.devservice.enabled=true a DevService will start a ClamAV instance for you on TCP port 3310, so you can test locally during development.
quarkus.antivirus.clamav.enabled=true
+quarkus.antivirus.clamav.health.enabled=true
+%dev.quarkus.antivirus.clamav.devservice.enabled=true
+%dev.quarkus.antivirus.clamav.host=localhost
+%dev.quarkus.antivirus.clamav.port=3310VirusTotal is a REST API that analyses suspicious files to detect malware using over 70 antivirus scanners. VirusTotal checks the hash of a file to see if it has been scanned and what the results are. You can set the threshold of how many of the 70+ engines you want to report the file as malicious before you consider it a malicious file using the minimum-votes property.
quarkus.antivirus.virustotal.enabled=true
+quarkus.antivirus.virustotal.key=<YOUR API KEY>
+quarkus.antivirus.virustotal.minimum-votes=1Simply inject the Antivirus service, and it will run the scan against all configured services. It works against InputStream so it can be used in any Quarkus application it is not constrained to REST applications only.
@Path("/antivirus")
+@ApplicationScoped
+public class AntivirusResource {
+
+ @Inject
+ Antivirus antivirus;
+
+ @PUT
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ @Produces(MediaType.TEXT_PLAIN)
+ @Path("/upload")
+ public Response upload(@MultipartForm @Valid final UploadRequest fileUploadRequest) {
+ final String fileName = fileUploadRequest.getFileName();
+ final InputStream data = fileUploadRequest.getData();
+ try {
+ // copy the stream to make it resettable
+ final ByteArrayInputStream inputStream = new ByteArrayInputStream(
+ IOUtils.toBufferedInputStream(data).readAllBytes());
+
+ // scan the file and check the results
+ List<AntivirusScanResult> results = antivirus.scan(fileName, inputStream);
+ for (AntivirusScanResult result : results) {
+ if (result.getStatus() != Response.Status.OK.getStatusCode()) {
+ throw new WebApplicationException(result.getMessage(), result.getStatus());
+ }
+ }
+
+ // reset the stream
+ inputStream.reset();
+
+ // write the file out to disk
+ final File tempFile = File.createTempFile("fileName", "tmp");
+ IOUtils.copy(inputStream, new FileOutputStream(tempFile));
+ } catch (AntivirusException | IOException e) {
+ throw new BadRequestException(e);
+ }
+
+ return Response.ok().build();
+ }
+}We can’t anticipate every antivirus engine out there and some may be proprietary. However, the architecture is designed to be pluggable, so you can plug your own engine in. Simply produce a bean that extends the AntivirusEngine interface, and it will be picked up and used.
@ApplicationScoped
+public class MyCustomEngine implements AntivirusEngine {
+
+ @Override
+ public boolean isEnabled() {
+ return true;
+ }
+
+ @Override
+ public AntivirusScanResult scan(final String filename, final InputStream inputStream) {
+ // scan your file here
+ }
+}The Dev UI will let you inspect the running ClamAV Dev Service.
+
+You can also inspect the container image that was started under Dev Services:
+
+You can view all of ClamAV’s container logs right in the DevUI log.
+
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If Dev Services for ClamAV has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The ClamAV container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicates if the ClamAV server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ClamAV starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ClamAV servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The ClamAV container image to use. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Flag to enable the FreshClam daemon to update the virus database daily. Default it is disabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable ClamAV container logging +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If ClamAv registers in the health check by pinging the service. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Property to enable or disable the virus scanner. Useful for developers who don’t want to scan files locally. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The IP Address of the machine where ClamAV is running. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Port of the machine where ClamAV is running. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The timeout of how much time to give CLamAV to scan the virus before failing. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Size in bytes of the chunks of data to stream to the scanner at a time. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The timeout of how much time to give CLamAV to scan the virus before failing. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Property to enable or disable the virus scanner. Useful for developers who don’t want to scan files locally. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The API endpoint for VirusTotal. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The API key for VirusTotal. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+VirusTotal checks over 70+ different engine for virus and collates a count of how many of those 70 reported a file as malicious. This number lets you control how many engines have to report a file is malicious to raise an exception. +
+
+Environment variable: |
+int |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The APIstax API key. Get one via https://apistax.io +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Enables the mock mode. +When enabled, requests are not send. Instead, fake data is returned. +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus APIstax is a complete Java client implementation for the APIstax platform.
+Add the following dependency to your build file:
+<dependency>
+ <groupId>io.quarkiverse.apistax</groupId>
+ <artifactId>quarkus-apistax</artifactId>
+ <version>2.2.1</version>
+</dependency>implementation("io.quarkiverse.apistax:quarkus-apistax:2.2.1")Get your APIstax API key here and add it to your application.properties file:
+quarkus.apistax.api-key=API-KEYInject an APIstaxClient and start using it.
@ApplicationScoped
+public class VatService {
+
+ @Inject
+ APIstaxClient client;
+
+ public boolean isValid(String vatId) {
+ VatVerificationResult result = client.verifyVatId(vatId);
+ return result.getValid() == true;
+ }
+}The further information and documentation about the APIs can be found on APIstax documentation page.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The APIstax API key. Get one via https://apistax.io +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Enables the mock mode. +When enabled, requests are not send. Instead, fake data is returned. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+communication protocol, possible values are: VST, HTTP_JSON, HTTP_VPACK, HTTP2_JSON, HTTP2_VPACK, (default: HTTP2_JSON) +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+connection and request timeout (ms), (default 0, no timeout) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+username for authentication, (default: root) +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+password for authentication +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+use SSL connection, (default: false) +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+enable hostname verification, (HTTP only, default: true) +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+VST chunk size in bytes, (default: 30000) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+max number of connections per host, (default: 1 VST, 1 HTTP/2, 20 HTTP/1.1) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+max lifetime of a connection (ms), (default: no ttl) +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+VST keep-alive interval (s), (default: no keep-alive probes will be sent) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+acquire the list of available hosts, (default: false) +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+acquireHostList interval (ms), (default: 3_600_000, 1 hour) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+load balancing strategy, possible values are: NONE, ROUND_ROBIN, ONE_RANDOM, (default: NONE) +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+amount of samples kept for queue time metrics, (default: 10) +
+
+Environment variable: |
+int |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+host hostname +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+
+host port +
+
+Environment variable: |
+int |
+required |
+
sslTruststore configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+location where to find the cert file +
+
+Environment variable: |
+path |
+required |
+
+
+
+
+
+
+trustStore password +
+
+Environment variable: |
+string |
+required |
+
ArangoDB is a scalable graph database system to drive value from connected data, faster. Native graphs, an integrated search engine, and JSON support, via a single query language.
+| + + | ++This extension has been developed following samples presents in ArangoDB Java Driver + | +
If you want to use this extension, you need to add the io.quarkiverse.arangodb-client-ext:quarkus-arangodb-client-ext extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.arangodb-client-ext</groupId>
+ <artifactId>quarkus-arangodb-client-ext</artifactId>
+ <version>1.0.1</version>
+</dependency>The Arangodb driver can be configured with standard Quarkus properties.
+Configuration support multiple hosts. If you have only one host you can default empty host naming can be used.
+Single Host configuration
+quarkus.arangodb.hosts.hostname = localhost
+quarkus.arangodb.hosts.port = 8529quarkus.arangodb.hosts.host1.hostname = host1
+quarkus.arangodb.hosts.host1.port = 8529
+quarkus.arangodb.hosts.host2.hostname = host2
+quarkus.arangodb.hosts.host2.port = 8529quarkus.arangodb.user = root
+quarkus.arangodb.password = passwordArangoDB Java Driver provide JWT based authentication. This kind of authentication is not implemented because no use case has been determined.
+To activate ssl secure connection please add these properties:
+quarkus.arangodb.use-ssl = true
+quarkus.arangodb.ssl-truststore.location = example.truststore
+quarkus.arangodb.ssl-truststore.password = 12345678| + + | ++The truststore muse be generated using the PEM certificate used on Arangodb server side. The truststore location can refer to resources folder or on an external one. It is preferable to use an external one to better handle certificate renewal or revocation without repackaging the application. + | +
| + + | +
+If you want to add, setup SSL using a PEM certificate on Arangodb side you could have a look to ArangodbContainer inside this project. It can give you good insights for producing custom container image regarding embedding certificate and updating arangodb.conf. You can easily produce an image based on official arangodb image and use /docker-entrypoint-initdb.d/ folder to add your custom shell or javascript scripts.
+ |
+
| + + | +
+PEM certificate and example.truststore using password 12345678 used in this extension are coming from the ArangoDB Java Driver
+ |
+
Quarkus supports a feature called Dev Services that allows you to create various datasources without any config.
+Dev Services will bring up an Arangodb container if you didn’t explicit add the default values or configured custom values for any of quarkus.arangodb.hosts.*, quarkus.arangodb.user or quarkus.arangodb.password.
Otherwise, Quarkus will automatically start an Arangodb container when running tests or dev-mode, and automatically configure the connection.
+When running the production version of the application, the Arangodb connection need to be configured as normal, so if you want to include a production database config in your application.properties and continue to use Dev Services we recommend that you use the %prod. profile to define your Neo4j settings.
For the following paragraph the Person object will be used as sample to describe many ways to use, implement custom serializer / deserializer.
import java.util.Objects;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public final class Person {
+ private final String name;
+
+ @JsonCreator
+ public Person(@JsonProperty("name") final String name) {
+ this.name = Objects.requireNonNull(name);
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o)
+ return true;
+ if (o == null || getClass() != o.getClass())
+ return false;
+ Person person = (Person) o;
+ return Objects.equals(name, person.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(name);
+ }
+
+ @Override
+ public String toString() {
+ return "Person{" +
+ "name='" + name + '\'' +
+ '}';
+ }
+}By default, if jackson is not added as a dependency in the application, the shaded Jackson version present inside the driver will be used. +In this case the configuration will be automatic. It works fine, however custom ObjectMapper configuration is not supported.
+To define custom Jackson configuration you can do it in several ways.
+Using Quarkus jackson
+Add this dependency in pom.xml
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-jackson</artifactId>
+</dependency>Next you can define a custom ObjectMapperCustomizer. This customizer is common across all the application.
import java.io.IOException;
+
+import jakarta.inject.Singleton;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.*;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+
+import io.quarkus.jackson.ObjectMapperCustomizer;
+
+@Singleton
+public final class RegisterCustomModuleCustomizer implements ObjectMapperCustomizer {
+ private static final String PERSON_SERIALIZER_ADDED_PREFIX = "MyNameIs";
+ private static final String PERSON_DESERIALIZER_ADDED_PREFIX = "Hello";
+
+ @Override
+ public void customize(final ObjectMapper mapper) {
+ final SimpleModule module = new SimpleModule("PersonModule");
+ module.addDeserializer(Person.class, new PersonDeserializer());
+ module.addSerializer(Person.class, new PersonSerializer());
+ mapper.registerModule(module);
+ }
+
+ private static class PersonSerializer extends JsonSerializer<Person> {
+ @Override
+ public void serialize(final Person value, final JsonGenerator gen, final SerializerProvider serializers)
+ throws IOException {
+ gen.writeStartObject();
+ gen.writeFieldName("name");
+ gen.writeString(PERSON_SERIALIZER_ADDED_PREFIX + value.getName());
+ gen.writeEndObject();
+ }
+ }
+
+ private static class PersonDeserializer extends JsonDeserializer<Person> {
+ @Override
+ public Person deserialize(final JsonParser parser, final DeserializationContext ctx) throws IOException {
+ final JsonNode rootNode = parser.getCodec().readTree(parser);
+ final JsonNode nameNode = rootNode.get("name");
+ final String name;
+ if (nameNode != null && nameNode.isTextual()) {
+ name = PERSON_DESERIALIZER_ADDED_PREFIX + nameNode.asText();
+ } else {
+ name = null;
+ }
+ return new Person(name);
+ }
+ }
+}Custom ArangodbSerde
+If you want to define ObjectMapper behaviors only for Arangodb you can do it by providing a custom ArangoSerde. Only one can be defined on the application.
import static com.fasterxml.jackson.databind.DeserializationFeature.USE_BIG_INTEGER_FOR_INTS;
+import static com.fasterxml.jackson.databind.SerializationFeature.WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED;
+
+import java.io.IOException;
+
+import jakarta.enterprise.inject.Produces;
+import jakarta.inject.Singleton;
+
+import com.arangodb.ContentType;
+import com.arangodb.serde.ArangoSerde;
+import com.arangodb.serde.jackson.JacksonSerde;
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.*;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+
+@Singleton
+public final class CustomArangodbSerde {
+ private static final String PERSON_SERIALIZER_ADDED_PREFIX = "MyNameIs";
+ private static final String PERSON_DESERIALIZER_ADDED_PREFIX = "Hello";
+
+ @Singleton
+ @Produces
+ public ArangoSerde arangodbSerdeProducer() {
+ return JacksonSerde.of(ContentType.JSON)
+ .configure(mapper -> {
+ mapper.configure(WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED, true);
+ mapper.configure(USE_BIG_INTEGER_FOR_INTS, true);
+ final SimpleModule module = new SimpleModule("PersonModule");
+ module.addDeserializer(Person.class, new CustomArangodbSerde.PersonDeserializer());
+ module.addSerializer(Person.class, new CustomArangodbSerde.PersonSerializer());
+ mapper.registerModule(module);
+ });
+ }
+
+ private static class PersonSerializer extends JsonSerializer<Person> {
+ @Override
+ public void serialize(final Person value, final JsonGenerator gen, final SerializerProvider serializers)
+ throws IOException {
+ gen.writeStartObject();
+ gen.writeFieldName("name");
+ gen.writeString(PERSON_SERIALIZER_ADDED_PREFIX + value.getName());
+ gen.writeEndObject();
+ }
+ }
+
+ private static class PersonDeserializer extends JsonDeserializer<Person> {
+ @Override
+ public Person deserialize(final JsonParser parser, final DeserializationContext ctx) throws IOException {
+ final JsonNode rootNode = parser.getCodec().readTree(parser);
+ final JsonNode nameNode = rootNode.get("name");
+ final String name;
+ if (nameNode != null && nameNode.isTextual()) {
+ name = PERSON_DESERIALIZER_ADDED_PREFIX + nameNode.asText();
+ } else {
+ name = null;
+ }
+ return new Person(name);
+ }
+ }
+}By default, the SSLContext implementation use this example SslExampleTest defined in ArangoDB Java Driver.
+It is convenient for most SSL use case. It can use certificate embedded inside the application or outside.
+If you want to provide your own implementation returning the SSLContext you can do it by implementing your own ArangodbSSLContextProvider.
import javax.net.ssl.SSLContext;
+
+import jakarta.enterprise.inject.Produces;
+import jakarta.inject.Singleton;
+
+import io.quarkiverse.arangodb.client.ext.runtime.ArangodbClientConfig;
+import io.quarkiverse.arangodb.client.ext.runtime.ArangodbSSLContextException;
+import io.quarkiverse.arangodb.client.ext.runtime.ArangodbSSLContextProvider;
+
+@Singleton
+public final class CustomArangodbSSLContextProviderProducer {
+ static final class CustomArangodbSSLContextProvider implements ArangodbSSLContextProvider {
+
+ @Override
+ public SSLContext provide() throws ArangodbSSLContextException {
+ throw new RuntimeException("TODO");
+ }
+
+ }
+
+ @Singleton
+ @Produces
+ public ArangodbSSLContextProvider customArangodbSSLContextProviderProducer(
+ final ArangodbClientConfig arangodbClientConfig) {
+ return new CustomArangodbSSLContextProvider();
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+communication protocol, possible values are: VST, HTTP_JSON, HTTP_VPACK, HTTP2_JSON, HTTP2_VPACK, (default: HTTP2_JSON) +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+connection and request timeout (ms), (default 0, no timeout) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+username for authentication, (default: root) +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+password for authentication +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+use SSL connection, (default: false) +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+enable hostname verification, (HTTP only, default: true) +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+VST chunk size in bytes, (default: 30000) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+max number of connections per host, (default: 1 VST, 1 HTTP/2, 20 HTTP/1.1) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+max lifetime of a connection (ms), (default: no ttl) +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+VST keep-alive interval (s), (default: no keep-alive probes will be sent) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+acquire the list of available hosts, (default: false) +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+acquireHostList interval (ms), (default: 3_600_000, 1 hour) +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+load balancing strategy, possible values are: NONE, ROUND_ROBIN, ONE_RANDOM, (default: NONE) +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+amount of samples kept for queue time metrics, (default: 10) +
+
+Environment variable: |
+int |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+host hostname +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+
+host port +
+
+Environment variable: |
+int |
+required |
+
sslTruststore configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+location where to find the cert file +
+
+Environment variable: |
+path |
+required |
+
+
+
+
+
+
+trustStore password +
+
+Environment variable: |
+string |
+required |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable this configuration. +Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The ActiveMQ Artemis container image to use.
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set.
+The discovery uses the
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether camel context enhancement should be enabled.
+If enabled, all
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Artemis connection url +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether to enable this configuration. +Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The ActiveMQ Artemis container image to use.
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set.
+The discovery uses the
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Artemis connection url +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
This extension enables the use of the Apache ActiveMQ Artemis JMS client in Quarkus.
+It provides configuration properties to configure the JMS client and native executable support.
+For general considerations about the JMS support in Quarkus, it is recommended to read the JMS guide.
+| Quarkus version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+ latest |
+
+ 2024-04-30 + |
+
+
|
+
+ latest |
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
| Quarkus LTS version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>2.1.3</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-jms extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-jms</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-test-artemis</artifactId>
+ <scope>test</scope>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
If you are using camel-quarkus, we also recommend setting camel-quarkus.platform.version to the version of camel used.
As with quarkus.datasource, we can configure multiple, named configuration. If a configuration is configured under the root quarkus.artemis, then this is the default or unnamed configuration.
quarkus.artemis.url=...
+quarkus.artemis.username=...
+quarkus.artemis.password=...This corresponding bean is registered as the @Default bean and can be injected without additional qualifiers.
| + + | ++There must be some build-time configuration, otherwise the bean will not be available. Having only run-time configuration (e.g. environment variables) is not enough. Please see section Configuration detection at build-time for details. + | +
ServerLocator when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}It is also registered with @Identifier("<default>"), so we can inject it with
ServerLocator by its explicit name when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory by its explicit name when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}Named configurations, on the other hand, are not configured as @Default beans and must therefore be injected by name. The name of the bean is the name of the configuration, and @Identifier(…) is used to qualify the name. So for example, if we define a configuration "named-1":
quarkus.artemis."named-1".url=...
+quarkus.artemis."named-1".username=...
+quarkus.artemis."named-1".password=...we can inject it with:
+ServerLocator "named-1" when using extension quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory "named-1" when using extension quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}| + + | +
+We strongly recommend the usage of @Identifier annotation instead of the @Named annotation. Some other feature rely on the usage of @Identifier. Please see section Health checks for details.
+ |
+
@Default BeanWhen an unnamed configuration is provided, this configuration will be registered as @Default bean. Otherwise, if only a single configuration is provided, this configuration will be registered as @Default bean. This mechanism allows us to inject this bean without any qualifier.
When we override the properties url, username or password of a configuration at runtime - either through the implicit environment variable (QUARKUS_ARTEMIS_URL, QUARKUS_ARTEMIS__CONNECTION_NAME__URL), a custom environment variable (quarkus.artemis.url=${ARTEMIS_URL:tcp://dummy:12345}) or a runtime-provided .properties-/.yaml files, we will see a warning at startup similar to this one:
2022-11-03 00:53:17,060 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime:
+ - quarkus.artemis.url is set to 'tcp://localhost:61616' but it is build time fixed to 'tcp://dummy:12345'. Did you change the property quarkus.artemis.url after building the application?This is expected. We bind some properties twice: once as build-time property, once as run time property. We do so to analyze the (run time-)configuration at build time to get a list of named connections. The overwritten configuration will take effect. The correct behaviour is enforced by two different tests. The above example is taken from the logs of those tests.
+We took special care so the configurations behave "as intuitively as possible". This means that if no connection-related configuration (enabled, url, username, password, devservices…, health-exclude, xa-enabled) is present at build-time, it is assumed that the configuration is not used and disabled. Therefore, if we want to use any configuration, but not configure it, we should set quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true to explicitly enable the configuration. Due to the fact how the configuration system works in quarkus, we are only able to analyze properties defined in the default profile, i.e. properties without a prefix (%dev, %text, …). If in doubt, we recommend setting quarkus.artemis.enabled/quarkus.artemis."named-configuration".enabled to true.
| + + | +
+This is also the case if we bind properties in the default profile to environment variables, without a default value. For example, quarkus.artemis.url=${ARTEMIS_URL} has no value at build-time, thus this property is "invisible" at build time.
+ |
+
| + + | +
+Binding a property to an environment variable, like quarkus.artemis.url=${ARTEMIS_URL} is sufficient, so the extension can pick up the configuration at build-time.
+ |
+
| + + | +
+If we want to configure a connection solely through the implicit environment variables QUARKUS_ARTEMIS_…, we should enable the configuration by setting quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true. For example, if we want to configure connection quarkus.artemis."named-1" through the implicit environment variables, we would set quarkus.artemis."named-1".enabled=true and then configure the connection through environment variables QUARKUS_ARTEMIS__NAMED_1__….
+ |
+
Table Visibility of configuration values gives an overview when a property is visible at build time, and when it is not.
+| Description | +Example | +Visible? | +
|---|---|---|
+ configuration property belonging to a specific profile + |
+
+
|
+
+ ❌ + |
+
+ configuration property bound to constant value + |
+
+
|
+
+ ✔️ + |
+
+ configuration property bound to environment variable + |
+
+
|
+
+ ❌ + |
+
+ configuration property bound to environment variable with default value + |
+
+
|
+
+ ✔️ + |
+
Please do not try to configure a configuration purely through environment variables, without having any indication of its present in the application’s configuration file. We specifically rely on the presence of some configuration fragment at build-time to detect configurations.
+To get XA-capable connection factories, we can set quarkus.artemis.xa-enabled / quarkus.artemis."named-configuration".xa-enabled to true. We can then inject the corresponding bean as XAConnectionFactory.
To use XA transactions and integrate with a transaction manager, we recommend using the quarkus-pooled-jms quarkiverse extension.
+The url configuration property is optional. But in general, without a url property, we cannot create a connection. In case of tests with embedded resources or devservices, the corresponding annotation/service injects a url. But if the application starts up and no url property is found, the creation of the bean will throw a RuntimeException with a corresponding error message. Notice that this will happen when the bean is created. If the bean is never used (and thus never created), the exception will not occur.
By default, all configurations are added to the health check endpoint when extension quarkus-smallrye-health is loaded.
We can disable health checks for all ServerLocator s (extension quarkus-artemis-core) or ConnectionFactory s (extension quarkus-artemis-jms) by setting quarkus.artemis.health.enabled to false.
We can disable health checks for individual configurations by setting quarkus.artemis.health-exclude / quarkus.artemis."named-configuration".health-exclude to true
| + + | +
+Note that we can only enable health checks through the above configuration if quarkus.artemis.health.enabled is true. Otherwise, setting quarkus.artemis.health-exclude / quarkus.artemis."named-connection".health-exclude has no effect.
+ |
+
If we create ServerLocator- (extension quarkus-artemis-core) or ConnectionFactory- (extension quarkus-artemis-jms) beans within our application (i.e. outside of this extension), we can include them in the health check by using the @Identifier annotation, e.g.:
ServerLocator-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identified("my-server-locator") // this annotation makes it so the bean is picked up by the health endpoint
+ public ServerLocator mySeverLocator(...) {
+ ServerLocator myServerLocator = ...;
+ ...
+ return myServerLocator;
+ }
+}ConnectionFactory-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identified("my-connection-factory") // this annotation makes it so the bean is picked up by the health endpoint
+ public ConnectionFactory myConnectionFactory(...) {
+ ConnectionFactory myConnectionFactory = ...;
+ ...
+ return myConnectionFactory;
+ }
+}If we do not want that beans created within our application is picked up by the health endpoint, we can set quarkus.artemis.health.external.enabled to false.
| + + | +
+Note that ServerLocator s / ConnectionFactory s are only picked up when quarkus.artemis.health.enabled is true.
+ |
+
All connection factories that are configured through quarkus-artemis-jms are automatically registered in the camel context, if the program uses camel. This allows us to reference the connection factories by name, e.g.:
ConnectionFactory s in a camel route by their bean namefrom(jms("queue:in").connectionFactory("<default>"))
+ .to(jms("queue:out").connectionFactory("named"));In camel-quarkus, an externally defined ConnectionFactory can only be referenced by its name in a route configuration if it has a @Named(…) annotation (documentation). This conflicts somewhat with the philosophy of the quarkus-artemis extensions, since it uses @Identifier instead. We bridge this gap by allowing to register all ConnectionFactory s annotated with @Identifier with the camel context. To enable this feature, we can set configuration property quarkus.artemis.camel-quarkus-enhance-enabled to true. This property is set to false by default.
With this in place, we can define a ConnectionFactory, e.g. through a method annotated with @Produces and, for example, @Identifier("externally-defined"):
ConnectionFactory-bean through a @Produces method@Produces
+@Typed({ ConnectionFactory.class })
+@ApplicationScoped
+@Identifier("externally-defined")
+ActiveMQConnectionFactory externallyDefinedConnectionFactory(
+ @ConfigProperty(name = "artemis.externally-defined.url") String externallyDefinedUrl) {
+ return new ActiveMQConnectionFactory(externallyDefinedUrl);
+}We can then use this ConnectionFactory as follows:
ConnectionFactory-bean by its namefrom(jms("queue:in").connectionFactory("externally-defined"))
+ .to(jms("queue:out").connectionFactory("externally-defined"));Finally, if only a single ConnectionFactory is defined through quarkus-artemis-jms, this ConnectionFactory is always registered as @Default bean (see Section @Default Bean). This allows us to use this ConnectionFactory implicitly in a camel route, without setting it explicitly:
ConnectionFactory-bean defined in the applicationfrom(jms("queue:in"))
+ .to(jms("queue:out"));This also works for an externally defined ConnectionFactory, as long as it is defined as @Default (remember that all beans that do not have any qualifier annotation are automatically @Default beans). For an externally defined ConnectionFactory, this does not require to set quarkus.artemis.camel-context-enhance-enable to be true.
This mechanism stops working as soon as more than one ConnectionFactory bean is defined in the application.
Artemis DevServices are automatically enabled unless quarkus.artemis.url / quarkus.artemis."named-configuration".url is set or quarkus.artemis.devservices.enabled / quarkus.artemis."named-configuration".enabled is false explicitly. And if you still want to use ArtemisTestResource in the test, you need to disable artemis devservices.
To facilitate testing, we provide a dedicated testing framework that can start an in-memory artemis instance For the default configuration, we can start an in-memory instance of artemis by annotating our tests with @QuarkusTestResource(ArtemisTestResource.class). The embedded artemis can be configured through a broker.xml, located under src/test/resources.
To start an in-memory artemis for a named configuration, we can define our own test annotation by extending ArtemisTestResource.class:
public class NamedOneArtemisTestResource extends ArtemisTestResource {
+ public NamedOneArtemisTestResource() {
+ super("named-1");
+ }
+}We can then annotate our test with @QuarkusTestResource(NamedOneArtemisTestResource.class).
This instance can be configured by placing a broker-named-1.xml in src/test/resources. In general, for a configuration with name <name>, we can configure the corresponding in-memory artemis through file src/test/resources/broker-<name>.xml.
For an in-depth explanation of what can be configured in a broker.xml, please see the official Artemis documentation.
Examples can be found in the integration-tests module, e.g.
+The Apache ActiveMQ Artemis Core integration with default configuration tests module
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable this configuration. +Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The ActiveMQ Artemis container image to use.
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set.
+The discovery uses the
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether camel context enhancement should be enabled.
+If enabled, all
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Artemis connection url +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Whether to enable this configuration. +Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The ActiveMQ Artemis container image to use.
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set.
+The discovery uses the
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Artemis connection url +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for authentication, only used with JMS +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This set of extensions enable Artemis JMS Client and Artemis JMS Resource Adapter in Quarkus.
+You can find the full set of support and documentation for both of them in the navigation on the left.
+This extension enables the use of the Apache ActiveMQ Artemis JMS client in Quarkus.
+It provides configuration properties to configure the JMS client and native executable support.
+For general considerations about the JMS support in Quarkus, it is recommended to read the JMS guide.
+| Quarkus version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+ latest |
+
+ 2024-04-30 + |
+
+
|
+
+ latest |
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
| Quarkus LTS version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.0.5</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-jms extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-jms</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-test-artemis</artifactId>
+ <scope>test</scope>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
If you are using camel-quarkus, we also recommend setting camel-quarkus.platform.version to the version of camel used.
As with quarkus.datasource, we can configure multiple, named configuration. If a configuration is configured under the root quarkus.artemis, then this is the default or unnamed configuration.
quarkus.artemis.url=...
+quarkus.artemis.username=...
+quarkus.artemis.password=...This corresponding bean is registered as the @Default bean and can be injected without additional qualifiers.
| + + | ++There must be some build-time configuration, otherwise the bean will not be available. Having only run-time configuration (e.g. environment variables) is not enough. Please see section Configuration detection at build-time for details. + | +
ServerLocator when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}It is also registered with @Identifier("<default>"), so we can inject it with
ServerLocator by its explicit name when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory by its explicit name when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}Named configurations, on the other hand, are not configured as @Default beans and must therefore be injected by name. The name of the bean is the name of the configuration, and @Identifier(…) is used to qualify the name. So for example, if we define a configuration "named-1":
quarkus.artemis."named-1".url=...
+quarkus.artemis."named-1".username=...
+quarkus.artemis."named-1".password=...we can inject it with:
+ServerLocator "named-1" when using extension quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory "named-1" when using extension quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}| + + | +
+We strongly recommend the usage of @Identifier annotation instead of the @Named annotation. Some other feature rely on the usage of @Identifier. Please see section Health checks for details.
+ |
+
When we override the properties url, username or password of a configuration at runtime - either through the implicit environment variable (QUARKUS_ARTEMIS_URL, QUARKUS_ARTEMIS__CONNECTION_NAME__URL), a custom environment variable (quarkus.artemis.url=${ARTEMIS_URL:tcp://dummy:12345}) or a runtime-provided .properties files, we will see a warning at startup similar to this one:
2022-11-03 00:53:17,060 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime:
+ - quarkus.artemis.url is set to 'tcp://localhost:61616' but it is build time fixed to 'tcp://dummy:12345'. Did you change the property quarkus.artemis.url after building the application?This is expected. We bind some properties twice: once as build-time property, once as run time property. We do so to analyze the (run time-)configuration at build time to get a list of named connections. The overwritten configuration will take effect. The correct behaviour enforced by two different tests. The above example is taken from the logs of our tests.
+We took special care so the configurations behave "as intuitively as possible". This means that if no connection-related configuration (enabled, url, username, password, devservices…, health-exclude, xa-enabled) is present at build-time, it is assumed that the configuration is not used and disabled. Therefore, if we want to use any configuration, but not configure it, we should set quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true to explicitly enable the configuration.
| + + | +
+binding a property to an environment variable, like quarkus.artemis.url=${ARTEMIS_URL} is sufficient, so the extension can pick up the configuration at build-time.
+ |
+
| + + | +
+If we want to configure a connection solely through the implicit environment variables QUARKUS_ARTEMIS_…, we should enable the configuration by setting quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true. For example, if we want to configure connection quarkus.artemis."named-1" through the implicit environment variables, we would set quarkus.artemis."named-1".enabled=true and then configure the connection through environment variables QUARKUS_ARTEMIS__NAMED_1__….
+ |
+
Please do not try to configure a configuration purely through environment variables, without having any indication of its presence in the application’s configuration file. We specifically rely on the presence of some configuration fragment at build-time to detect configurations.
+To get XA-capable connection factories, we can set quarkus.artemis.xa-enabled / quarkus.artemis."named-configuration".xa-enabled to true. We can then inject the corresponding bean as XAConnectionFactory.
To use XA transactions and integrate with a transaction manager, we recommend using the quarkus-pooled-jms quarkiverse extension.
+The url configuration property is optional. But in general, without a url property, we cannot create a connection. In case of tests with embedded resources or devservices, the corresponding annotation/service injects a url. But if the application starts up and no url property is found, the creation of the bean will throw a RuntimeException with a corresponding error message. Notice that this will happen when the bean is created. If the bean is never used (and thus never created), the exception will not occur.
By default, all configurations are added to the health check endpoint when extension quarkus-smallrye-health is loaded.
We can disable health checks for all ServerLocator s (extension quarkus-artemis-core) or ConnectionFactory s (extension quarkus-artemis-jms) by setting quarkus.artemis.health.enabled to false.
We can disable health checks for individual configurations by setting quarkus.artemis.health-exclude / quarkus.artemis."named-configuration".health-exclude to true
| + + | +
+Note that we can only enable health checks through the above configuration if quarkus.artemis.health.enabled is true. Otherwise, setting quarkus.artemis.health-exclude / quarkus.artemis."named-connection".health-exclude has no effect.
+ |
+
If we create ServerLocator- (extension quarkus-artemis-core) or ConnectionFactory- (extension quarkus-artemis-jms) beans within our application (i.e. outside of this extension), we can include them in the health check by using the Identifier annotation, e.g.:
ServerLocator-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-server-locator") // this annotation makes it so the bean is picked up by the health endpoint
+ public ServerLocator mySeverLocator(...) {
+ ServerLocator myServerLocator = ...;
+ ...
+ return myServerLocator;
+ }
+}ConnectionFactory-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-connection-factory") // this annotation makes it so the bean is picked up by the health endpoint
+ public ConnectionFactory myConnectionFactory(...) {
+ ConnectionFactory myConnectionFactory = ...;
+ ...
+ return myConnectionFactory;
+ }
+}If we do not want that beans created within our application is picked up by the health endpoint, we can set quarkus.artemis.health.external.enabled to false.
| + + | +
+Note that ServerLocator s / ConnectionFactory s are only picked up when quarkus.artemis.health.enabled is true.
+ |
+
All connection factories that are configured through quarkus-artemis-jms are automatically registered in the camel context, if the program uses camel. This allows us to reference the connection factories by name, e.g.:
ConnectionFactory s in a camel route by their bean namefrom(jms("queue:in").connectionFactory("<default>"))
+ .to(jms("queue:out").connectionFactory("named"));In camel-quarkus, an externally defined ConnectionFactory can only be referenced by its name in a route configuration if it has either a @Named(…) or the @Identifier(…) annotation. However, as mentioned above, the usage of @Identifier(…) should be preferred when using this extension.
ConnectionFactory-bean through a @Produces method@Produces
+@Typed({ ConnectionFactory.class })
+@ApplicationScoped
+@Identifier("externally-defined")
+ActiveMQConnectionFactory externallyDefinedConnectionFactory(
+ @ConfigProperty(name = "artemis.externally-defined.url") String externallyDefinedUrl) {
+ return new ActiveMQConnectionFactory(externallyDefinedUrl);
+}We can then use this ConnectionFactory as follows:
ConnectionFactory-bean by its namefrom(jms("queue:in").connectionFactory("externally-defined"))
+ .to(jms("queue:out").connectionFactory("externally-defined"));Finally, if only a single ConnectionFactory is defined through quarkus-artemis-jms, this ConnectionFactory is always registered as @Default bean. This allows us to use this ConnectionFactory implicitly in a camel route, without setting it explicitly:
ConnectionFactory-bean defined in the applicationfrom(jms("queue:in"))
+ .to(jms("queue:out"));This also works for an externally defined ConnectionFactory, as long as it is defined as @Default (remember that all beans that do not have any qualifier annotation are automatically @Default beans).
This mechanism stops working as soon as more than one ConnectionFactory bean is defined in the application.
Artemis DevServices are automatically enabled unless quarkus.artemis.url / quarkus.artemis."named-configuration".url is set or quarkus.artemis.devservices.enabled / quarkus.artemis."named-configuration".enabled is false explicitly. And if you still want to use ArtemisTestResource in the test, you need to disable artemis devservices.
To facilitate testing, we provide a dedicated testing framework that can start an in-memory artemis instance For the default configuration, we can start an in-memory instance of artemis by annotating our tests with @QuarkusTestResource(ArtemisTestResource.class). The embedded artemis can be configured through a broker.xml, located under src/test/resources.
To start an in-memory artemis for a named configuration, we can define our own test annotation by extending ArtemisTestResource.class:
public class NamedOneArtemisTestResource extends ArtemisTestResource {
+ public NamedOneArtemisTestResource() {
+ super("named-1");
+ }
+}We can then annotate our test with @QuarkusTestResource(NamedOneArtemisTestResource.class).
This instance can be configured by placing a broker-named-1.xml in src/test/resources. In general, for a configuration with name <name>, we can configure the corresponding in-memory artemis through file src/test/resources/broker-<name>.xml.
For an in-depth explanation of what can be configured in a broker.xml, please see the official Artemis documentation.
Examples can be found in the integration-tests module, e.g.
+The Apache ActiveMQ Artemis Core integration with default configuration tests module
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This extension enables the use of the Apache ActiveMQ Artemis JMS Resource Adapter in Quarkus.
+And it leverages on Quarkus IronJacamar
+To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.0.5</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-ra extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-ra</artifactId>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
quarkus.ironjacamar.ra.kind=artemis (1)
+
+quarkus.ironjacamar.ra.config.connection-parameters=host=localhost;port=5445;protocols=HORNETQ (2)
+quarkus.ironjacamar.ra.config.protocol-manager-factory=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
+quarkus.ironjacamar.ra.config.user=guest
+quarkus.ironjacamar.ra.config.password=guest
+quarkus.ironjacamar.ra.config.client-id=Quarkus
+
+quarkus.ironjacamar.activation-spec.myqueue.config.destination-type=jakarta.jms.Queue (3)
+quarkus.ironjacamar.activation-spec.myqueue.config.destination=jms.queue.MyQueue
+quarkus.ironjacamar.activation-spec.myqueue.config.max-session=2
+quarkus.ironjacamar.activation-spec.myqueue.config.rebalance-connections=true| 1 | +This is the resource adapter kind.
+It must match the value of the @ResourceAdapterKind annotation in the ResourceAdapterFactory implementation. |
+
| 2 | +(Optional) You can specify the resource adapter configuration that will be passed to your ResourceAdapterFactory#createResourceAdapter implementation method. |
+
| 3 | +(Optional) You can specify optional activation spec configuration ResourceAdapterFactory#createActivationSpec implementation method. |
+
You can configure more than one ResourceAdapter instance in your application.
+Just name the resource adapter in the configuration:
quarkus.ironjacamar.main.ra.kind=artemis (1)
+quarkus.ironjacamar.other.ra.kind=artemisTo reference in the code, you must use the @io.smallrye.common.annotation.Identifier annotation:
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+import io.smallrye.common.annotation.Identifier;
+
+import jakarta.inject.Inject;
+
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.Message;
+import jakarta.jms.MessageListener;
+
+@ResourceEndpoint(activationSpecConfigKey="myqueue")
+@Identifier("other") (1)
+public class MyResourceEndpoint implements MessageListener {
+
+ @Inject
+ @Identifier("main")
+ ConnectionFactory connectionFactory; (2)
+
+ @Override
+ public void onMessage(Message message) {
+ //...
+ }
+}| 1 | +This MessageListener will be activated by the other resource adapter configured above. |
+
| 2 | +This ConnectionFactory will be the one configured in the main resource adapter. |
+
For more details about Quarkus IronJacamar Configuration, please refer to the documents.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This set of extensions enable Artemis JMS Client and Artemis JMS Resource Adapter in Quarkus.
+You can find the full set of support and documentation for both of them in the navigation on the left.
+This extension enables the use of the Apache ActiveMQ Artemis JMS client in Quarkus.
+It provides configuration properties to configure the JMS client and native executable support.
+For general considerations about the JMS support in Quarkus, it is recommended to read the JMS guide.
+| Quarkus version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+ latest |
+
+ 2024-04-30 + |
+
+
|
+
+ latest |
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
| Quarkus LTS version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.1.4</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-jms extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-jms</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-test-artemis</artifactId>
+ <scope>test</scope>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
If you are using camel-quarkus, we also recommend setting camel-quarkus.platform.version to the version of camel used.
As with quarkus.datasource, we can configure multiple, named configuration. If a configuration is configured under the root quarkus.artemis, then this is the default or unnamed configuration.
quarkus.artemis.url=...
+quarkus.artemis.username=...
+quarkus.artemis.password=...This corresponding bean is registered as the @Default bean and can be injected without additional qualifiers.
| + + | ++There must be some build-time configuration, otherwise the bean will not be available. Having only run-time configuration (e.g. environment variables) is not enough. Please see section Configuration detection at build-time for details. + | +
ServerLocator when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}It is also registered with @Identifier("<default>"), so we can inject it with
ServerLocator by its explicit name when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory by its explicit name when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}Named configurations, on the other hand, are not configured as @Default beans and must therefore be injected by name. The name of the bean is the name of the configuration, and @Identifier(…) is used to qualify the name. So for example, if we define a configuration "named-1":
quarkus.artemis."named-1".url=...
+quarkus.artemis."named-1".username=...
+quarkus.artemis."named-1".password=...we can inject it with:
+ServerLocator "named-1" when using extension quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory "named-1" when using extension quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}| + + | +
+We strongly recommend the usage of @Identifier annotation instead of the @Named annotation. Some other feature rely on the usage of @Identifier. Please see section Health checks for details.
+ |
+
When we override the properties url, username or password of a configuration at runtime - either through the implicit environment variable (QUARKUS_ARTEMIS_URL, QUARKUS_ARTEMIS__CONNECTION_NAME__URL), a custom environment variable (quarkus.artemis.url=${ARTEMIS_URL:tcp://dummy:12345}) or a runtime-provided .properties files, we will see a warning at startup similar to this one:
2022-11-03 00:53:17,060 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime:
+ - quarkus.artemis.url is set to 'tcp://localhost:61616' but it is build time fixed to 'tcp://dummy:12345'. Did you change the property quarkus.artemis.url after building the application?This is expected. We bind some properties twice: once as build-time property, once as run time property. We do so to analyze the (run time-)configuration at build time to get a list of named connections. The overwritten configuration will take effect. The correct behaviour enforced by two different tests. The above example is taken from the logs of our tests.
+We took special care so the configurations behave "as intuitively as possible". This means that if no connection-related configuration (enabled, url, username, password, devservices…, health-exclude, xa-enabled) is present at build-time, it is assumed that the configuration is not used and disabled. Therefore, if we want to use any configuration, but not configure it, we should set quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true to explicitly enable the configuration.
| + + | +
+binding a property to an environment variable, like quarkus.artemis.url=${ARTEMIS_URL} is sufficient, so the extension can pick up the configuration at build-time.
+ |
+
| + + | +
+If we want to configure a connection solely through the implicit environment variables QUARKUS_ARTEMIS_…, we should enable the configuration by setting quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true. For example, if we want to configure connection quarkus.artemis."named-1" through the implicit environment variables, we would set quarkus.artemis."named-1".enabled=true and then configure the connection through environment variables QUARKUS_ARTEMIS__NAMED_1__….
+ |
+
Please do not try to configure a configuration purely through environment variables, without having any indication of its presence in the application’s configuration file. We specifically rely on the presence of some configuration fragment at build-time to detect configurations.
+To get XA-capable connection factories, we can set quarkus.artemis.xa-enabled / quarkus.artemis."named-configuration".xa-enabled to true. We can then inject the corresponding bean as XAConnectionFactory.
To use XA transactions and integrate with a transaction manager, we recommend using the quarkus-pooled-jms quarkiverse extension.
+The url configuration property is optional. But in general, without a url property, we cannot create a connection. In case of tests with embedded resources or devservices, the corresponding annotation/service injects a url. But if the application starts up and no url property is found, the creation of the bean will throw a RuntimeException with a corresponding error message. Notice that this will happen when the bean is created. If the bean is never used (and thus never created), the exception will not occur.
By default, all configurations are added to the health check endpoint when extension quarkus-smallrye-health is loaded.
We can disable health checks for all ServerLocator s (extension quarkus-artemis-core) or ConnectionFactory s (extension quarkus-artemis-jms) by setting quarkus.artemis.health.enabled to false.
We can disable health checks for individual configurations by setting quarkus.artemis.health-exclude / quarkus.artemis."named-configuration".health-exclude to true
| + + | +
+Note that we can only enable health checks through the above configuration if quarkus.artemis.health.enabled is true. Otherwise, setting quarkus.artemis.health-exclude / quarkus.artemis."named-connection".health-exclude has no effect.
+ |
+
If we create ServerLocator- (extension quarkus-artemis-core) or ConnectionFactory- (extension quarkus-artemis-jms) beans within our application (i.e. outside of this extension), we can include them in the health check by using the Identifier annotation, e.g.:
ServerLocator-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-server-locator") // this annotation makes it so the bean is picked up by the health endpoint
+ public ServerLocator mySeverLocator(...) {
+ ServerLocator myServerLocator = ...;
+ ...
+ return myServerLocator;
+ }
+}ConnectionFactory-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-connection-factory") // this annotation makes it so the bean is picked up by the health endpoint
+ public ConnectionFactory myConnectionFactory(...) {
+ ConnectionFactory myConnectionFactory = ...;
+ ...
+ return myConnectionFactory;
+ }
+}If we do not want that beans created within our application is picked up by the health endpoint, we can set quarkus.artemis.health.external.enabled to false.
| + + | +
+Note that ServerLocator s / ConnectionFactory s are only picked up when quarkus.artemis.health.enabled is true.
+ |
+
All connection factories that are configured through quarkus-artemis-jms are automatically registered in the camel context, if the program uses camel. This allows us to reference the connection factories by name, e.g.:
ConnectionFactory s in a camel route by their bean namefrom(jms("queue:in").connectionFactory("<default>"))
+ .to(jms("queue:out").connectionFactory("named"));In camel-quarkus, an externally defined ConnectionFactory can only be referenced by its name in a route configuration if it has either a @Named(…) or the @Identifier(…) annotation. However, as mentioned above, the usage of @Identifier(…) should be preferred when using this extension.
ConnectionFactory-bean through a @Produces method@Produces
+@Typed({ ConnectionFactory.class })
+@ApplicationScoped
+@Identifier("externally-defined")
+ActiveMQConnectionFactory externallyDefinedConnectionFactory(
+ @ConfigProperty(name = "artemis.externally-defined.url") String externallyDefinedUrl) {
+ return new ActiveMQConnectionFactory(externallyDefinedUrl);
+}We can then use this ConnectionFactory as follows:
ConnectionFactory-bean by its namefrom(jms("queue:in").connectionFactory("externally-defined"))
+ .to(jms("queue:out").connectionFactory("externally-defined"));Finally, if only a single ConnectionFactory is defined through quarkus-artemis-jms, this ConnectionFactory is always registered as @Default bean. This allows us to use this ConnectionFactory implicitly in a camel route, without setting it explicitly:
ConnectionFactory-bean defined in the applicationfrom(jms("queue:in"))
+ .to(jms("queue:out"));This also works for an externally defined ConnectionFactory, as long as it is defined as @Default (remember that all beans that do not have any qualifier annotation are automatically @Default beans).
This mechanism stops working as soon as more than one ConnectionFactory bean is defined in the application.
Artemis DevServices are automatically enabled unless quarkus.artemis.url / quarkus.artemis."named-configuration".url is set or quarkus.artemis.devservices.enabled / quarkus.artemis."named-configuration".enabled is false explicitly. And if you still want to use ArtemisTestResource in the test, you need to disable artemis devservices.
To facilitate testing, we provide a dedicated testing framework that can start an in-memory artemis instance For the default configuration, we can start an in-memory instance of artemis by annotating our tests with @QuarkusTestResource(ArtemisTestResource.class). The embedded artemis can be configured through a broker.xml, located under src/test/resources.
To start an in-memory artemis for a named configuration, we can define our own test annotation by extending ArtemisTestResource.class:
public class NamedOneArtemisTestResource extends ArtemisTestResource {
+ public NamedOneArtemisTestResource() {
+ super("named-1");
+ }
+}We can then annotate our test with @QuarkusTestResource(NamedOneArtemisTestResource.class).
This instance can be configured by placing a broker-named-1.xml in src/test/resources. In general, for a configuration with name <name>, we can configure the corresponding in-memory artemis through file src/test/resources/broker-<name>.xml.
For an in-depth explanation of what can be configured in a broker.xml, please see the official Artemis documentation.
Examples can be found in the integration-tests module, e.g.
+The Apache ActiveMQ Artemis Core integration with default configuration tests module
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This extension enables the use of the Apache ActiveMQ Artemis JMS Resource Adapter in Quarkus.
+And it leverages on Quarkus IronJacamar
+To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.1.4</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-ra extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-ra</artifactId>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
quarkus.ironjacamar.ra.kind=artemis (1)
+
+quarkus.ironjacamar.ra.config.connection-parameters=host=localhost;port=5445;protocols=HORNETQ (2)
+quarkus.ironjacamar.ra.config.protocol-manager-factory=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
+quarkus.ironjacamar.ra.config.user=guest
+quarkus.ironjacamar.ra.config.password=guest
+quarkus.ironjacamar.ra.config.client-id=Quarkus
+
+quarkus.ironjacamar.activation-spec.myqueue.config.destination-type=jakarta.jms.Queue (3)
+quarkus.ironjacamar.activation-spec.myqueue.config.destination=jms.queue.MyQueue
+quarkus.ironjacamar.activation-spec.myqueue.config.max-session=2
+quarkus.ironjacamar.activation-spec.myqueue.config.rebalance-connections=true| 1 | +This is the resource adapter kind.
+It must match the value of the @ResourceAdapterKind annotation in the ResourceAdapterFactory implementation. |
+
| 2 | +(Optional) You can specify the resource adapter configuration that will be passed to your ResourceAdapterFactory#createResourceAdapter implementation method. |
+
| 3 | +(Optional) You can specify optional activation spec configuration ResourceAdapterFactory#createActivationSpec implementation method. |
+
You can configure more than one ResourceAdapter instance in your application.
+Just name the resource adapter in the configuration:
quarkus.ironjacamar.main.ra.kind=artemis (1)
+quarkus.ironjacamar.other.ra.kind=artemisTo reference in the code, you must use the @io.smallrye.common.annotation.Identifier annotation:
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+import io.smallrye.common.annotation.Identifier;
+
+import jakarta.inject.Inject;
+
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.Message;
+import jakarta.jms.MessageListener;
+
+@ResourceEndpoint(activationSpecConfigKey="myqueue")
+@Identifier("other") (1)
+public class MyResourceEndpoint implements MessageListener {
+
+ @Inject
+ @Identifier("main")
+ ConnectionFactory connectionFactory; (2)
+
+ @Override
+ public void onMessage(Message message) {
+ //...
+ }
+}| 1 | +This MessageListener will be activated by the other resource adapter configured above. |
+
| 2 | +This ConnectionFactory will be the one configured in the main resource adapter. |
+
For more details about Quarkus IronJacamar Configuration, please refer to the documents.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This set of extensions enable Artemis JMS Client and Artemis JMS Resource Adapter in Quarkus.
+You can find the full set of support and documentation for both of them in the navigation on the left.
+This extension enables the use of the Apache ActiveMQ Artemis JMS client in Quarkus.
+It provides configuration properties to configure the JMS client and native executable support.
+For general considerations about the JMS support in Quarkus, it is recommended to read the JMS guide.
+| Quarkus version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+ latest |
+
+ 2024-04-30 + |
+
+
|
+
+ latest |
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
| Quarkus LTS version | +Quarkus JMS version | +End of Life | +
|---|---|---|
+
|
+
+
|
+
+ TBD + |
+
+
|
+
+
|
+
+ TBD + |
+
To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.2.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-jms extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-jms</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-test-artemis</artifactId>
+ <scope>test</scope>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
If you are using camel-quarkus, we also recommend setting camel-quarkus.platform.version to the version of camel used.
As with quarkus.datasource, we can configure multiple, named configuration. If a configuration is configured under the root quarkus.artemis, then this is the default or unnamed configuration.
quarkus.artemis.url=...
+quarkus.artemis.username=...
+quarkus.artemis.password=...This corresponding bean is registered as the @Default bean and can be injected without additional qualifiers.
| + + | ++There must be some build-time configuration, otherwise the bean will not be available. Having only run-time configuration (e.g. environment variables) is not enough. Please see section Configuration detection at build-time for details. + | +
ServerLocator when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}It is also registered with @Identifier("<default>"), so we can inject it with
ServerLocator by its explicit name when using quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory by its explicit name when using quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("<default>") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}Named configurations, on the other hand, are not configured as @Default beans and must therefore be injected by name. The name of the bean is the name of the configuration, and @Identifier(…) is used to qualify the name. So for example, if we define a configuration "named-1":
quarkus.artemis."named-1".url=...
+quarkus.artemis."named-1".username=...
+quarkus.artemis."named-1".password=...we can inject it with:
+ServerLocator "named-1" when using extension quarkus-artemis-corepublic class MyClass {
+ ...
+ private final ServerLocator serverLocator;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ServerLocator serverLocator,
+ ...
+ ) {
+ ...
+ this.serverLocator = serverLocator;
+ ...
+ }
+}ConnectionFactory "named-1" when using extension quarkus-artemis-jmspublic class MyClass {
+ ...
+ private final ConnectionFactory connectionFactory;
+ ...
+
+ public MyClass (
+ ...
+ @Identifier("named-1") ConnectionFactory connectionFactory,
+ ...
+ ) {
+ ...
+ this.connectionFactory = connectionFactory;
+ ...
+ }
+}| + + | +
+We strongly recommend the usage of @Identifier annotation instead of the @Named annotation. Some other feature rely on the usage of @Identifier. Please see section Health checks for details.
+ |
+
When we override the properties url, username or password of a configuration at runtime - either through the implicit environment variable (QUARKUS_ARTEMIS_URL, QUARKUS_ARTEMIS__CONNECTION_NAME__URL), a custom environment variable (quarkus.artemis.url=${ARTEMIS_URL:tcp://dummy:12345}) or a runtime-provided .properties files, we will see a warning at startup similar to this one:
2022-11-03 00:53:17,060 WARN [io.qua.run.con.ConfigRecorder] (main) Build time property cannot be changed at runtime:
+ - quarkus.artemis.url is set to 'tcp://localhost:61616' but it is build time fixed to 'tcp://dummy:12345'. Did you change the property quarkus.artemis.url after building the application?This is expected. We bind some properties twice: once as build-time property, once as run time property. We do so to analyze the (run time-)configuration at build time to get a list of named connections. The overwritten configuration will take effect. The correct behaviour enforced by two different tests. The above example is taken from the logs of our tests.
+We took special care so the configurations behave "as intuitively as possible". This means that if no connection-related configuration (enabled, url, username, password, devservices…, health-exclude, xa-enabled) is present at build-time, it is assumed that the configuration is not used and disabled. Therefore, if we want to use any configuration, but not configure it, we should set quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true to explicitly enable the configuration.
| + + | +
+binding a property to an environment variable, like quarkus.artemis.url=${ARTEMIS_URL} is sufficient, so the extension can pick up the configuration at build-time.
+ |
+
| + + | +
+If we want to configure a connection solely through the implicit environment variables QUARKUS_ARTEMIS_…, we should enable the configuration by setting quarkus.artemis.enabled / quarkus.artemis."named-configuration".enabled to true. For example, if we want to configure connection quarkus.artemis."named-1" through the implicit environment variables, we would set quarkus.artemis."named-1".enabled=true and then configure the connection through environment variables QUARKUS_ARTEMIS__NAMED_1__….
+ |
+
Please do not try to configure a configuration purely through environment variables, without having any indication of its presence in the application’s configuration file. We specifically rely on the presence of some configuration fragment at build-time to detect configurations.
+To get XA-capable connection factories, we can set quarkus.artemis.xa-enabled / quarkus.artemis."named-configuration".xa-enabled to true. We can then inject the corresponding bean as XAConnectionFactory.
To use XA transactions and integrate with a transaction manager, we recommend using the quarkus-pooled-jms quarkiverse extension.
+The url configuration property is optional. But in general, without a url property, we cannot create a connection. In case of tests with embedded resources or devservices, the corresponding annotation/service injects a url. But if the application starts up and no url property is found, the creation of the bean will throw a RuntimeException with a corresponding error message. Notice that this will happen when the bean is created. If the bean is never used (and thus never created), the exception will not occur.
By default, all configurations are added to the health check endpoint when extension quarkus-smallrye-health is loaded.
We can disable health checks for all ServerLocator s (extension quarkus-artemis-core) or ConnectionFactory s (extension quarkus-artemis-jms) by setting quarkus.artemis.health.enabled to false.
We can disable health checks for individual configurations by setting quarkus.artemis.health-exclude / quarkus.artemis."named-configuration".health-exclude to true
| + + | +
+Note that we can only enable health checks through the above configuration if quarkus.artemis.health.enabled is true. Otherwise, setting quarkus.artemis.health-exclude / quarkus.artemis."named-connection".health-exclude has no effect.
+ |
+
If we create ServerLocator- (extension quarkus-artemis-core) or ConnectionFactory- (extension quarkus-artemis-jms) beans within our application (i.e. outside of this extension), we can include them in the health check by using the Identifier annotation, e.g.:
ServerLocator-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-server-locator") // this annotation makes it so the bean is picked up by the health endpoint
+ public ServerLocator mySeverLocator(...) {
+ ServerLocator myServerLocator = ...;
+ ...
+ return myServerLocator;
+ }
+}ConnectionFactory-bean that is picked up automatically by health checkspublic class MyBeanProvider {
+ @ApplicationScoped
+ @Identifier("my-connection-factory") // this annotation makes it so the bean is picked up by the health endpoint
+ public ConnectionFactory myConnectionFactory(...) {
+ ConnectionFactory myConnectionFactory = ...;
+ ...
+ return myConnectionFactory;
+ }
+}If we do not want that beans created within our application is picked up by the health endpoint, we can set quarkus.artemis.health.external.enabled to false.
| + + | +
+Note that ServerLocator s / ConnectionFactory s are only picked up when quarkus.artemis.health.enabled is true.
+ |
+
All connection factories that are configured through quarkus-artemis-jms are automatically registered in the camel context, if the program uses camel. This allows us to reference the connection factories by name, e.g.:
ConnectionFactory s in a camel route by their bean namefrom(jms("queue:in").connectionFactory("<default>"))
+ .to(jms("queue:out").connectionFactory("named"));In camel-quarkus, an externally defined ConnectionFactory can only be referenced by its name in a route configuration if it has either a @Named(…) or the @Identifier(…) annotation. However, as mentioned above, the usage of @Identifier(…) should be preferred when using this extension.
ConnectionFactory-bean through a @Produces method@Produces
+@Typed({ ConnectionFactory.class })
+@ApplicationScoped
+@Identifier("externally-defined")
+ActiveMQConnectionFactory externallyDefinedConnectionFactory(
+ @ConfigProperty(name = "artemis.externally-defined.url") String externallyDefinedUrl) {
+ return new ActiveMQConnectionFactory(externallyDefinedUrl);
+}We can then use this ConnectionFactory as follows:
ConnectionFactory-bean by its namefrom(jms("queue:in").connectionFactory("externally-defined"))
+ .to(jms("queue:out").connectionFactory("externally-defined"));Finally, if only a single ConnectionFactory is defined through quarkus-artemis-jms, this ConnectionFactory is always registered as @Default bean. This allows us to use this ConnectionFactory implicitly in a camel route, without setting it explicitly:
ConnectionFactory-bean defined in the applicationfrom(jms("queue:in"))
+ .to(jms("queue:out"));This also works for an externally defined ConnectionFactory, as long as it is defined as @Default (remember that all beans that do not have any qualifier annotation are automatically @Default beans).
This mechanism stops working as soon as more than one ConnectionFactory bean is defined in the application.
Artemis DevServices are automatically enabled unless quarkus.artemis.url / quarkus.artemis."named-configuration".url is set or quarkus.artemis.devservices.enabled / quarkus.artemis."named-configuration".enabled is false explicitly. And if you still want to use ArtemisTestResource in the test, you need to disable artemis devservices.
To facilitate testing, we provide a dedicated testing framework that can start an in-memory artemis instance For the default configuration, we can start an in-memory instance of artemis by annotating our tests with @QuarkusTestResource(ArtemisTestResource.class). The embedded artemis can be configured through a broker.xml, located under src/test/resources.
To start an in-memory artemis for a named configuration, we can define our own test annotation by extending ArtemisTestResource.class:
public class NamedOneArtemisTestResource extends ArtemisTestResource {
+ public NamedOneArtemisTestResource() {
+ super("named-1");
+ }
+}We can then annotate our test with @QuarkusTestResource(NamedOneArtemisTestResource.class).
This instance can be configured by placing a broker-named-1.xml in src/test/resources. In general, for a configuration with name <name>, we can configure the corresponding in-memory artemis through file src/test/resources/broker-<name>.xml.
For an in-depth explanation of what can be configured in a broker.xml, please see the official Artemis documentation.
Examples can be found in the integration-tests module, e.g.
+The Apache ActiveMQ Artemis Core integration with default configuration tests module
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+This is a global setting and is not specific to a datasource. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether configurations (
+
+Environment variable: |
+boolean |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether to enable this configuration. +
+
+Is enabled by default. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+The ActiveMQ Artemis container image to use. +
+
+Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Indicates if the ActiveMQ Artemis broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for ActiveMQ Artemis starts a new container. Is activated by default when not set. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared ActiveMQ Artemis brokers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+User to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password to start artemis broker. Defaults to
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Support to expose
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Artemis connection url. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Password for authentication, only used with JMS. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether this particular data source should be excluded from the health check if the general health check for data sources is enabled. +
+
+By default, the health check includes all configured data sources (if it is enabled). +
+
+Environment variable: |
+boolean |
++ |
This extension enables the use of the Apache ActiveMQ Artemis JMS Resource Adapter in Quarkus.
+And it leverages on Quarkus IronJacamar
+To benefit from a consistent definition of the Artemis dependencies (including artemis-server often used in the tests),
+it is recommended to add the following BOM to your project, below the Quarkus BOM:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-bom</artifactId>
+ <version>3.2.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>Once the BOM is added, simply add the io.quarkiverse.artemis:quarkus-artemis-ra extension:
<dependency>
+ <groupId>io.quarkiverse.artemis</groupId>
+ <artifactId>quarkus-artemis-ra</artifactId>
+</dependency>We recommend to set properties quarkus.version and artemis.version to the versions you are using/need to use. We also recommend to align artemis.version with the artemis server version used.
quarkus.ironjacamar.ra.kind=artemis (1)
+
+quarkus.ironjacamar.ra.config.connection-parameters=host=localhost;port=5445;protocols=HORNETQ (2)
+quarkus.ironjacamar.ra.config.protocol-manager-factory=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
+quarkus.ironjacamar.ra.config.user=guest
+quarkus.ironjacamar.ra.config.password=guest
+quarkus.ironjacamar.ra.config.client-id=Quarkus
+
+quarkus.ironjacamar.activation-spec.myqueue.config.destination-type=jakarta.jms.Queue (3)
+quarkus.ironjacamar.activation-spec.myqueue.config.destination=jms.queue.MyQueue
+quarkus.ironjacamar.activation-spec.myqueue.config.max-session=2
+quarkus.ironjacamar.activation-spec.myqueue.config.rebalance-connections=true| 1 | +This is the resource adapter kind.
+It must match the value of the @ResourceAdapterKind annotation in the ResourceAdapterFactory implementation. |
+
| 2 | +(Optional) You can specify the resource adapter configuration that will be passed to your ResourceAdapterFactory#createResourceAdapter implementation method. |
+
| 3 | +(Optional) You can specify optional activation spec configuration ResourceAdapterFactory#createActivationSpec implementation method. |
+
You can configure more than one ResourceAdapter instance in your application.
+Just name the resource adapter in the configuration:
quarkus.ironjacamar.main.ra.kind=artemis (1)
+quarkus.ironjacamar.other.ra.kind=artemisTo reference in the code, you must use the @io.smallrye.common.annotation.Identifier annotation:
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+import io.smallrye.common.annotation.Identifier;
+
+import jakarta.inject.Inject;
+
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.Message;
+import jakarta.jms.MessageListener;
+
+@ResourceEndpoint(activationSpecConfigKey="myqueue")
+@Identifier("other") (1)
+public class MyResourceEndpoint implements MessageListener {
+
+ @Inject
+ @Identifier("main")
+ ConnectionFactory connectionFactory; (2)
+
+ @Override
+ public void onMessage(Message message) {
+ //...
+ }
+}| 1 | +This MessageListener will be activated by the other resource adapter configured above. |
+
| 2 | +This ConnectionFactory will be the one configured in the main resource adapter. |
+
For more details about Quarkus IronJacamar Configuration, please refer to the documents.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Description +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Url +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Protocol +
+
+Environment variable: |
+string |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Url +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Protocol +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Description +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable AysncApi-Scanning +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Version of the WebComponent to be used in html-view to be found at [HOST]/asyncapi.html +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Full qualified name of the implementing AsyncApiFilter +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AsyncApi specification version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Default ContentType +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Title +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-description +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Email +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Contact-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+License-Name +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+License-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Url +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Protocol +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Description +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable AysncApi-Scanning +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Version of the WebComponent to be used in html-view to be found at [HOST]/asyncapi.html +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Full qualified name of the implementing AsyncApiFilter +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AsyncApi specification version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Default ContentType +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Title +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-description +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Email +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Contact-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+License-Name +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+License-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Url +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Protocol +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Description +
+
+Environment variable: |
+string |
++ |
There are two extensions:
+The AsyncApi-Extension scans a given asyncapi-file +and provides the infos found there as Microprofile-configuration (Kafka-topics, server-url, etc.). +So it can be used by someone who has already an existing AsyncApi-Definition and wants to create a service according to it.
+The AsyncApi-Scanner-Extension follows a "code first" approach. +An annotation-scanner scans the existing code, combines it with the given mp-config and creates an AsyncApi-description with this infos.
+You can find documentation for each of them in the navigation on the left.
+| + + | ++Describe what the extension does here. + | +
If you want to use this extension, you need to add the io.quarkiverse.asyncapi:quarkus-asyncapi extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.asyncapi</groupId>
+ <artifactId>quarkus-asyncapi</artifactId>
+ <version>0.3.0</version>
+</dependency>This extension creates an AsyncApi-document, describing data your server publishes/subscribes to/from Kafka-topics.
+It does this by
+scanning for annotations @Channel, @Outgoing and @Incoming in your project,
reading topics and descriptions from microprofile-configuration and
+reading data from running kafka
+The result can be viewed as html or svg or downloaded as yaml, json or plant-uml (localhost://[quarkus.http.root-path]/asyncapi.[html|svg|yaml|json|puml]).
+If you want to use this extension, you need to add the io.quarkiverse.asyncapi:quarkus-asyncapi extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.asyncapi</groupId>
+ <artifactId>quarkus-asyncapi-scanner</artifactId>
+ <version>0.3.0</version>
+</dependency>| + + | ++For more information about the extension configuration please refer to the Configuration Reference. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable AysncApi-Scanning +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Version of the WebComponent to be used in html-view to be found at [HOST]/asyncapi.html +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Full qualified name of the implementing AsyncApiFilter +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AsyncApi specification version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Default ContentType +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Title +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-version +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Project-description +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Contact-Email +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Contact-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+License-Name +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+License-URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Url +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Protocol +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Description +
+
+Environment variable: |
+string |
++ |
First thing first.
+For this sample to work, you need to have an Azure account as well as Azure CLI installed.
+The Azure CLI is available to install in Windows, macOS and Linux environments.
+Checkout the installation guide.
+Then, you need an Azure subscription and log into it by using the az login command.
+You can run az version to find the version and az upgrade to upgrade to the latest version.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The endpoint of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The id of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The secret of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The label filter of the app configuration. Use comma as separator for multiple label names +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start an azurite instance when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the Dev services will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the azurite instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Azure Storage Blob starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared azurite instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The connection string of Azure Storage Account. +
+
+Environment variable: |
+string |
+required |
+
Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.
+
Quarkus Azure Services ExtensionsQuarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.
+Azure App Configuration is a fast, scalable parameter storage for app configuration.
+This extension allows to inject a io.smallrye.config.SmallRyeConfig object inside your Quarkus application so you can access the app configuration stored in Azure.
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.azureservices</groupId>
+ <artifactId>quarkus-azure-app-configuration</artifactId>
+ <version>1.0.2</version>
+</dependency>Once you have added the extension to your project, follow the next steps, so you can inject io.smallrye.config.SmallRyeConfig object in your application to store and read blobs.
First thing first.
+For this sample to work, you need to have an Azure account as well as Azure CLI installed.
+The Azure CLI is available to install in Windows, macOS and Linux environments.
+Checkout the installation guide.
+Then, you need an Azure subscription and log into it by using the az login command.
+You can run az version to find the version and az upgrade to upgrade to the latest version.
Create an Azure resource group with the az group create command. +A resource group is a logical container into which Azure resources are deployed and managed.
+az group create \
+ --name rg-quarkus-azure-app-configuration \
+ --location eastusCreate an Azure App Configuration store with the following command:
+az appconfig create \
+ --name appcs-quarkus-azure-app-configuration \
+ --resource-group rg-quarkus-azure-app-configuration \
+ --location eastusThen create some key-value properties with the following commands:
+az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyOne --value "Value 1"
+az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyTwo --value "Value 2"You can list the key-value properties with the following command:
+az appconfig kv list --name appcs-quarkus-azure-app-configurationIf you log into the Azure portal, you can see the resource group and the key-value you created.
+
+As you can see below in the Configuration Reference section, this extension has several configuration options. +To be able to connect to the Azure App Configuration that we’ve just created, you must get the URL of the endpoing, it’s id and secret. +For that, execute the following Azure CLI command:
+az appconfig credential list --name appcs-quarkus-azure-app-configurationYou’ll get the following output:
+{
+ "connectionString": "Endpoint=https://appcs-quarkus-azure-app-configuration.azconfig.io;Id=xxxxxx;Secret=xxxxxx",
+ "id": "xxxxxx",
+ "name": "Primary",
+ "readOnly": false,
+ "value": "xxxxxx"
+}Then, in the application.properties file, add the following property according to the output of the previous command:
quarkus.azure.app.configuration.endpoint=https://appcs-quarkus-azure-app-configuration.azconfig.io
+quarkus.azure.app.configuration.id=xxxxxx
+quarkus.azure.app.configuration.secret=xxxxxxNow that your Azure environment is ready and that you have configured the extension, you can inject the SmallRyeConfig object in your application, so you can interact with Azure App Configuration.
@Path("/config")
+@Produces(MediaType.APPLICATION_JSON)
+public class ConfigResource {
+
+ @Inject
+ SmallRyeConfig config;
+
+ @GET
+ @Path("/{name}")
+ public Response configValue(@PathParam("name") final String name) {
+ return Response.ok(config.getConfigValue(name)).build();
+ }
+}To execute this sample you can run the following cURL commands:
+curl -X GET localhost:8080/config/myKeyOne
curl -X GET localhost:8080/config/myKeyTwo
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The endpoint of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The id of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The secret of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The label filter of the app configuration. Use comma as separator for multiple label names +
+
+Environment variable: |
+string |
++ |
Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.
+Azure Blob Storage is a massively scalable and secure object storage for cloud-native workloads, archives, data lakes, high-performance computing, and machine learning.
+This extension allows you to store and retrieve blobs from Azure Blob Storage by injecting a com.azure.storage.blob.BlobServiceClient object inside your Quarkus application.
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.azureservices</groupId>
+ <artifactId>quarkus-azure-storage-blob</artifactId>
+ <version>1.0.2</version>
+</dependency>Once you have added the extension to your project, follow the next steps, so you can inject com.azure.storage.blob.BlobServiceClient object in your application to store and read blobs.
First thing first.
+For this sample to work, you need to have an Azure account as well as Azure CLI installed.
+The Azure CLI is available to install in Windows, macOS and Linux environments.
+Checkout the installation guide.
+Then, you need an Azure subscription and log into it by using the az login command.
+You can run az version to find the version and az upgrade to upgrade to the latest version.
Create an Azure resource group with the az group create command. +A resource group is a logical container into which Azure resources are deployed and managed.
+az group create \
+ --name rg-quarkus-azure-storage-blob \
+ --location eastusCreate a general-purpose storage account with the following command:
+az storage account create \
+ --name stquarkusazurestorageblo \
+ --resource-group rg-quarkus-azure-storage-blob \
+ --location eastus \
+ --sku Standard_ZRS \
+ --encryption-services blobBlobs are always uploaded into a container. +You can organize groups of blobs in containers similar to the way you organize your files on your computer in folders. +The following command uses your Azure AD account to authorize the operation to create the container. +Before you create the container, assign the Storage Blob Data Contributor role to yourself. +Even if you are the account owner, you need explicit permissions to perform data operations against the storage account. +For that, get your subscription id with:
+az account show \
+ --query idThen, assign the role to yourself with (change <subscription> with your subscription id):
az ad signed-in-user show --query id -o tsv | az role assignment create \
+ --role "Storage Blob Data Contributor" \
+ --assignee @- \
+ --scope "/subscriptions/<subscription>/resourceGroups/rg-quarkus-azure-storage-blob/providers/Microsoft.Storage/storageAccounts/stquarkusazurestorageblo"az storage container create \
+ --account-name stquarkusazurestorageblo \
+ --name container-quarkus-azure-storage-blob \
+ --auth-mode loginIf you log into the Azure portal, you can see the resource group and the storage account you created.
+
+As you can see below in the Configuration Reference section, this extension has several configuration options.
+But one of them is mandatory, and that is the quarkus.azure.storage.blob.connection-string.
+To get the connection string, execute the following Azure CLI command:
az storage account show-connection-string \
+ --resource-group rg-quarkus-azure-storage-blob \
+ --name stquarkusazurestorageblo \
+ --output tsvThen, in the application.properties file, add the following property:
quarkus.azure.storage.blob.connection-string=DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName=stquarkusazurestorageblo;AccountKey=xxxxxxx==;BlobEndpoint=https://stquarkusazurestorageblo.blob.core.windows.net/;FileEndpoint=https://stquarkusazurestorageblo.file.core.windows.net/;QueueEndpoint=https://stquarkusazurestorageblo.queue.core.windows.net/;TableEndpoint=https://stquarkusazurestorageblo.table.core.windows.net/Now that your Azure environment is ready and that you have configured the extension, you can inject the com.azure.storage.blob.BlobServiceClient object in your application, so you can interact with Azure Blob Storage.
The uploadBlob method first gets the container that we’ve created (`container-quarkus-azure-storage-blob), sets some text to a text file, and then uploads the text to the container.
+The `downloadBlob method downloads the text file from the container and prints the text to the console.
To execute this sample you can run the following cURL commands:
+curl -X POST localhost:8080/quarkus-azure-storage-blob
curl localhost:8080/quarkus-azure-storage-blob
@Path("/quarkus-azure-storage-blob")
+@ApplicationScoped
+public class StorageBlobResource {
+
+ @Inject
+ BlobServiceClient blobServiceClient;
+
+ @POST
+ public Response uploadBlob() {
+ BlobContainerClient blobContainerClient = blobServiceClient
+ .createBlobContainerIfNotExists("container-quarkus-azure-storage-blob");
+ BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
+ blobClient.upload(BinaryData.fromString("Hello quarkus-azure-storage-blob at " + LocalDateTime.now()), true);
+
+ return Response.status(CREATED).build();
+ }
+
+ @GET
+ public String downloadBlob() {
+ BlobContainerClient blobContainerClient = blobServiceClient
+ .createBlobContainerIfNotExists("container-quarkus-azure-storage-blob");
+ BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
+
+ return blobClient.downloadContent().toString();
+ }
+}You can go back to the Azure portal and see the container and the blob that you’ve created.
+
+In case you plan to use BlobServiceClient (that provides all other clients for interacting with Azure BlobStore), note that it cannot be used within the reactive code as it blocks the event loop due to the fact that BlobServiceClient is a wrapper around the BlobServiceAsyncClient and it uses blocking calls such as blockingGet.
Using it in reactive code such as RestEasy Reactive or Reactive Messaging will cause indefinite hang of the application that prevents it from further functioning or shutdown.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start an azurite instance when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the Dev services will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the azurite instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Azure Storage Blob starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared azurite instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The connection string of Azure Storage Account. +
+
+Environment variable: |
+string |
+required |
+
Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.
+Azure App Configuration is a fast, scalable parameter storage for app configuration.
+This extension allows to inject a io.smallrye.config.SmallRyeConfig object inside your Quarkus application so you can access the app configuration stored in Azure.
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.azureservices</groupId>
+ <artifactId>quarkus-azure-app-configuration</artifactId>
+ <version>1.0.2</version>
+</dependency>Once you have added the extension to your project, follow the next steps, so you can inject io.smallrye.config.SmallRyeConfig object in your application to store and read blobs.
First thing first.
+For this sample to work, you need to have an Azure account as well as Azure CLI installed.
+The Azure CLI is available to install in Windows, macOS and Linux environments.
+Checkout the installation guide.
+Then, you need an Azure subscription and log into it by using the az login command.
+You can run az version to find the version and az upgrade to upgrade to the latest version.
Create an Azure resource group with the az group create command. +A resource group is a logical container into which Azure resources are deployed and managed.
+az group create \
+ --name rg-quarkus-azure-app-configuration \
+ --location eastusCreate an Azure App Configuration store with the following command:
+az appconfig create \
+ --name appcs-quarkus-azure-app-configuration \
+ --resource-group rg-quarkus-azure-app-configuration \
+ --location eastusThen create some key-value properties with the following commands:
+az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyOne --value "Value 1"
+az appconfig kv set --name appcs-quarkus-azure-app-configuration --yes --key myKeyTwo --value "Value 2"You can list the key-value properties with the following command:
+az appconfig kv list --name appcs-quarkus-azure-app-configurationIf you log into the Azure portal, you can see the resource group and the key-value you created.
+
+As you can see below in the Configuration Reference section, this extension has several configuration options. +To be able to connect to the Azure App Configuration that we’ve just created, you must get the URL of the endpoing, it’s id and secret. +For that, execute the following Azure CLI command:
+az appconfig credential list --name appcs-quarkus-azure-app-configurationYou’ll get the following output:
+{
+ "connectionString": "Endpoint=https://appcs-quarkus-azure-app-configuration.azconfig.io;Id=xxxxxx;Secret=xxxxxx",
+ "id": "xxxxxx",
+ "name": "Primary",
+ "readOnly": false,
+ "value": "xxxxxx"
+}Then, in the application.properties file, add the following property according to the output of the previous command:
quarkus.azure.app.configuration.endpoint=https://appcs-quarkus-azure-app-configuration.azconfig.io
+quarkus.azure.app.configuration.id=xxxxxx
+quarkus.azure.app.configuration.secret=xxxxxxNow that your Azure environment is ready and that you have configured the extension, you can inject the SmallRyeConfig object in your application, so you can interact with Azure App Configuration.
@Path("/config")
+@Produces(MediaType.APPLICATION_JSON)
+public class ConfigResource {
+
+ @Inject
+ SmallRyeConfig config;
+
+ @GET
+ @Path("/{name}")
+ public Response configValue(@PathParam("name") final String name) {
+ return Response.ok(config.getConfigValue(name)).build();
+ }
+}To execute this sample you can run the following cURL commands:
+curl -X GET localhost:8080/config/myKeyOne
curl -X GET localhost:8080/config/myKeyTwo
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The endpoint of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The id of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The secret of the app configuration +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The label filter of the app configuration. Use comma as separator for multiple label names +
+
+Environment variable: |
+string |
++ |
Quarkus Azure Services Extensions are developed and supported by Microsoft as part of their commitment to Open Standard Enterprise Java. For more information, see Jakarta EE on Azure.
+Azure Blob Storage is a massively scalable and secure object storage for cloud-native workloads, archives, data lakes, high-performance computing, and machine learning.
+This extension allows you to store and retrieve blobs from Azure Blob Storage by injecting a com.azure.storage.blob.BlobServiceClient object inside your Quarkus application.
If you want to use this extension, you need to add the io.quarkiverse.azureservices:quarkus-azure-services extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.azureservices</groupId>
+ <artifactId>quarkus-azure-storage-blob</artifactId>
+ <version>1.0.2</version>
+</dependency>Once you have added the extension to your project, follow the next steps, so you can inject com.azure.storage.blob.BlobServiceClient object in your application to store and read blobs.
First thing first.
+For this sample to work, you need to have an Azure account as well as Azure CLI installed.
+The Azure CLI is available to install in Windows, macOS and Linux environments.
+Checkout the installation guide.
+Then, you need an Azure subscription and log into it by using the az login command.
+You can run az version to find the version and az upgrade to upgrade to the latest version.
Create an Azure resource group with the az group create command. +A resource group is a logical container into which Azure resources are deployed and managed.
+az group create \
+ --name rg-quarkus-azure-storage-blob \
+ --location eastusCreate a general-purpose storage account with the following command:
+az storage account create \
+ --name stquarkusazurestorageblo \
+ --resource-group rg-quarkus-azure-storage-blob \
+ --location eastus \
+ --sku Standard_ZRS \
+ --encryption-services blobBlobs are always uploaded into a container. +You can organize groups of blobs in containers similar to the way you organize your files on your computer in folders. +The following command uses your Azure AD account to authorize the operation to create the container. +Before you create the container, assign the Storage Blob Data Contributor role to yourself. +Even if you are the account owner, you need explicit permissions to perform data operations against the storage account. +For that, get your subscription id with:
+az account show \
+ --query idThen, assign the role to yourself with (change <subscription> with your subscription id):
az ad signed-in-user show --query id -o tsv | az role assignment create \
+ --role "Storage Blob Data Contributor" \
+ --assignee @- \
+ --scope "/subscriptions/<subscription>/resourceGroups/rg-quarkus-azure-storage-blob/providers/Microsoft.Storage/storageAccounts/stquarkusazurestorageblo"az storage container create \
+ --account-name stquarkusazurestorageblo \
+ --name container-quarkus-azure-storage-blob \
+ --auth-mode loginIf you log into the Azure portal, you can see the resource group and the storage account you created.
+
+As you can see below in the Configuration Reference section, this extension has several configuration options.
+But one of them is mandatory, and that is the quarkus.azure.storage.blob.connection-string.
+To get the connection string, execute the following Azure CLI command:
az storage account show-connection-string \
+ --resource-group rg-quarkus-azure-storage-blob \
+ --name stquarkusazurestorageblo \
+ --output tsvThen, in the application.properties file, add the following property:
quarkus.azure.storage.blob.connection-string=DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName=stquarkusazurestorageblo;AccountKey=xxxxxxx==;BlobEndpoint=https://stquarkusazurestorageblo.blob.core.windows.net/;FileEndpoint=https://stquarkusazurestorageblo.file.core.windows.net/;QueueEndpoint=https://stquarkusazurestorageblo.queue.core.windows.net/;TableEndpoint=https://stquarkusazurestorageblo.table.core.windows.net/Now that your Azure environment is ready and that you have configured the extension, you can inject the com.azure.storage.blob.BlobServiceClient object in your application, so you can interact with Azure Blob Storage.
The uploadBlob method first gets the container that we’ve created (`container-quarkus-azure-storage-blob), sets some text to a text file, and then uploads the text to the container.
+The `downloadBlob method downloads the text file from the container and prints the text to the console.
To execute this sample you can run the following cURL commands:
+curl -X POST localhost:8080/quarkus-azure-storage-blob
curl localhost:8080/quarkus-azure-storage-blob
@Path("/quarkus-azure-storage-blob")
+@ApplicationScoped
+public class StorageBlobResource {
+
+ @Inject
+ BlobServiceClient blobServiceClient;
+
+ @POST
+ public Response uploadBlob() {
+ BlobContainerClient blobContainerClient = blobServiceClient
+ .createBlobContainerIfNotExists("container-quarkus-azure-storage-blob");
+ BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
+ blobClient.upload(BinaryData.fromString("Hello quarkus-azure-storage-blob at " + LocalDateTime.now()), true);
+
+ return Response.status(CREATED).build();
+ }
+
+ @GET
+ public String downloadBlob() {
+ BlobContainerClient blobContainerClient = blobServiceClient
+ .createBlobContainerIfNotExists("container-quarkus-azure-storage-blob");
+ BlobClient blobClient = blobContainerClient.getBlobClient("quarkus-azure-storage-blob.txt");
+
+ return blobClient.downloadContent().toString();
+ }
+}You can go back to the Azure portal and see the container and the blob that you’ve created.
+
+In case you plan to use BlobServiceClient (that provides all other clients for interacting with Azure BlobStore), note that it cannot be used within the reactive code as it blocks the event loop due to the fact that BlobServiceClient is a wrapper around the BlobServiceAsyncClient and it uses blocking calls such as blockingGet.
Using it in reactive code such as RestEasy Reactive or Reactive Messaging will cause indefinite hang of the application that prevents it from further functioning or shutdown.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start an azurite instance when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the Dev services will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the azurite instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Azure Storage Blob starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared azurite instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The connection string of Azure Storage Account. +
+
+Environment variable: |
+string |
+required |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+rate limiter will be completely disabled if false +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Maximum number of entries in the underlying cache +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Duration during which the bucket is kept after last refill if untouched +
+
+Environment variable: |
+Duration |
+
|
+
+
+
+
+
+
+Identity resolver allow to segment the population. Each resolved identity key will have its own quota. this must be a valid CDI bean implementing IdentityResolver. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+limits enforced for this bucket +
+
+Environment variable: |
+list of Limit |
+required |
+
+
+
+
+
+
+If true, permitted uses are shared for all methods using the same bucket id. If false, each method has its own quota. +
+
+Environment variable: |
+boolean |
+
|
+
Bucket4J is a Java rate-limiting library based on the token-bucket algorithm. Bucket4j is a thread-safe library that can be used in either a standalone JVM application, or a clustered environment. It also supports in-memory or distributed caching via the JCache (JSR107) specification. +This extension allow you to control the request rate sent to your application by using a dead simple API.
+If you want to use this extension, you need to add the io.quarkiverse.bucket4j:quarkus-bucket4j extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.bucket4j</groupId>
+ <artifactId>quarkus-bucket4j</artifactId>
+ <version>1.0.3</version>
+</dependency>Annotate the method that need to be throttled with @RateLimited
+@ApplicationScoped
+public static class RateLimitedMethods {
+
+ @RateLimited(bucket = "group1")
+ public String limited() {
+ return "LIMITED";
+ }
+
+}You can also annotate a class, in that case all methods in the class are throttled
+@ApplicationScoped
+@RateLimited(bucket = "group1")
+public static class RateLimitedMethods {
+
+ public String limited() {
+ return "LIMITED";
+ }
+
+}And add a limit group using the same bucket id in the configuration:
+# burst protection
+quarkus.rate-limiter.buckets.group1.limits[0].permitted-uses: 10
+quarkus.rate-limiter.buckets.group1.limits[0].period: 1S
+# fair use
+quarkus.rate-limiter.buckets.group1.limits[1].permitted-uses: 100
+quarkus.rate-limiter.buckets.group1.limits[1].period: 5Mor with yaml:
+quarkus:
+ rate-limiter:
+ buckets:
+ group1:
+ limits:
+ - permitted-uses: 10
+ period: 1S
+ - permitted-uses: 100
+ period: 5MThe bucket can contain multiple limits that will all be enforced.
+By default, if multiple methods share the same bucket id, each method has its own quota. +You can change this behaviour by enabling the shared option in the configuration.
+# burst protection
+quarkus.rate-limiter.buckets.group1.shared: true
+quarkus.rate-limiter.buckets.group1.limits[0].permitted-uses: 10
+quarkus.rate-limiter.buckets.group1.limits[0].period: 1SIf you want to perform the throttling per user, simply specify an IdentityKeyResolver either in the bucket config or in the RateLimited annotation. +If a value is specified in the annotation, it will take precedence over the config. +The default one is the ConstantResolver, which will cause the segmentation to be disabled.
+@ApplicationScoped
+public static class RateLimitedMethods {
+
+ @RateLimited(bucket = "group1", identityResolver = IpResolver.class)
+ public String limitedByIp() {
+ return "LIMITED";
+ }
+}IpResolver is provided out of the box. if you want a more complex segmentation, you can implement your own resolver. +A custom resolver must be a valid CDI Bean.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+rate limiter will be completely disabled if false +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Maximum number of entries in the underlying cache +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Duration during which the bucket is kept after last refill if untouched +
+
+Environment variable: |
+Duration |
+
|
+
+
+
+
+
+
+Identity resolver allow to segment the population. Each resolved identity key will have its own quota. this must be a valid CDI bean implementing IdentityResolver. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+limits enforced for this bucket +
+
+Environment variable: |
+list of Limit |
+required |
+
+
+
+
+
+
+If true, permitted uses are shared for all methods using the same bucket id. If false, each method has its own quota. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If enable/disable the Cert-Manager extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the certificate resource to be generated. If not provided, it will use the default name for the application resources. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+SecretName is the name of the secret resource that will be automatically created and managed by this Certificate resource. It will be populated with a private key and certificate, signed by the denoted issuer. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+CommonName is a common name to be used on the Certificate. The CommonName should have a length of 64 characters or fewer to avoid generating invalid CSRs. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The lifetime of the Certificate. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How long before the currently issued certificate’s expiry cert-manager should renew the certificate. The default is 2⁄3 of the issued certificate’s duration. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The list of Subject Alternative Names. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of IP address subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of URI subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of email subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If true, it will mark this Certificate as valid for certificate signing. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The set of x509 usages that are requested for the certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
The reference to the issuer for this certificate +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The kind of the resource being referred to. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The group of the resource being referred to. +
+
+Environment variable: |
+string |
++ |
The CA issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the secret used to sign Certificates issued by this Issuer. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which the revocation of this certificate can be checked. +
+
+Environment variable: |
+list of string |
++ |
The Vault issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The connection address for the Vault server, e.g: “https://vault.example.com:8200”. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The mount path of the Vault PKI backend’s sign endpoint, e.g: “my_pki_mount/sign/my-role-name”. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The PEM-encoded CA bundle (base64-encoded) used to validate Vault server certificate. +
+
+Environment variable: |
+string |
+required |
+
The reference where to retrieve the Vault token +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The Vault authentication using App Role auth mechanism +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The App Role authentication backend is mounted in Vault, e.g: “approle” +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The App Role authentication backend when setting up the authentication backend in Vault. +
+
+Environment variable: |
+string |
+required |
+
The reference to a key in a Secret that contains the App Role secret used to authenticate with Vault +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The Vault authentication using Kubernetes service account +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The mount path to use when authenticating with Vault. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The required Secret field containing a Kubernetes ServiceAccount JWT used for authenticating with Vault. +
+
+Environment variable: |
+string |
+required |
+
The reference to a key in a Secret that contains the App Role secret used to authenticate with Vault +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The self-signed issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+If the self-signed issuer should be generated. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which the revocation of this certificate can be checked. +
+
+Environment variable: |
+list of string |
++ |
Full X509 name specification (https://golang +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The organizations to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The countries to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The organizational Units to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The cities to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The State/Provinces to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The street addresses to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The postal codes to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The serial number to be used on the Certificate. +
+
+Environment variable: |
+string |
++ |
The Keystores generation configuration +This configuration section is optional |
+Type |
+Default |
+
JKS configures options for storing a JKS keystore in the spec +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+Create enables keystore creation for the Certificate. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
PKCS12 configures options for storing a PKCS12 keystore in the spec +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+Create enables keystore creation for the Certificate. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
#quarkus-certificate_quarkus.certificate.private-key +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+RotationPolicy controls how private keys should be regenerated when a re-issuance is being processed. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+int |
+
|
+
The Quarkus Cert-Manager extension supports generating an X.509 certificate with the help of the Certificate and Issuer CRD resources handled by the Cert-Manager. When these CRD resources are deployed on the cluster, the Cert-Manager will process them to populate a Secret containing for example a: CA certificate, private key, server certificate, or java keystores, etc.
+Under the hood, this extension uses Dekorate to generate all the Cert-Manager manifests at build time.
+Before getting started, make sure you’re using the right Quarkus Helm version that is compatible with the Quarkus version you’re using in your project. See the following table to see the compatibility among versions:
+| Quarkus Cert-Manager Version | +Quarkus Version | +
|---|---|
1.0.1 |
+Quarkus 3+ |
+
1.0.0 |
+Quarkus 3+ |
+
0.0.2 |
+Quarkus 2.12+ |
+
0.0.1 |
+Quarkus 2.12+ |
+
In this example, we’ll create a Quarkus application with the Quarkus Cert-Manager and the Quarkus Kubernetes extensions by running the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=certmanager-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy-reactive,kubernetes,certmanager"
+cd certmanager-quickstartIf you already have your Quarkus project configured, you can add the certmanager extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="certmanager"This command will add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.certmanager</groupId>
+ <artifactId>quarkus-certmanager</artifactId>
+ <version>1.0.2</version>
+</dependency>Once we add the Quarkus Cert-Manager extension to your project, you can now generate the resources by running the following Maven command:
+./mvnw clean packageAnd next, we need to provide the certificate configuration. The minimal information that the extension needs is:
+* secretName: the name of the Kubernetes Secret resource that will include the Cert-Manager generated files.
+* the Issuer that represents the certificate authority (CA). See all the supported options in the Issuer section.
For all the configuration options, please go to the Configuration guide.
+The minimal configuration can be provided using the properties file and the following keys:
+quarkus.certificate.secret-name=tls-secret
+# The selfSigned issuer:
+quarkus.certificate.self-signed.enabled=trueThis configuration will generate up to two resources under the target/kubernetes/kubernetes.yml file that should look like this:
apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+ name: kubernetes-example
+spec:
+ selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+ name: kubernetes-example
+spec:
+ encodeUsagesInRequest: false
+ isCA: false
+ issuerRef:
+ name: kubernetes-example
+ secretName: tls-secretThe Quarkus Cert-Manager extension will add, part of the Deployment, a volume mounted from the secret that contains the Cert-Manager generated files to allow the application to access them and to configure the HTTPS/TLS endpoint:
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: kubernetes-example
+spec:
+ replicas: 1
+ template:
+ spec:
+ containers:
+ - name: kubernetes-example
+ volumeMounts:
+ - mountPath: /etc/certs
+ name: volume-certs
+ readOnly: true
+ volumes:
+ - name: volume-certs
+ secret:
+ optional: false
+ secretName: tls-secretMoreover, the Quarkus Cert-Manager extension will also autoconfigure the application to accept SSL connections. By default, it will autoconfigure only the Ingress/Route resource if exposed, otherwise, it will enable the HTTPS/TLS configuration for the internal communications of the application. This configuration can be controlled using the property quarkus.certificate.autoconfigure which values:
(Default) AUTOMATIC: It will secure Ingress/Route resources if exposed, otherwise the HTTP endpoints.
+NONE: It won’t autoconfigure anything.
+ALL: It will secure the HTTP endpoints and also the Ingress/Route resources if exposed.
+HTTPS_ONLY: It will secure only the HTTP endpoints.
+CLUSTER_ONLY: It will secure only the Ingress/Route resources. It will throw an exception if it was not exposed.
+For example, if you want to secure both the internal HTTPs connections and the ingress resource by setting the property quarkus.certificate.autoconfigure=ALL, it will update the Ingress resource as follows if the property quarkus.kubernetes.ingress.expose is true:
apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+ ...
+spec:
+ rules:
+ ...
+ tls:
+ - hosts:
+ - kubernetes-example.com
+ - localhost
+ secretName: tls-secretAnd it will also autoconfigure the HTTP SSL configuration part of the Deployment resource:
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ ...
+ name: quarkus-certmanager-integration-tests-certmanager-ssl
+spec:
+ replicas: 1
+ selector:
+ ...
+ template:
+ ...
+ spec:
+ containers:
+ - env:
+ - name: KUBERNETES_NAMESPACE
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.namespace
+ - name: QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE_TYPE
+ value: PKCS12
+ - name: QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ key: password
+ name: pkcs12-pass
+ - name: QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE
+ value: /etc/certs/keystore.p12When securing your resources, it’s important to validate that the requests are coming from known host names. For this purpose, we can use the dnsNames property which is part of the certificate configuration. For example, by adding the following quarkus.certificate.dns-names property (it’s a comma separated list of strings):
quarkus.certificate.dns-names=foo.bar.comThe certificate will only allow requests accessing the server host foo.bar.com. Remark: If the DNS Host name does not exist, then you will get an error.
Note that the applications in Kubernetes can be publicly exposed using Ingress resources, for example:
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+ name: kubernetes-example
+spec:
+ rules:
+ - host: foo.bar.com
+ http:
+ paths:
+ - pathType: Prefix
+ path: "/"
+ backend:
+ service:
+ name: kubernetes-example
+ port:
+ name: http
+ tls:
+ - hosts:
+ - foo.bar.com
+ secretName: tls-secret # < cert-manager will store the created certificate in this secret.The Issuer is a Kubernetes resource that represents a certificate issuing authority that can generate signed certificates by honoring certificate signing requests. All cert-manager certificates require a referenced issuer to attempt to honor the request.
The supported issuers of this extension are SelfSigned, CA, Vault, and IssuerRef.
+| + + | +
+
+
+Only one issuer must be set between |
+
Using the SelfSigned issuer, the certificate will sign itself using the given private key. +To use the SelfSigned issuer, you need to add the following key property:
+quarkus.certificate.self-signed.enabled=trueUsing the CA issuer, the certificate and private key are stored inside the cluster as a Kubernetes Secret and will be used to sign incoming certificate requests. +To use the CA issuer, you need to add the following key properties:
+quarkus.certificate.ca.secret-name=ca-key-pairWhen this certificate is installed in the cluster, Cert-Manager will issue the certificate and generate the CA secret resource ca-key-pair which the following content:
apiVersion: v1
+kind: Secret
+metadata:
+ name: ca-key-pair
+data:
+ tls.crt: <auto generated encrypted data>
+ tls.key: <auto generated encrypted data>Using the Vault issuer, the certificate will be issued by the certificate authority Vault. +To use the Vault issuer, you need the following key properties:
+quarkus.certificate.vault.server=https://vault.example.com:8200
+quarkus.certificate.vault.path=my_pki_mount/sign/my-role-name
+# Any of the auth mechanisms to login into Vault:
+## 1.- Via token secret resource reference:
+quarkus.certificate.vault.auth-token-secret-ref...
+## 2.- Via using Application Role:
+quarkus.certificate.vault.auth-app-role...
+## 3.- Via using Kubernetes service account:
+quarkus.certificate.vault.auth-kubernetes...To use a pre-existing issuer type that is separately installed in the cluster, you can use the issuerRef type. For example:
quarkus.certificate.issuer-ref.name=my-issuer
+quarkus.certificate.issuer-ref.kind=ClusterIssuerIn this example, we are using a ClusterIssuer resource that is part of the Cert-Manager API and that should have previously been installed in the cluster.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If enable/disable the Cert-Manager extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the certificate resource to be generated. If not provided, it will use the default name for the application resources. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+SecretName is the name of the secret resource that will be automatically created and managed by this Certificate resource. It will be populated with a private key and certificate, signed by the denoted issuer. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+CommonName is a common name to be used on the Certificate. The CommonName should have a length of 64 characters or fewer to avoid generating invalid CSRs. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The lifetime of the Certificate. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How long before the currently issued certificate’s expiry cert-manager should renew the certificate. The default is 2⁄3 of the issued certificate’s duration. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The list of Subject Alternative Names. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of IP address subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of URI subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The list of email subjectAltNames to be set on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If true, it will mark this Certificate as valid for certificate signing. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The set of x509 usages that are requested for the certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
The reference to the issuer for this certificate +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The kind of the resource being referred to. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The group of the resource being referred to. +
+
+Environment variable: |
+string |
++ |
The CA issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the secret used to sign Certificates issued by this Issuer. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which the revocation of this certificate can be checked. +
+
+Environment variable: |
+list of string |
++ |
The Vault issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The connection address for the Vault server, e.g: “https://vault.example.com:8200”. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The mount path of the Vault PKI backend’s sign endpoint, e.g: “my_pki_mount/sign/my-role-name”. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The PEM-encoded CA bundle (base64-encoded) used to validate Vault server certificate. +
+
+Environment variable: |
+string |
+required |
+
The reference where to retrieve the Vault token +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The Vault authentication using App Role auth mechanism +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The App Role authentication backend is mounted in Vault, e.g: “approle” +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The App Role authentication backend when setting up the authentication backend in Vault. +
+
+Environment variable: |
+string |
+required |
+
The reference to a key in a Secret that contains the App Role secret used to authenticate with Vault +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The Vault authentication using Kubernetes service account +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The mount path to use when authenticating with Vault. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The required Secret field containing a Kubernetes ServiceAccount JWT used for authenticating with Vault. +
+
+Environment variable: |
+string |
+required |
+
The reference to a key in a Secret that contains the App Role secret used to authenticate with Vault +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
The self-signed issuer configuration +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+If the self-signed issuer should be generated. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The CRL distribution points is an X.509 v3 certificate extension which identifies the location of the CRL from which the revocation of this certificate can be checked. +
+
+Environment variable: |
+list of string |
++ |
Full X509 name specification (https://golang +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The organizations to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The countries to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The organizational Units to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The cities to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The State/Provinces to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The street addresses to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The postal codes to be used on the Certificate. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The serial number to be used on the Certificate. +
+
+Environment variable: |
+string |
++ |
The Keystores generation configuration +This configuration section is optional |
+Type |
+Default |
+
JKS configures options for storing a JKS keystore in the spec +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+Create enables keystore creation for the Certificate. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
PKCS12 configures options for storing a PKCS12 keystore in the spec +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+Create enables keystore creation for the Certificate. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The name of the resource being referred to. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The key of the entry in the Secret resource’s data field to be used. +
+
+Environment variable: |
+string |
+required |
+
#quarkus-certificate_quarkus.certificate.private-key +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+RotationPolicy controls how private keys should be regenerated when a re-issuance is being processed. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Environment variable: |
+int |
+
|
+
This guide explains how your Quarkus application can read configuration properties at runtime from HashiCorp Consul.
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+We recommend that you follow the instructions in the next sections and create the application step by step.
+Consul is a versatile system which among other things, provides a distributed Key-Value store that is used in many architectures as a source of configuration for services.
+This Key-Value store is what the quarkus-config-consul extension interacts with in order to allow Quarkus applications to read runtime configuration properties from Consul.
There are various ways to start Consul that vary in complexity, but for the purposes of this guide, we elect to start a single Consul server with no persistence via Docker, like so:
+docker run --rm --name consul -p 8500:8500 -p 8501:8501 consul:1.7 agent -dev -ui -client=0.0.0.0 -bind=0.0.0.0 --https-port=8501Please consult the documentation to learn more about the various Consul installation options.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.2:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=config-consul-quickstart \
+ -DclassName="org.acme.consul.config.GreetingResource" \
+ -Dpath="/greeting" \
+ -Dextensions="config-consul"
+cd config-consul-quickstartThis command generates a Maven project with a REST endpoint and imports the config-consul extension.
If you already have your Quarkus project configured, you can add the config-consul extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="config-consul"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.config</groupId>
+ <artifactId>quarkus-config-consul</artifactId>
+ <version>2.3.1</version>
+</dependency>The Quarkus Maven plugin automatically generated a GreetingResource JAX-RS resource in the
+src/main/java/org/acme/consul/config/client/GreetingResource.java file that looks like:
package org.acme.consul.config.client;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+@Path("/greeting")
+public class GreetingResource {
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return "hello";
+ }
+}As we want to use configuration properties obtained from the Config Server, we will update the GreetingResource to inject the message property. The updated code will look like this:
package org.acme.consul.config.client;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+@Path("/greeting")
+public class GreetingResource {
+ @ConfigProperty(name = "greeting.message", defaultValue="Hello from default")
+ String message;
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return message;
+ }
+}Quarkus provides various configuration knobs under the quarkus.consul-config root. For the purposes of this guide, our Quarkus application is going to be configured in application.properties as follows:
# use the same name as the application name that was configured when standing up the Config Server
+quarkus.application.name=consul-test
+# enable retrieval of configuration from Consul - this is off by default
+quarkus.consul-config.enabled=true
+# this is a key in Consul's KV store that the Quarkus application will read and try to extract properties from
+quarkus.consul-config.properties-value-keys=config/${quarkus.application.name}For the previous application configuration to work, we need to add a config/consul-test key under Consul’s Key Value store. The value of this key will essentially be a properties "file" containing the application configuration.
+In this case we want to add the following data to the config/consul-test key:
greeting.message=Hello from ConsulWhen adding this configuration from the UI, Consul will automatically convert the data into the necessary base64 encoding. If you instead add the configuration via the Consul’s REST API, +make sure to first encode the previous data into base64.
+| + + | +
+In this use case we made the value of the key as a properties "file", because we used quarkus.consul-config.properties-value-keys in the application. The
+extension also provides the ability to use the raw values of keys when quarkus.consul-config.raw-value-keys is used. Furthermore, these two properties can be used
+simultaneously, while each one also supports setting multiple keys.
+ |
+
Run the application with: ./mvnw compile quarkus:dev.
+Open your browser to http://localhost:8080/greeting.
The result should be: Hello from Consul as it is the value obtained from the Consul Key Value store.
You can of course create a native image using the instructions of the +Building a native executable guide.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If set to true, the application will attempt to look up the configuration from Consul +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Consul agent host +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Whether or not to use HTTPS when communicating with the agent +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Consul token to be provided when authentication is enabled +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TrustStore to be used containing the SSL certificate used by Consul agent Can be either a classpath resource or a file system path +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Password of TrustStore to be used containing the SSL certificate used by Consul agent +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+KeyStore to be used containing the SSL certificate for authentication with Consul agent Can be either a classpath resource or a file system path +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Password of KeyStore to be used containing the SSL certificate for authentication with Consul agent +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to recover key from KeyStore for SSL client authentication with Consul agent If no value is provided, the key-store-password will be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+When using HTTPS and no keyStore has been specified, whether or not to trust all certificates +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Common prefix that all keys share when looking up the keys from Consul. The prefix is not included in the keys of the user configuration +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Keys whose value is a raw string. When this is used, the keys that end up in the user configuration are the keys specified her with '/' replaced by '.' +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Keys whose value represents a properties file. When this is used, the keys that end up in the user configuration are the keys of the properties file, not these keys +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If set to true, the application will not start if any of the configured config sources cannot be located +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If set to true, the application will attempt to look up the configuration from Consul +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Consul agent host +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Whether or not to use HTTPS when communicating with the agent +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Consul token to be provided when authentication is enabled +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+TrustStore to be used containing the SSL certificate used by Consul agent Can be either a classpath resource or a file system path +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Password of TrustStore to be used containing the SSL certificate used by Consul agent +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+KeyStore to be used containing the SSL certificate for authentication with Consul agent Can be either a classpath resource or a file system path +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+Password of KeyStore to be used containing the SSL certificate for authentication with Consul agent +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to recover key from KeyStore for SSL client authentication with Consul agent If no value is provided, the key-store-password will be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+When using HTTPS and no keyStore has been specified, whether or not to trust all certificates +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The amount of time to wait when initially establishing a connection before giving up and timing out. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The amount of time to wait for a read on a socket before an exception is thrown. +
+
+Specify
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Common prefix that all keys share when looking up the keys from Consul. The prefix is not included in the keys of the user configuration +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Keys whose value is a raw string. When this is used, the keys that end up in the user configuration are the keys specified her with '/' replaced by '.' +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Keys whose value represents a properties file. When this is used, the keys that end up in the user configuration are the keys of the properties file, not these keys +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If set to true, the application will not start if any of the configured config sources cannot be located +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If set to true, the application will attempt to look up the configuration from DB + |
+boolean |
+
|
+
+
+
+
+
+
+If set to true, the application will cache all looked up the configuration from DB in memory +If set to false, the application will always get the latest values from the DB + |
+boolean |
+
|
+
+
+
+
+
+
+Table name for configuration records + |
+string |
+
|
+
+
+
+
+
+
+Name of the column containing the key + |
+string |
+
|
+
+
+
+
+
+
+Name of the column containing the value + |
+string |
+
|
+
+
+
+
+
+
+The datasource username, if not defined the usename of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource password, if not defined the password of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource URL, if not defined the URL of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource driver, if not defined the driver of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The initial size of the pool. Usually you will want to set the initial size to match at least the minimal size, but this is not enforced so to allow for architectures which prefer a lazy initialization of the connections on boot, while being able to sustain a minimal pool size after boot. + |
+int |
+
|
+
+
+
+
+
+
+The int pool minimum size + |
+int |
+
|
+
+
+
+
+
+
+The datasource pool maximum size + |
+int |
+
|
+
+
+
+
+
+
+The timeout before cancelling the acquisition of a new connection + |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
This guide explains how your Quarkus application can read configuration properties using +Jasypt encryption.
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+We recommend that you follow the instructions in the next sections and create the application step by step.
+Jasypt is a java library which allows the developer to add basic encryption capabilities.
+Add the config-jasypt extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="config-jasypt"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.config</groupId>
+ <artifactId>quarkus-config-jasypt</artifactId>
+ <version>2.3.1</version>
+</dependency>| + + | ++The Jasypt Quarkus Extension is required to native mode. There is no difference in features to the +SmallRye Config Jasypt. + | +
A secret configuration may be expressed as ${jasypt::value}. The ${jasypt::…} SecretKeyHandler requires both
+smallrye.config.secret-handler.jasypt.password and smallrye.config.secret-handler.jasypt.algorithm configurations
+to state the password and the algorithm to be used by the Jasypt encryptor.
application.properties
+
+smallrye.config.secret-handler.jasypt.password=jasypt
+smallrye.config.secret-handler.jasypt.algorithm=PBEWithHMACSHA512AndAES_256
+
+my.secret=${jasypt::ENC(wqp8zDeiCQ5JaFvwDtoAcr2WMLdlD0rjwvo8Rh0thG5qyTQVGxwJjBIiW26y0dtU)}Jasypt encrypted values must be set with the handler expression as ${jasypt::ENC(value)}. Note
+that the encrypted value must be generated using the proper Jasypt encryptor with the same password and algorithm set
+in the configuration.
A possible encrypted value for 12345678 is ENC(wqp8zDeiCQ5JaFvwDtoAcr2WMLdlD0rjwvo8Rh0thG5qyTQVGxwJjBIiW26y0dtU)
Lookups to the configuration my.secret will automatically decrypt the value with Jasypt and
+provide the original 12345678 string.
| + + | +
+It is possible to generate the encrypted secret with the following JBang script:
+jbang https://raw.githubusercontent.com/smallrye/smallrye-config/main/documentation/src/main/docs/config/secret-handlers/jasypt.java -s=<secret> -p=<password>
+ |
+
This guide explains how your Quarkus application can read configuration properties from a database using JDBC
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+We recommend that you follow the instructions in the next sections and create the application step by step.
+A database table can be used as a Key-Value store as a source of configuration for services.
+This table is what the quarkus-config-jsbc extension interacts with in order to allow Quarkus applications to read configuration properties from.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.2:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=config-jdbc-quickstart \
+ -DclassName="org.acme.jdbc.config.GreetingResource" \
+ -Dpath="/greeting" \
+ -Dextensions="config-jdbc"
+cd config-jdbc-quickstartThis command generates a Maven project with a REST endpoint and imports the config-jdbc extension.
If you already have your Quarkus project configured, you can add the config-jdbc extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="config-jdbc"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.config</groupId>
+ <artifactId>quarkus-config-jdbc</artifactId>
+ <version>2.3.1</version>
+</dependency>The Quarkus Maven plugin automatically generated a GreetingResource JAX-RS resource in the
+src/main/java/org/acme/consul/config/client/GreetingResource.java file that looks like:
package org.acme.consul.config.client;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+@Path("/greeting")
+public class GreetingResource {
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return "hello";
+ }
+}As we want to use configuration properties obtained from the Config Server, we will update the GreetingResource to inject the message property. The updated code will look like this:
package org.acme.consul.config.client;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+@Path("/greeting")
+public class GreetingResource {
+ @ConfigProperty(name = "greeting.message", defaultValue="Hello from default")
+ String message;
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return message;
+ }
+}Quarkus provides various configuration knobs under the quarkus.config.source.jdbc root. For the purposes of this guide, our Quarkus application is going to be configured in application.properties as follows:
quarkus.config.source.jdbc.username=sa
+quarkus.config.source.jdbc.password=sa
+quarkus.config.source.jdbc.url=jdbc:h2:tcp://localhost/mem:testFor the previous application configuration to work, we need to have a table named configuration with two columns key and value with a record inserted into it
CREATE TABLE IF NOT EXISTS configuration (key varchar(255), value varchar(255));
+
+INSERT INTO configuration (key, value)
+VALUES ('greeting.message', 'Hello from DB');Run the application with: ./mvnw compile quarkus:dev.
+Open your browser to http://localhost:8080/greeting.
The result should be: Hello from DB as it is the value obtained from the database.
You can of course create a native image using the instructions of the +Building a native executable guide.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If set to true, the application will attempt to look up the configuration from DB + |
+boolean |
+
|
+
+
+
+
+
+
+If set to true, the application will cache all looked up the configuration from DB in memory +If set to false, the application will always get the latest values from the DB + |
+boolean |
+
|
+
+
+
+
+
+
+Table name for configuration records + |
+string |
+
|
+
+
+
+
+
+
+Name of the column containing the key + |
+string |
+
|
+
+
+
+
+
+
+Name of the column containing the value + |
+string |
+
|
+
+
+
+
+
+
+The datasource username, if not defined the usename of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource password, if not defined the password of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource URL, if not defined the URL of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The datasource driver, if not defined the driver of the default datasource is used + |
+string |
+value of |
+
+
+
+
+
+
+The initial size of the pool. Usually you will want to set the initial size to match at least the minimal size, but this is not enforced so to allow for architectures which prefer a lazy initialization of the connections on boot, while being able to sustain a minimal pool size after boot. + |
+int |
+
|
+
+
+
+
+
+
+The int pool minimum size + |
+int |
+
|
+
+
+
+
+
+
+The datasource pool maximum size + |
+int |
+
|
+
+
+
+
+
+
+The timeout before cancelling the acquisition of a new connection + |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
Integrates Couchbase into Quarkus.
+This extension is currently in alpha status. It supports:
+Dependency injecting a Couchbase Cluster.
Configuring the Cluster through application.properties. Currently a minimal set of configuration options is provided.
Graal/native-image, though so far it has been minimally tested with basic cases.
+Please try it out and provide feedback, ideas and bug reports on Github.
+Add it to your project:
+<dependency>
+ <groupId>com.couchbase</groupId>
+ <artifactId>quarkus-couchbase</artifactId>
+ <version>1.0.0-alpha.1</version>
+</dependency>(Note this will soon be updated to the new groupId of io.quarkiverse.couchbase, but it has not yet been published to Maven under this.)
Provide the Couchbase configuration in application.properties:
quarkus.couchbase.connection-string=localhost
+quarkus.couchbase.username=username
+quarkus.couchbase.password=passwordNow you can @Inject a Couchbase Cluster into your project:
@Path("/couchbase")
+public class TestCouchbaseResource {
+ @Inject
+ Cluster cluster;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ @Path("/test")
+ public String run() {
+ // Get a reference to a particular Couchbase bucket and its default collection
+ var bucket = cluster.bucket("travel-sample");
+ var collection = bucket.defaultCollection() ;
+
+ // Upsert a new document
+ collection.upsert("test", JsonObject.create().put("foo", "bar"));
+
+ // Fetch and print a document
+ var doc = bucket.defaultCollection().get("test");
+ System.out.println("Got doc " + doc.contentAsObject().toString());
+
+ // Perform a N1QL query
+ var queryResult = cluster.query("select * from `travel-sample` where url like 'http://marriot%' and country = 'United States';");
+
+ queryResult.rowsAsObject().forEach(row -> {
+ System.out.println(row.toString());
+ });
+
+ return "success!";
+ }
+}And test http://localhost:8080/couchbase/test.
+This extension allows you to use Cucumber to test your Quarkus application.
+If you want to use this extension, you need to add the io.quarkiverse.cucumber:quarkus-cucumber extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.cucumber</groupId>
+ <artifactId>quarkus-cucumber</artifactId>
+ <version>1.0.0</version>
+</dependency>To bootstrap Cucumber add the following class to your test suite:
+import io.quarkiverse.cucumber.CucumberQuarkusTest;
+
+public class MyTest extends CucumberQuarkusTest {
+
+}This will automatically bootstrap Cucumber, and discover any .feature files and step classes that provide glue code.
The test class can by run by any IDE with support for JUnit5.
+In IntelliJ it is possible to directly run feature files:
+
+You need to add the following main method to your test class:
import io.quarkiverse.cucumber.CucumberQuarkusTest;
+
+public class MyTest extends CucumberQuarkusTest {
+ public static void main(String[] args) {
+ runMain(MyTest.class, args);
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+The default path for CXF resources.
+⚠️ Note that the default value before 3.0.0 was
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files.
+There are 4 place holders, which can be used in the template:
+ -
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files.
+There are 4 place holders, which can be used in the template:
+ -
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The client service interface class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The service endpoint implementation class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The service endpoint WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The published service endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names or named CDI beans.
+Examples: quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature quarkus.cxf.endpoint."/fruit".features = #myCustomLoggingFeature In the second case, the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The client WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client interface class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint namespace +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The username for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names.
+Example: quarkus.cxf.endpoint.myClient.features = org.apache.cxf.ext.logging.LoggingFeature
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
This project aims at porting Apache CXF to Quarkus runtime +including full support for producing GraalVM native images.
+| + + | ++While Apache CXF implements wide range of standards and specifications, +CXF Extensions for Quarkus is currently focusing only on supporting the ones related to +Simple Object Access Protocol (SOAP) +and Java API for XML Web Services (JAX-WS). +Please refer to Reference to learn which parts of CXF are supported. + | +
The documentation is divided in two major parts:
+User guide - explains the typical usage of CXF Extensions for Quarkus
+Reference - the full list of supported specifications, use cases and configuration options
+Please feel free to start a discussion +or open an issue in the GitHub repository in case you need support. +The following general guidelines can be used to determine whether to start a discussion or open an issue.
+Bug reports
+Feature requests
+Q&A and general communication
+RFCs for new features
+Contributions and pull requests from the community are welcome!
+Stable • Since 0.14.0
+Allows logging HTTP headers and bodies of SOAP requests and responses for both CXF clients and services.
+Create a new project using quarkus-cxf-rt-features-logging on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-logging</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
This extension wraps the CXF org.apache.cxf:cxf-rt-features-logging artifact
+thus providing the org.apache.cxf.ext.logging.LoggingFeature class.
LoggingFeature instances can be configured per service or per client.
+You can either use a LoggingFeature instance with default settings
+or you can produce a custom LoggingFeature CDI bean.
LoggingFeature to a client or serviceYou have two options to do that:
+In application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeature
+# For a client:
+quarkus.cxf.client."myClient".features=org.apache.cxf.ext.logging.LoggingFeature| + + | ++There is an example in Your first SOAP Web service chapter of the User guide. + | +
or alternatively
+Use the @Features annotation of CXF:
@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}LoggingFeatureLoggingFeature offers some attributes that may be worth customizing in some situations.
E.g. if your payloads are complex, you may want to set prettyLogging to true to render them with an indentation.
+Or if your messages are big and you need to see them complete in the log, you may want to increase the limit.
| + + | +
+Check the CXF message logging page for all possible LoggingFeature attributes.
+ |
+
To achieve this, you can produce a custom LoggingFeature bean that is then picked by Quarkus CXF
+for clients and services where you specified *.features = org.apache.cxf.ext.logging.LoggingFeature:
import org.apache.cxf.ext.logging.LoggingFeature;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ LoggingFeature loggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ loggingFeature.setLimit(Integer.MAX_VALUE);
+ return loggingFeature;
+ }
+}LoggingFeaturesIn case you’d like to configure the LoggingFeatures for your individual services or clients differently,
+you can so that by defining multiple @Named LoggingFeature beans:
import org.apache.cxf.ext.logging.LoggingFeature;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ @Named("limitedLoggingFeature") // "limitedLoggingFeature" is redundant if the name of the method is the same
+ LoggingFeature limitedLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setLimit(Integer.MAX_VALUE);
+ return loggingFeature;
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named("prettyLoggingFeature")
+ LoggingFeature prettyLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ return loggingFeature;
+ }
+}and then refer to them by their names prefixed with # in application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features = #limitedLoggingFeature
+# For a client:
+quarkus.cxf.client."myClient".features = #prettyLoggingFeature| + + | ++Please note that named Feature beans are currently not supported for SOAP clients. + | +
🧪Experimental • Since 0.14.0
+Collect metrics using Micrometer.
+| + + | ++This extension is experimental, because there are no tests covering it. Contributions are welcome! + | +
Create a new project using quarkus-cxf-rt-features-metrics on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
The integration of CXF into Quarkus Micrometer ecosystem is implemented using CXF MicrometerMetricsProvider and io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature.
Simply add the following to your application.properties to start collecting metrics:
# Enable metrics for a service
+quarkus.cxf.endpoint."/fruit-service".features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature
+
+# Enable metrics for a client
+quarkus.cxf.client."fruit-client".features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature🧪Experimental • Since 1.1.0
+Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
+| + + | ++This extension is experimental, because there are no tests covering it. Contributions are welcome! + | +
Create a new project using quarkus-cxf-rt-transports-http-hc5 on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-transports-http-hc5</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Once the quarkus-cxf-rt-transports-http-hc5 dependency is available in the classpath,
+CXF will use HttpAsyncClient for asynchronous calls and will continue using HttpURLConnection for synchronous calls.
| + + | ++You can see more details about the CXF asynchronous client and how to tune it further in CXF documentation. + | +
Asynchronous client invocations require some additional methods in the service endpoint interface. +That code is not generated by default.
+To enable it, you need to create a JAX-WS binding file with enableAsyncMapping set to true:
<bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ wsdlLocation="AffectedWSDL"
+ xmlns="http://java.sun.com/xml/ns/jaxws">
+ <bindings node="AffectedNode">
+ <enableAsyncMapping>true</enableAsyncMapping>
+ </bindings>
+</bindings>This file should then be passed to wsdl2java +through its additional-params property:
+quarkus.cxf.java2ws.includes = HelloService.wsdl
+quarkus.cxf.java2ws.foo-params.additional-params = -b,src/main/resources/binding.xmlOnce the asynchronous stubs are available, it is possible to wrap a client call in io.smallrye.mutiny.Uni as shown below:
import jakarta.inject.Inject;
+import io.smallrye.mutiny.Uni;
+import io.quarkiverse.cxf.annotation.CXFClient;
+
+class Client {
+
+ @Inject @CXFClient
+ CalculatorService calculator;
+
+ public Uni add(int a, int b) {
+ return Uni.createFrom().future(() ->
+ (Future)calculatorSoap.addAsync(a, b, res -> {}));
+ }
+} | + + | ++A sample application demonstrating this flow is available here. + | +
🧪Experimental • Since 1.5.3
+| + + | ++This extension is known not to work. Contributions are welcome! + | +
Create a new project using quarkus-cxf-rt-ws-rm on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-rm</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Stable • Since 0.14.0
+Provides CXF framework’s WS-Security implementation.
+Create a new project using quarkus-cxf-rt-ws-security on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-security</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
The CXF framework’s WS-Security implementation is based on WSS4J. The example below shows how to integrate with WSS4J using interceptors.
+| + + | +
+Currently, only the programmatic WSS4JInterceptors are supported. Actions like Timestamp, UsernameToken, Signature, Encryption, etc., can be applied to the interceptors by passing the appropriate configuration properties.
+ |
+
Add the WSS4JInInterceptor to in-interceptors of your web service in application.properties:
quarkus.cxf.endpoint."/rounder".in-interceptors = org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor| + + | ++The sample code snippets used in this section come from the + WS-Security server integration test + in the source tree of CXF Extensions for Quarkus + | +
Then you can configure your WSS4JInInterceptor using CDI like the following:
@ApplicationScoped
+public class WSS4JInInterceptorProducer {
+
+ /** Produced in CxfWssServerTestResource */
+ @ConfigProperty(name = "wss.username", defaultValue = "cxf")
+ String username;
+
+ /** Produced in CxfWssServerTestResource */
+ @ConfigProperty(name = "wss.password", defaultValue = "pwd")
+ String password;
+
+ @Produces
+ @Unremovable
+ @ApplicationScoped
+ WSS4JInInterceptor wssInterceptor() {
+ final CallbackHandler passwordCallback = new CallbackHandler() {
+ @Override
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ for (Callback callback : callbacks) {
+ if (callback instanceof WSPasswordCallback) {
+ final WSPasswordCallback pc = (WSPasswordCallback) callback;
+ if (username.equals(pc.getIdentifier())) {
+ pc.setPassword(password);
+ }
+ return;
+ }
+ }
+ }
+ };
+ final Map<String, Object> props = new HashMap<>();
+ props.put(ConfigurationConstants.ACTION, "UsernameToken");
+ props.put(ConfigurationConstants.PASSWORD_TYPE, "PasswordText");
+ props.put(ConfigurationConstants.USER, username);
+ props.put(ConfigurationConstants.PW_CALLBACK_REF, passwordCallback);
+ return new WSS4JInInterceptor(props);
+ }
+}The corresponding client implementation would be slightly different:
+we will use WSS4JOutInterceptor and out-interceptors in application.properties:
quarkus.cxf.client."wss-client".out-interceptors=org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor| + + | ++The sample code snippets used in this section come from the + WS-Security client integration test + in the source tree of CXF Extensions for Quarkus + | +
Then producing the WSS4JOutInterceptor could look like the following.
@ApplicationScoped
+public class WSS4JOutInterceptorProducer {
+
+ /** Produced in CxfWssClientTestResource */
+ @ConfigProperty(name = "wss.username")
+ String username;
+
+ /** Produced in CxfWssClientTestResource */
+ @ConfigProperty(name = "wss.password")
+ String password;
+
+ @Produces
+ @Unremovable
+ @ApplicationScoped
+ WSS4JOutInterceptor wssInterceptor() {
+ final CallbackHandler passwordCallback = new CallbackHandler() {
+ @Override
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ for (Callback callback : callbacks) {
+ if (callback instanceof WSPasswordCallback) {
+ ((WSPasswordCallback) callback).setPassword(password);
+ }
+ return;
+ }
+ }
+ };
+ final Map<String, Object> props = new HashMap<>();
+ props.put(ConfigurationConstants.ACTION, "UsernameToken");
+ props.put(ConfigurationConstants.PASSWORD_TYPE, "PasswordText");
+ props.put(ConfigurationConstants.USER, username);
+ props.put(ConfigurationConstants.PW_CALLBACK_REF, passwordCallback);
+ props.put(ConfigurationConstants.ADD_USERNAMETOKEN_NONCE, "true");
+ props.put(ConfigurationConstants.ADD_USERNAMETOKEN_CREATED, "true");
+ return new WSS4JOutInterceptor(props);
+ }
+}Please refer to WS-Security and WSS4J documentation for details.
+Stable • Since 1.5.3
+Issue, renew and validate security tokens in context of WS-Trust.
+Create a new project using quarkus-cxf-services-sts on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-services-sts</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Please find an example in the +WS-Trust integration test in the source tree of CXF Extensions for Quarkus +while we are working hard on providing a more user friendly text for this page.
+Stable • Since 1.5.11
+XJC plugins for wsdl2java code generation. +You’ll need to add this extension if you want to use any of the following in +quarkus.cxf.codegen.wsdl2java.additional-params:
+-xjc-Xbg - generate getFoo() instead of isFoo() accessor methods for boolean fields.
-xjc-Xdv - let the generated getter methods return the default value defined in the schema unless the field is set explicitly.
-xjc-Xjavadoc - generate JavaDoc based on xs:documentation present in the schema.
-xjc-Xproperty-listener - add PropertyChangeListener support to the generated beans.
-xjc-Xts - generate toString() methods in model classes.
-xjc-Xwsdlextension - generate beans that can be used directly with WSDL4J as extensors in the WSDL.
| + + | +
+Check the wsdl2java section of User guide for more details about wsdl2java.
+ |
+
Create a new project using quarkus-cxf-xjc-plugins on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-xjc-plugins</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Stable • Since 0.1.0
+Core capabilities for implementing SOAP clients and JAX-WS services.
+Create a new project using quarkus-cxf on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Check the following chapters of User guide:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+The default path for CXF resources.
+⚠️ Note that the default value before 3.0.0 was
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files.
+There are 4 place holders, which can be used in the template:
+ -
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files.
+There are 4 place holders, which can be used in the template:
+ -
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The client service interface class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The service endpoint implementation class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The service endpoint WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The published service endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names or named CDI beans.
+Examples: quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature quarkus.cxf.endpoint."/fruit".features = #myCustomLoggingFeature In the second case, the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The client WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client interface class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint namespace +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The username for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names.
+Example: quarkus.cxf.endpoint.myClient.features = org.apache.cxf.ext.logging.LoggingFeature
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
Here is the list of extensions produced by this project. +Please follow the links under the extension names to learn about how to use them, about their configuration and about any known limitations.
+| Quarkus CXF extension | +Support level | +Since | +Supported standards | +
|---|---|---|---|
Quarkus CXF |
+Stable |
+0.1.0 |
++ |
Quarkus CXF Logging Feature |
+Stable |
+0.14.0 |
++ |
Quarkus CXF Metrics Feature |
+Experimental |
+0.14.0 |
++ |
Quarkus CXF WS-Security |
+Stable |
+0.14.0 |
++ |
Quarkus CXF WS-ReliableMessaging |
+Experimental |
+1.5.3 |
++ |
Quarkus CXF Security Token Service (STS) |
+Stable |
+1.5.3 |
++ |
Quarkus CXF HTTP Async Transport |
+Experimental |
+1.1.0 |
++ |
Quarkus CXF XJC Plugins |
+Stable |
+1.5.11 |
++ |
Here is a list of CXF modules supported by CXF Extensions for Quarkus. +You should typically not depend on these directly, but rather use some of the extensions listed above that brings the given CXF module as a transitive dependency.
+Out of CXF front ends only the
+JAX-WS front end is fully supported by quarkus-cxf.
The Simple front end may work in JVM mode, but it is not tested properly. +We advise not to use it.
+Out of CXF Data Bindings only the following ones are supported:
+Out of CXF Transports only the following ones are supported:
+quarkus-cxf implements its own custom transport based on Quarkus and Vert.x for serving SOAP endpoints
HTTP client via quarkus-cxf, including
Asynchronous Client HTTP Transport
+via quarkus-cxf-rt-transports-http-hc5
wsdl2Java - see the Generate the Model classes from WSDL
+ section of User guide
java2ws - see the Generate WSDL from Java section of User guide
All CXF WSDL Bindings are supported:
+Here is a list of CXF modules currently not supported by CXF Extensions for Quarkus along with possible alternatives and/or reasons why the given module is not supported.
+| CXF module | +Alternative | +
|---|---|
JAX-RS |
++ |
| + | + |
| + | Use JAXB and JAX-WS |
+
DOSGI |
++ |
JiBX |
+Use JAXB and JAX-WS |
+
Local transport |
+Use HTTP transport |
+
JMS transport |
+Use HTTP transport |
+
JBI |
+Deprecated in CXF use HTTP transport |
+
UDP transport |
+Use HTTP transport |
+
| + | Use HTTP transport |
+
WebSocket transport |
+Use HTTP transport |
+
Clustering |
++ |
CORBA
+ |
+Use JAX-WS |
+
SDO databinding |
++ |
| + | Deprecated in CXF |
+
| + | Use JAX-WS |
+
| + | Use HTTP transport |
+
WS-Transfer runtime |
++ |
Throttling |
+Use load balancer |
+
client-endpoint-url defaultsIf you omit the client-endpoint-url property in application.properties,
+the CXF Quarkus extension will assume that the service is published at http://localhost:8080/{service-path},
+where {service-path} is derived from
Configuration property quarkus.cxf.path (if specified); and the
SEI’s class name in lower case
+Given quarkus.cxf.path = /ws, the default effective client-endpoint-url of the CalculatorService would be
+http://localhost:8080/ws/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
If quarkus.cxf.path is not specified, the client-endpoint-url would be just
+http://localhost:8080/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
In the example above, we configured just a single client called myCalculator.
+Of course, you can configure multiple clients pointing at different URLs and/or implementing different SEIs using multiple identifiers:
cxf.it.calculator.baseUri = http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl=${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url=${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface=org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService
+
+# another client
+quarkus.cxf.client.anotherCalculator.wsdl = https://acme.com/ws/WeatherService?wsdl
+quarkus.cxf.client.anotherCalculator.client-endpoint-url = https://acme.com/ws/WeatherService
+quarkus.cxf.client.anotherCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorServiceBasic authentication for clients is supported by default.
+Just add the following properties to your application.properties:
quarkus.cxf.client.myCalculator.username = user
+quarkus.cxf.client.myCalculator.password = passwordTo globally configure all clients in your application, you can use the example snippet below to configure the
+HttpConduit.
+This allows you to set the HTTPClientPolicy, AuthorizationPolicy, ProxyAuthorizationPolicy or even TLSClientParameters for your clients.
void onStart(@Observes StartupEvent ev) {
+
+ HTTPConduitConfigurer httpConduitConfigurer = new HTTPConduitConfigurer() {
+ public void configure(String name, String address, HTTPConduit c) {
+ AsyncHTTPConduit conduit = (AsyncHTTPConduit)c;
+ // use setter to configure client
+ conduit.getHttpAsyncClient().getCredentialsProvider().setCredentials( AuthScope.ANY,
+ new NTCredentials( USER,PWD, "", DOM ) );
+ conduit.getClient().setAllowChunking( false );
+ conduit.getClient().setAutoRedirect( true );
+ }
+ };
+
+ final Bus bus = BusFactory.getThreadDefaultBus();
+ bus.setExtension(httpConduitConfigurer, HTTPConduitConfigurer.class);
+}To configure the HttpConduit for a single client in your application, use the example snippet below:
@Inject
+ @CXFClient
+ SomePortType portType;
+
+ @PostConstruct
+ void configurePortType() throws NoSuchAlgorithmException, UnrecoverableKeyException, KeyStoreException {
+ final var httpConduit = (HTTPConduit) ClientProxy.getClient(portType).getConduit();
+ final var tlsClientParameters = Optional.ofNullable(httpConduit.getTlsClientParameters()).orElseGet(TLSClientParameters::new);
+ tlsClientParameters.setCertAlias(config.clientCert().keyAlias());
+ tlsClientParameters.setKeyManagers(clientKeyManagers);
+ tlsClientParameters.setTrustManagers(clientTrustManagers);
+ httpConduit.setTlsClientParameters(tlsClientParameters);
+ }Camel Quarkus supports CXF since its version 2.12.0. +Under the hood, the implementation is based on CXF Extensions for Quarkus. +Therefore, all functionality available in CXF Extensions for Quarkus is also available in Camel Quarkus.
+Please refer to Camel Quarkus CXF SOAP extension documentation for further details.
+Some issues may appear during the development, testing, and native image building process of your quarkus-cxf project;
+below are some common ones and how to address them.
Sometimes a REST endpoint may be needed in the same project where the Quarkus CXF Extension is used. +The REST endpoint path must be different from the SOAP endpoint path (in order to avoid request +forwarding conflicts between both protocols).
+For example, if a WeatherWebService interface is declared in a WSDL, you can
+begin by creating the org.acme.cxf.WeatherWebServiceImpl class as follows:
package org.acme.cxf;
+
+import ...
+
+@Slf4j
+@WebService(endpointInterface = "org.acme.cxf.WeatherWebService")
+public class WeatherWebServiceImpl implements WeatherWebService {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ private Map<String, DailyTemperature> dailyTempByZipCode = Collections.synchronizedMap(new LinkedHashMap<>());
+
+ public WeatherWebServiceImpl() {
+ this.dailyTempByZipCode.addAll(
+ this.backEndWeatherService.getDailyForecast(Instant.now()));
+ }
+
+ @Override
+ public DailyTemperature estimationTemperatures(String zipCode) {
+ log.info("Daily estimation temperatures forecast called with '{}' zip code paramter", zipCode);
+ return this.dailyTempByZipCode.get(zipCode);
+ }
+}After that, you would need to specify the root context for your CXF web services, as indicated +in the properties documentation to split the REST (with RESTEasy for example) +and SOAP routes based on their root context paths.
+CXF’s SOAP properties:
+quarkus.cxf.path=/soap
+quarkus.cxf.endpoint."/weather".implementor=org.acme.cxf.WeatherWebServiceImplNow, imagine the following RESTEasy endpoint:
+package org.acme.reasteasy;
+
+import ...
+
+@Slf4j
+@Path("/healthcheck")
+public class HealthCheckResource {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ @GET
+ public Response doHealthCheck() {
+ if(this.backEndWeatherService.isAvailable()) {
+ return Response.ok().build();
+ } else {
+ return Response.status(Response.Status.SERVICE_UNAVAILABLE);
+ }
+ }
+}You can separate your REST endpoint by configuring the REASTEasy path:
+quarkus.resteasy.path=/restYou should now be able to send requests to both your REST and SOAP endpoints deployed within a single project, at:
+http://localhost:8080/soap/weather for SOAP
+Sometimes the wsdl2java autogenerated Java classes may not be +fully compatible with GraalVM due to non ASCII characters getting included in the code. Similar exceptions to +the below may appear during native image builds.
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] compile: 161 459,15 ms, 8,54 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] image: 158 272,73 ms, 8,43 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] write: 205,82 ms, 8,43 GB
+Fatal error:com.oracle.svm.core.util.VMError$HostedError: java.lang.RuntimeException: oops : expected ASCII string! com.oracle.svm.reflect.OperationOrderStatusType_CRÉÉ_f151156b0d42ecdbdfb919501d8a86dda8733012_1456.hashCode
+ at com.oracle.svm.core.util.VMError.shouldNotReachHere(VMError.java:72)Below is an example of auto-generated non ASCII characters in a Java class:
+@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Cr\u00e9\u00e9")
+ CRÉÉ("Cr\u00e9\u00e9"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de r\u00e9ponse")
+ EN_ATTENTE_DE_RÉPONSE("En attente de r\u00e9ponse"),
+ @XmlEnumValue("Attribu\u00e9")
+ ATTRIBUÉ("Attribu\u00e9"),
+ @XmlEnumValue("Clotur\u00e9")
+ CLOTURÉ("Clotur\u00e9"),
+ @XmlEnumValue("Annul\u00e9")
+ ANNULÉ("Annul\u00e9");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Anything starting with \u will be a problem. Consequently the following refactoring is needed:
@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Créé")
+ CREE("Créé"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de réponse")
+ EN_ATTENTE_DE_REPONSE("En attente de réponse"),
+ @XmlEnumValue("Attribué")
+ ATTRIBUE("Attribué"),
+ @XmlEnumValue("Cloturé")
+ CLOTURE("Cloturé"),
+ @XmlEnumValue("Annulé")
+ ANNULE("Annulé");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Both contract first and code first development modes are fully supported by CXF Extensions for Quarkus.
+A SOAP service is described by WSDL.
+It is a contract defining operations, their parameters and return values, etc.
+WSDL is rich enough to be used for generating the code of a complete client.
+CXF provides the wsdl2java utility for that.
CXF Extensions for Quarkus wraps wsdl2java in the quarkus-cxf extension so you do not need to use it directly.
Please follow the Generate the Model classes from WSDL section of the user guide +for more details about how to use it.
+You may also want to check the CXF Developing a Consumer as a general introduction.
+When implementing a service the generation of Java code from WSDL
+may also come in handy.
+wsdl2java can generate the model classes (with JAXB annotations)
+and service interfaces (with JAX-WS annotations) for you.
+Your task is then to provide implementations for those interfaces.
You may want to check the WSDL First Service Development +section of CXF documentation for a better understanding of the underlying concepts.
+Another valid option at your disposal is to write your service in Java, using JAX-WS and JAXB. +Then you have two options how to obtain the WSDL contract:
+Start your service and point your clients at http://your-host/your-service?wsdl
+Generate the WSDL document from Java classes at build time
+| + + | ++Check the Code first development section of CXF documentation for further information. + | +
This guide explains how to set up a new project for a Quarkus application hosting a CXF client or server or both.
+Please read the Prerequisites section of Quarkus getting started guide.
+In addition to that, you may need
+GraalVM with the native-image command installed and the GRAALVM_HOME environment variable set.
+See Building a native executable section of the Quarkus
+documentation.
If you are on Linux, a container runtime like docker is sufficient for the native mode too.
+Use -Pnative -Dquarkus.native.container-build=true instead of -Pnative if you choose this option.
New project skeletons can be generated using code.quarkus.io.
+All extensions produced by Quarkiverse CXF project can be found using origin:other cxf query.
+Here you can select the extensions that you want to work with.
+For a simple Hello world Web service or client the `quarkus-cxf`extension is enough.
+Click the blue Generate your application button to download a basic skeleton project.
Unpack the zip file and import the project the into your favorite IDE.
+code.quarkus.io currently generates pom.xml files
+containing quarkus-cxf* dependencies with version literals (see issue #651)
+like the following:
...
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>${quarkus.platform.artifact-id}</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf</artifactId>
+ <version>1.5.17</version>
+ </dependency>
+ ...
+ </dependencies>
+...This might become impractical, once you start adding more extensions from CXF Extensions for Quarkus +or some optionals required for covering some specific use cases.
+Thus we recommend to add quarkus-cxf-bom manually:
...
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>${quarkus.platform.artifact-id}</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-bom</artifactId>
+ <version>1.5.17</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf</artifactId>
+ <!-- no version required here if you import quarkus-cxf-bom above -->
+ </dependency>
+ ...
+ </dependencies>
+...quarkus-cxf-bom version?Each CXF Extensions for Quarkus major.minor version stream is compatible with some specific major.minor stream of Quarkus.
E.g. the current stable release of CXF Extensions for Quarkus is 1.5.17.
+It was tested against Quarkus 2.13.8.Final.
+Hence, at the given point in time, you’ll best use the newest micro version of that Quarkus Platform stream.
+The available versions of io.quarkus.platform:quarkus-bom can be viewed on
+Maven Central.
CXF interceptors and CXF features can be added to both your client or server using either annotations or application.properties configurations.
While CXF provides a number of out of the box embedded interceptors and features, you can also integrate your custom developed implementations.
+Annotations can be used on either the service interface or implementor classes.
+@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@org.apache.cxf.interceptor.InInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor" })
+@org.apache.cxf.interceptor.OutInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor","org.acme.Test3Intercetpor" })
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}You may also define your configurations in the application.properties file.
quarkus.cxf.endpoint."/greeting-service".features=org.apache.cxf.ext.logging.LoggingFeature
+quarkus.cxf.endpoint."/greeting-service".in-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".out-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".in-fault-interceptors=org.acme.Test2Interceptor,org.acme.Test3Intercetpor
+quarkus.cxf.endpoint."/greeting-service".out-fault-interceptors=org.acme.Test1Intercetpor| + + | ++Both feature and interceptor classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class. + | +
The integration-tests folder of the codebase provides various examples
+that demonstrate how to use this extension extensively.
In this guide we explain how to create a simple Quarkus application acting as a client of a remote Web service.
+| + + | ++Follow the Project creation guide before proceeding here. + | +
First, we need some remote Web service to connect to. +We can use a simple Calculator Web service running in a container for that purpose.
+$ docker run -p 8082:8080 quay.io/l2x6/calculator-ws:1.0Once the container is up and running, we can inspect its WSDL
+$ curl -s http://localhost:8082/calculator-ws/CalculatorService?wsdl
+<?xml version="1.0" ?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="CalculatorService" targetNamespace="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+
+ ...
+
+ <wsdl:binding name="CalculatorServiceSoapBinding" type="tns:CalculatorService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"></soap:binding>
+ <wsdl:operation name="add">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="add">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="addResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+ <wsdl:operation name="subtract">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="subtract">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="subtractResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+
+ ...
+
+ </wsdl:binding>
+
+ ...
+
+</wsdl:definitions>As you can see in the WSDL, the service offers some basic arithmetic operations, such as add, subtract, etc.
Let’s test it with curl:
$ curl -s \
+ -X POST \
+ -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
+ <Body>
+ <add xmlns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <arg0 xmlns="">7</arg0> (1)
+ <arg1 xmlns="">4</arg1>
+ </add>
+ </Body>
+ </Envelope>' \
+ http://localhost:8082/calculator-ws/CalculatorService
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:addResponse xmlns:ns2="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <return>11</return> (2)
+ </ns2:addResponse>
+ </soap:Body>
+</soap:Envelope>| 1 | +The request to add 7 and 4 |
+
| 2 | +11 - return value of the operation |
+
Now let’s have a look how we can get the client inside a Quarkus application.
+First, we need the Service Endpoint Interface (SEI) and all other model classes it requires.
+There are several ways to get them:
+Write by hand
+Copy from the Web Sevice project, if it is written in Java
+Have a Maven artifact containing the model classes, perhaps it is offered by the Service project
+Generate the model classes from WSDL
+The last option tends to be the easiest and most flexible for client applications.
+| + + | ++If you want to use this approach, please first follow the Generate Java from WSDL section and then continue with the next steps. + | +
In our case, the Service Endpoint Interface (SEI) is org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService.
As usual on Quarkus, we can obtain an instance of it via CDI.
+To make it testable easily, we’ll wrap it in a REST service:
+package io.quarkiverse.cxf.client.it;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.MediaType;
+
+import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
+
+import io.quarkiverse.cxf.annotation.CXFClient;
+
+@Path("/cxf/calculator-client")
+public class CxfClientRestResource {
+
+ @CXFClient("myCalculator") (1)
+ CalculatorService myCalculator;
+
+ @GET
+ @Path("/add")
+ @Produces(MediaType.TEXT_PLAIN)
+ public int add(@QueryParam("a") int a, @QueryParam("b") int b) {
+ return myCalculator.add(a, b); (2)
+ }
+
+}| 1 | +Let the CDI container inject an instance of the client. @CXFClient("myCalculator") is actually equivalent to @Inject @CXFClient("myCalculator") |
+
| 2 | +Invoke the add operation thus calling the remote Web service |
+
Is this all we need for the client to work?
+- No, in addition to the above, we need to tell a few other things to the CXF Quarkus extension in application.properties:
cxf.it.calculator.baseUri=http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl=${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url=${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface=org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService| + + | ++All client configuration properties are documented in the Configuration properties reference. + | +
With all the above files in place, we should be able to start the application in Quarkus dev mode
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and test it by sending some requests to it:
+$ curl -s 'http://localhost:8080/cxf/calculator-client/add?a=5&b=6'
+11where 11 is the correct result of adding 5 and 6.
In this guide we explain how to create a Quarkus application exposing a simple SOAP Web service.
+| + + | ++Follow the Project creation guide before proceeding here. + | +
Having the pom.xml in place, you can add a simple Hello world! Web service in src/main/java.
| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
First add the service interface:
+package io.quarkiverse.cxf.it.server;
+
+import javax.jws.WebMethod;
+import javax.jws.WebService;
+
+/**
+ * The simplest Hello service.
+ */
+@WebService(name = "HelloService", serviceName = "HelloService")
+public interface HelloService {
+
+ @WebMethod
+ String hello(String text);
+
+}and then the implementation:
+package io.quarkiverse.cxf.it.server;
+
+import javax.jws.WebMethod;
+import javax.jws.WebService;
+
+/**
+ * The simplest Hello service implementation.
+ */
+@WebService(serviceName = "HelloService")
+public class HelloServiceImpl implements HelloService {
+
+ @WebMethod
+ @Override
+ public String hello(String text) {
+ return "Hello " + text + "!";
+ }
+
+}For the implementation to get exposed under a certain path, you need to add the following configuration to application.properties:
# The context path under which all services will be available
+quarkus.cxf.path=/soap
+
+# Publish "HelloService" under the context path /${quarkus.cxf.path}/hello
+quarkus.cxf.endpoint."/hello".implementor=io.quarkiverse.cxf.it.server.HelloServiceImpl
+quarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeature| + + | ++All configuration properties are documented in the Configuration properties reference. + | +
With these files in place, you can start Quarkus in dev mode:
$ mvn quarkus:devThis will compile the project and start the application on the background.
+You can test the service using curl or some other SOAP client.
First let’s have a look at the auto-generated WSDL under http://localhost:8080/soap/hello?wsdl:
+$ curl http://localhost:8080/soap/hello?wsdl
+<?xml version='1.0' encoding='UTF-8'?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://server.it.cxf.quarkiverse.io/"
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http"
+ name="HelloService" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <wsdl:types>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://server.it.cxf.quarkiverse.io/" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <xsd:element name="hello" type="tns:hello"/>
+ <xsd:complexType name="hello">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="arg0" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+ <xsd:element name="helloResponse" type="tns:helloResponse"/>
+ <xsd:complexType name="helloResponse">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="return" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+</xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="helloResponse">
+ <wsdl:part element="tns:helloResponse" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="hello">
+ <wsdl:part element="tns:hello" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:portType name="HelloService">
+ <wsdl:operation name="hello">
+ <wsdl:input message="tns:hello" name="hello">
+ </wsdl:input>
+ <wsdl:output message="tns:helloResponse" name="helloResponse">
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="HelloServiceSoapBinding" type="tns:HelloService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+ <wsdl:operation name="hello">
+ <soap:operation soapAction="" style="document"/>
+ <wsdl:input name="hello">
+ <soap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="helloResponse">
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="HelloService">
+ <wsdl:port binding="tns:HelloServiceSoapBinding" name="HelloServicePort">
+ <soap:address location="http://localhost:8080/soap/hello"/>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions>Second, let’s send a SOAP request to the service:
+$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+ </soap:Envelope>' \
+ http://localhost:8080/soap/hello
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return>Hello World!</return>
+ </ns1:helloResponse>
+ </soap:Body>
+</soap:Envelope>Note the expected <return>Hello World!</return> in the SOAP response.
Sometimes it may come in handy to be able to inspect the SOAP messages received or sent by the server or client.
+This is easily doable by adding the quarkus-cxf-rt-features-logging extension to pom.xml.
| + + | ++Try to do that while Quarkus dev mode is running. + You should see the application being recompiled and redeployed upon saving your changes in the source tree. + | +
pom.xml<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-logging</artifactId>
+</dependency>application.propertiesquarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeatureAfter that you can send a new SOAP request and see some SOAP payloads in the application console:
+2023-01-11 22:12:21,315 INFO [org.apa.cxf.ser.Hel.REQ_IN] (vert.x-worker-thread-0) REQ_IN
+ Address: http://localhost:8080/soap/hello
+ HttpMethod: POST
+ Content-Type: text/xml;charset=UTF-8
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {Accept=*/*, User-Agent=curl/7.79.1, content-type=text/xml;charset=UTF-8, Host=localhost:8080, Content-Length=203, x-quarkus-hot-deployment-done=true}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+</soap:Envelope>
+
+
+2023-01-11 22:12:21,327 INFO [org.apa.cxf.ser.Hel.RESP_OUT] (vert.x-worker-thread-0) RESP_OUT
+ Address: http://localhost:8080/soap/hello
+ Content-Type: text/xml
+ ResponseCode: 200
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/"><return>Hello World!</return></ns1:helloResponse></soap:Body></soap:Envelope>You may want to proceed with packaging your application for running on a JVM or natively.
+quarkus-cxf extension supports generating Java classes from WSDL during Quarkus code generation phase.
| + + | ++The code snippets shown in this section come from the + client integration test + in the source tree of CXF Extensions for Quarkus. + You may want to check it as an executable example. + | +
You need to set up a couple of things for CXF code generation to work:
+Have io.quarkiverse.cxf:quarkus-cxf dependency in your project
For Maven projects, the generate-code goal needs to be present in the configuration of quarkus-maven-plugin:
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>For Gradle projects no additional configurarion of io.quarkus plugin is needed
Put your WSDL files under src/main/resources or src/test/resources or any subdirectory thereof.
Your WSDL file names must end with .wsdl
Set quarkus.cxf.codegen.wsdl2java.includes
+configuration property
+to a pattern matching the WSDL files you wish to process.
+If you want to process all WSDL files under src/main/resources/wsdl or src/test/resources/wsdl, set it as follows:
quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdlThis will generate Java classes in target/generated-sources/wsdl2java or
+target/generated-test-sources/wsdl2java directory.
+They will be automatically picked by the compiler plugin there.
+Hence we are free to refer to them from our application or test code.
Note that quarkus-cxf code generation uses the wsdl2Java utility
+from CXF under the hood. wsdl2Java is called separately for each WSDL file selected by includes and excludes.
Passing custom parameters to wsdl2java is possible through
+quarkus.cxf.codegen.wsdl2java.additional-params
+configuration parameter.
If you need different additional-params for each WSDL file, you may want to define a separate named parameter set for
+each one of them. Here is an example:
# Parameters for foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.includes = wsdl/foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.additional-params = -wsdlLocation,wsdl/foo.wsdl
+# Parameters for bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.includes = wsdl/bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.additional-params = -wsdlLocation,wsdl/bar.wsdl,-xjc-Xts| + + | +
+Add io.quarkiverse.cxf:quarkus-cxf-xjc-plugins dependency to your project to be able to use
+ -xjc-Xbg, -xjc-Xdv, -xjc-Xjavadoc, -xjc-Xproperty-listener, -xjc-Xts and -xjc-Xwsdlextension
+ wsdl2java parameters.
+ |
+
If the WSDL served by your service at http://your-host/your-service?wsdl is not enough
+because you e.g. want to distribute it as a Maven artifact,
+then you can use java2ws to generate the WSDL document at build time.
You do not need to invoke the java2ws tool provided by CXF directly,
+neither you have to use the cxf-java2ws-plugin.
quarkus-cxf wraps java2ws and so you can configure it in application.properties
+as any other aspect of your application.
Here is an example:
+| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
quarkus.cxf.java2ws.includes=io.quarkiverse.cxf.it.server.HelloService,io.quarkiverse.cxf.it.server.FaultyHelloService
+quarkus.cxf.java2ws.wsdl-name-template=%TARGET_DIR%/Java2wsTest/%SIMPLE_CLASS_NAME%-from-java2ws.wsdlHere we have instructed java2ws to generate WSDLs for two interfaces,
+namely HelloService and FaultyHelloService.
Note that the Service interfaces must be annotated with jakarta.xml.ws.WebService to be selected for java2ws processing.
The two generated WSDL documents will be stored as target/Java2wsTest/FaultyHelloService-from-java2ws.wsdl
+and target/Java2wsTest/HelloService-from-java2ws.wsdl respectively.
| + + | +
+Unlike wsdl2java which is executed within Quarkus source generation phase,
+ java2ws is a part Quarkus augmentation that happens after compilation.
+ The input of java2ws are, after all, Java class files.
+ Hence you do not need to add <goal>generate-code</goal> to quarkus-maven-plugin
+ for java2ws.
+ |
+
quarkus.cxf.java2ws.* configuration properties of quarkus-cxf
This User guide explains typical use cases of CXF Extensions for Quarkus.
+You may want to start with some of the following topics:
+As an alternative to the @HandlerChain annotation,
+JAX-WS Handlers can be added
+to both your client or server via application.properties:
# A web service endpoint with multiple Handler classes
+quarkus.cxf.endpoint."/greeting-service".handlers=org.acme.MySOAPHandler,org.acme.AnotherSOAPHandler
+
+# A web service client with a single Handler
+quarkus.cxf.client."greeting-client".handlers=org.acme.MySOAPHandlerWhere MySOAPHandler could look like below:
import jakarta.xml.ws.handler.soap.SOAPHandler;
+import jakarta.xml.ws.handler.soap.SOAPMessageContext;
+
+public class MySOAPHandler implements SOAPHandler {
+
+ public boolean handleMessage(SOAPMessageContext messageContext) {
+ SOAPMessage msg = messageContext.getMessage();
+ return true;
+ }
+ // other methods
+} | + + | +
+The SOAPHandler classes will be attempted to be loaded via CDI first.
+ If no CDI beans are available for the given type, then the no parameters constructor will used
+ to instantiate each class.
+ |
+
JAX-WS Providers are fully supported, and can be implemented as shown below.
+Given the following sample Provider implementation:
import jakarta.xml.transform.stream.StreamSource;
+import jakarta.xml.ws.BindingType;
+import jakarta.xml.ws.Provider;
+import jakarta.xml.ws.Service;
+import jakarta.xml.ws.ServiceMode;
+import jakarta.xml.ws.WebServiceProvider;
+import java.io.StringReader;
+
+@WebServiceProvider
+@ServiceMode(value = Service.Mode.PAYLOAD)
+public class StreamSourcePayloadProvider implements Provider {
+
+ public StreamSourcePayloadProvider() {
+ }
+
+ public StreamSource invoke(StreamSource request) {
+ String payload = StaxUtils.toString(request);
+
+ // Do some interesting things ...
+
+ StreamSource response = new StreamSource(new StringReader(payload));
+ return response;
+ }
+} The application.properties can be configured as shown below.
# A web service endpoint with the Provider implementation class
+quarkus.cxf.endpoint."/stream-source".implementor=org.acme.StreamSourcePayloadProvider| + + | +
+Provider classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class.
+ |
+
In this chapter, we explain how to package a Quarkus CXF application for running on a JVM or for running it natively.
+In the introductory guides for SOAP client and SOAP service, we worked only in Quarkus dev mode:
+Quarkus tooling was running on the background,
+watching for changes in our workspace, recompiling and reloading the application as needed.
How do we run the application on a JVM once we are done with the development?
+First we need to package it with Maven:
+$ mvn packageThe libraries needed to run the application on a JVM can be found in target/quarkus-app directory:
$ ls -lh target/quarkus-app
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 app
+drwxr-xr-x. 4 ppalaga ppalaga 4.0K Jan 12 22:29 lib
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 quarkus
+-rw-r--r--. 1 ppalaga ppalaga 6.1K Jan 12 22:29 quarkus-app-dependencies.txt
+-rw-r--r--. 1 ppalaga ppalaga 678 Jan 12 22:29 quarkus-run.jarWe can start the application as follows:
+$ java -jar target/quarkus-app/quarkus-run.jarYou can send some SOAP requests using curl to make sure that the application works.
Quarkus offers first class support for building GraalVM native images +and CXF Extensions for Quarkus fully honors that promise too.
+| + + | ++GraalVM native images are platform specific executable files that you can run directly without a JVM. + They boot faster and spend less memory compared to running the same application in JVM mode. + | +
The pom.xml file generated by code.quarkus.io
+contains the native profile needed for building the native image:
<profile>
+ <id>native</id>
+ <activation>
+ <property>
+ <name>native</name>
+ </property>
+ </activation>
+ <properties>
+ <skipITs>false</skipITs>
+ <quarkus.package.type>native</quarkus.package.type>
+ </properties>
+</profile>Further, as mentioned above, you need the GraalVM native-image tool.
You should either have it installed locally and have GRAALVM_HOME environment variable set properly,
+or — if you only need to produce a Linux native executable — you can use docker.
# Make sure $GRAALVM_HOME is set properly
+$ echo $GRAALVM_HOME
+/home/{user}/.sdkman/candidates/java/{major}.{minor}.r{java-version}-grl
+
+# Produce the native executable
+mvn package -Pnative| + + | +
+Quarkus is quite picky about the GraalVM version.
+ When using the local installation, always make sure that you use the version preferred by Quarkus.
+ You can do that by opening quarkus-bom imported in your pom.xml and searching for graalvm there.
+ If you use Docker, Quarkus takes care for pulling the right version for you.
+ |
+
docker# Produce the native executable
+mvn package -Pnative -Dquarkus.native.container-build=trueThis can take a minute or so for a simple application.
+When the build is done, the native executable should be available in target directory:
$ ls -l target
+...
+-rwxr-xr-x. 1 ppalaga ppalaga 71M Jan 11 22:42 quarkus-cxf-integration-test-server-1.8.0-SNAPSHOT-runner
+...Note the x permission on Linux and the size of just 71 MB.
You can run it as follows:
+$ target/*-runner
+...
+INFO [io.quarkus] (main) quarkus-cxf-integration-test-server 1.8.0-SNAPSHOT native (powered by Quarkus
+2.15.2.Final) started in 0.042s. Listening on: http://0.0.0.0:8080
+...Again, you can send some SOAP requests using curl to make sure that the native executable works.
Do not forget to compare the memory usage, time to first request and other performance metrics +with the stack you used before and share your results!
+You may also refer to the links below which contain tips on how to work with native images.
+Please refer to Quarkus Container image guide.
+Our introductory guides for Quarkus SOAP client +and SOAP service dealt with services +having only primitive parameters and return values such as integers and strings. +Let’s have a look at passing and receiving more complex objects.
+As an example, let’s create an application for managing fruits.
+| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
Because our representation of fruit is supposed to be a complex, let’s model it as a Java bean with a couple of attributes:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Objects;
+
+import javax.xml.bind.annotation.XmlElement;
+import javax.xml.bind.annotation.XmlRootElement;
+import javax.xml.bind.annotation.XmlType;
+
+@XmlType(name = "Fruit")
+@XmlRootElement
+public class Fruit {
+
+ private String name;
+
+ private String description;
+
+ public Fruit() {
+ }
+
+ public Fruit(String name, String description) {
+ this.name = name;
+ this.description = description;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ @XmlElement
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ @XmlElement
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.getName(), this.getName());
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.getName());
+ }
+}As you may have noticed, we have used some JAXB annotations,
+such as @XmlElement, @XmlRootElement and @XmlType.
+This is to control the serialization and deserialization of the bean from and to XML.
JAXB is a reflection based serialization framework.
+When learning about GraalVM native images, one of the first things you typically hear is
+that you have to register classes, fields and methods for reflection at build time.
+With plain GraalVM you’d have to do this through reflection-config.json manually.
+Well, at least for the classes you have written yourself.
+Not so with Quarkus. quarkus-jaxb extension (which quarkus-cxf depends on)
+is able to scan your application’s class path for classes annotated with JAXB annotations
+and register them for reflection automatically.
Hence working with complex payloads on Quarkus is not different from stock CXF. +The JAXB serialization and deserialization will work out of the box without any additional configuration.
+The Service Endpoint Interface (SEI) for managing fruits might look like the following:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Set;
+
+import javax.jws.WebMethod;
+import javax.jws.WebService;
+
+@WebService
+public interface FruitService {
+
+ @WebMethod
+ Set<Fruit> list();
+
+ @WebMethod
+ Set<Fruit> add(Fruit fruit);
+
+ @WebMethod
+ Set<Fruit> delete(Fruit fruit);
+}We can implement the SEI as simply as possible:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+import javax.jws.WebService;
+
+@WebService(serviceName = "FruitService")
+public class FruitServiceImpl implements FruitService {
+
+ private Set<Fruit> fruits = Collections.synchronizedSet(new LinkedHashSet<>());
+
+ public FruitServiceImpl() {
+ fruits.add(new Fruit("Apple", "Winter fruit"));
+ fruits.add(new Fruit("Pineapple", "Tropical fruit"));
+ }
+
+ @Override
+ public Set<Fruit> list() {
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> add(Fruit fruit) {
+ fruits.add(fruit);
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> delete(Fruit fruit) {
+ fruits.remove(fruit);
+ return fruits;
+ }
+}application.propertiesThe implementation is pretty straightforward and you just need to define your endpoints using the application.properties.
quarkus.cxf.endpoint."/fruits".implementor=io.quarkiverse.cxf.it.server.FruitServiceImpl
+quarkus.cxf.endpoint."/fruits".features=org.apache.cxf.ext.logging.LoggingFeaturedev mode and curlHaving the above files in place, you can start Quarkus tooling in dev mode:
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and then check whether the service is working by invoking its list operation:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soapenv:Envelope
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <soapenv:Body>
+ <ns1:list/>
+ </soapenv:Body>
+ </soapenv:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:listResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ </ns1:listResponse>
+ </soap:Body>
+</soap:Envelope>As you can see, the endpoint has returned the two fruits Apple and Pineapple available by default.
Now let’s add another fruit, say an Orange:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:add xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <arg0>
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </arg0>
+ </ns2:add>
+ </soap:Body></soap:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:addResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </return>
+ </ns1:addResponse>
+ </soap:Body>
+</soap:Envelope>We can see Orange having been added in the returned list as expected.
You may want to proceed with packaging your application for running on a JVM or natively.
+By default, a SOAP 1.1 binding is used. In order to switch to SOAP 1.2 and/or support MTOM, the config quarkus.cxf.endpoint.key.soap-binding must be set to one of the following values:
Binding |
+Property Value |
+
SOAP 1.1 |
++ |
SOAP 1.2 |
++ |
SOAP 1.1 with MTOM |
++ |
SOAP 1.2 with MTOM |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+The default path for CXF resources. +
+
+⚠️ Note that the default value before Quarkus CXF version 2.0.0 was
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Examples: +
+
+
+
+
+
+
+
+Note that file extensions other than
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the file sets selected by
+
+The files from
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+You need to add
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+The universe of class names to which
+
+Examples: +
+
+Let’s say that the application contains two classes annotated with
+
+Then +
+
+
+
+
+
+
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the class names selected by
+
+If you would like to include the generated WSDL files in native image, you need to add them yourself using
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Note that only options related to generation of WSDL from Java are supported currently. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files. +
+
+There are 4 place holders, which can be used in the template: +
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Select the
+
+
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The size in bytes of the chunks of memory allocated when writing data. +
+
+This is a very advanced setting that should only be set if you understand exactly how it affects the output IO operations of the application. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The size of the output stream response buffer in bytes. If a response is larger than this and no content-length is provided then the response will be chunked. +
+
+Larger values may give slight performance increases for large responses, at the expense of more memory usage. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Examples: +
+
+
+
+
+
+
+
+Note that file extensions other than
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the file sets selected by
+
+The files from
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+You need to add
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+The universe of class names to which
+
+Examples: +
+
+Let’s say that the application contains two classes annotated with
+
+Then +
+
+
+
+
+
+
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the class names selected by
+
+If you would like to include the generated WSDL files in native image, you need to add them yourself using
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Note that only options related to generation of WSDL from Java are supported currently. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files. +
+
+There are 4 place holders, which can be used in the template: +
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The client service interface class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If
+
+Setting this to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The service endpoint implementation class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The service endpoint WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The published service endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names or named CDI beans. +
+
+Examples: +
+
+
+
+
+
+In the second case, the
+
+
+
+
+
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The client WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint namespace +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The username for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names. +
+
+Example: +
+
+
+
+
+
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Specifies the amount of time, in milliseconds, that the consumer will attempt to establish a connection before it times out. 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the amount of time, in milliseconds, used when requesting a connection from the connection manager(if appliable). 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies if the consumer will automatically follow a server issued redirection. (name is not part of standard) +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the maximum amount of retransmits that are allowed for redirects. Retransmits for authorization is included in the retransmit count. Each redirect may cause another retransmit for a UNAUTHORIZED response code, ie. 401. Any negative number indicates unlimited retransmits, although, loop protection is provided. The default is unlimited. (name is not part of standard) +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+If true, the client is free to use chunking streams if it wants, but it is not required to use chunking streams. If false, the client must use regular, non-chunked requests in all cases. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If AllowChunking is true, this sets the threshold at which messages start getting chunked. Messages under this limit do not get chunked. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Specifies the chunk length for a HttpURLConnection. This value is used in java.net.HttpURLConnection.setChunkedStreamingMode(int chunklen). chunklen indicates the number of bytes to write in each chunk. If chunklen is less than or equal to zero, a default value will be used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Specifies the MIME types the client is prepared to handle (e.g., HTML, JPEG, GIF, etc.) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the language the client desires (e.g., English, French, etc.) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the encoding the client is prepared to handle (e.g., gzip) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the content type of the stream being sent in a post request. (this should be text/xml for web services, or can be set to application/x-www-form-urlencoded if the client is sending form data). +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the Internet host and port number of the resource on which the request is being invoked. This is sent by default based upon the URL. Certain DNS scenarios or application designs may request you to set this, but typically it is not required. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The connection disposition. If close the connection to the server is closed after each request/response dialog. If Keep-Alive the client requests the server to keep the connection open, and if the server honors the keep alive request, the connection is reused. Many servers and proxies do not honor keep-alive requests. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Most commonly used to specify no-cache, however the standard supports a dozen or so caching related directives for requests +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+HTTP Version used for the connection. The "auto" default will use whatever the default is for the HTTPConduit implementation. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+aka User-Agent Specifies the type of browser is sending the request. This is usually only needed when sites have HTML customized to Netscape vs IE, etc, but can also be used to optimize for different SOAP stacks. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider→consumer connection. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the address of proxy server if one is used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the port number used by the proxy server. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Specifies the list of hostnames that will not use the proxy configuration. Examples of value: * "localhost" → A single hostname * "localhost|www.google.com" → 2 hostnames that will not use the proxy configuration * "localhost|www.google.*|*.apache.org" → It’s also possible to use a pattern-like value +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the type of the proxy server. Can be either HTTP or SOCKS. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Username for the proxy authentication +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for the proxy authentication +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Select the
+
+
+
+Environment variable: |
+
+
|
++ |
This project aims at porting Apache CXF to Quarkus runtime +including full support for producing GraalVM native images.
+| + + | ++While Apache CXF implements wide range of standards and specifications, +CXF Extensions for Quarkus is currently focusing only on supporting the ones related to +Simple Object Access Protocol (SOAP) +and Java API for XML Web Services (JAX-WS). +Please refer to Reference to learn which parts of CXF are supported. + | +
The documentation is divided in two major parts:
+User guide - explains the typical usage of CXF Extensions for Quarkus
+Reference - the full list of supported specifications, use cases and configuration options
+Please feel free to start a discussion +or open an issue in the GitHub repository in case you need support. +The following general guidelines can be used to determine whether to start a discussion or open an issue.
+Bug reports
+Feature requests
+Q&A and general communication
+RFCs for new features
+Contributions and pull requests from the community are welcome!
+Stable • Since 0.14.0
+Allows logging HTTP headers and bodies of SOAP requests and responses for both CXF clients and services.
+Create a new project using quarkus-cxf-rt-features-logging on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-logging</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
This extension wraps the CXF org.apache.cxf:cxf-rt-features-logging artifact
+thus providing the org.apache.cxf.ext.logging.LoggingFeature class.
LoggingFeature instances can be configured per service or per client.
+You can either use a LoggingFeature instance with default settings
+or you can produce a custom LoggingFeature CDI bean.
LoggingFeature to a client or serviceYou have two options to do that:
+In application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeature
+# For a client:
+quarkus.cxf.client."myClient".features=org.apache.cxf.ext.logging.LoggingFeature| + + | ++There is an example in Your first SOAP Web service chapter of the User guide. + | +
or alternatively
+Use the @Features annotation of CXF:
@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}LoggingFeatureLoggingFeature offers some attributes that may be worth customizing in some situations.
E.g. if your payloads are complex, you may want to set prettyLogging to true to render them with an indentation.
+Or if your messages are big and you need to see them complete in the log, you may want to increase the limit.
| + + | +
+Check the CXF message logging page for all possible LoggingFeature attributes.
+ |
+
To achieve this, you can produce a custom LoggingFeature bean that is then picked by Quarkus CXF
+for clients and services where you specified *.features = org.apache.cxf.ext.logging.LoggingFeature:
import org.apache.cxf.ext.logging.LoggingFeature;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ LoggingFeature loggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ loggingFeature.setLimit(Integer.MAX_VALUE);
+ return loggingFeature;
+ }
+}LoggingFeaturesIn case you’d like to configure the LoggingFeatures for your individual services or clients differently,
+you can so that by defining multiple @Named LoggingFeature beans:
import org.apache.cxf.ext.logging.LoggingFeature;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ @Named("limitedLoggingFeature") // "limitedLoggingFeature" is redundant if the name of the method is the same
+ LoggingFeature limitedLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setLimit(Integer.MAX_VALUE);
+ return loggingFeature;
+ }
+
+ @Produces
+ @ApplicationScoped
+ @Named("prettyLoggingFeature")
+ LoggingFeature prettyLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ return loggingFeature;
+ }
+}and then refer to them by their names prefixed with # in application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features = #limitedLoggingFeature
+# For a client:
+quarkus.cxf.client."myClient".features = #prettyLoggingFeatureStable • Since 0.14.0
+Collect metrics using Micrometer.
+| + + | ++Dropwizard Metrics are unsupported. + They do not work in native mode and the are no tests for JVM mode. + | +
Create a new project using quarkus-cxf-rt-features-metrics on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
The integration of CXF into Quarkus Micrometer ecosystem is implemented using
+CXF MicrometerMetricsProvider
+and io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature.
| + + | ++The sample code snippets used in this section come from the + metrics integration test + in the source tree of CXF Extensions for Quarkus + | +
To enable metrics collection for services, just add io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature
+to your service’s features:
quarkus.cxf.path = /soap
+quarkus.cxf.endpoint."/hello".implementor = io.quarkiverse.cxf.metrics.server.it.HelloServiceImpl
+quarkus.cxf.endpoint."/hello".features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeatureThe same can be done for a client:
+quarkus.cxf.client.hello.wsdl = http://localhost:${quarkus.http.test-port}/soap/hello?wsdl
+quarkus.cxf.client.hello.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/hello
+quarkus.cxf.client.hello.service-interface = io.quarkiverse.cxf.metrics.server.it.HelloService
+quarkus.cxf.client.hello.features = io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeatureFinally, to export the metrics in json format and for Prometheus, add the following dependency to your project
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
+</dependency>and set the following properties
+quarkus.micrometer.export.json.enabled = true
+quarkus.micrometer.export.json.path = metrics/json
+quarkus.micrometer.export.prometheus.path = metrics/prometheusAfter that, you should be able to see some metrics under cxf.server.requests and/or cxf.client.requests in the output of
+the endpoints you configured above:
$ curl http://localhost:8080/q/metrics/json
+metrics: {
+ ...
+ "cxf.server.requests": {
+ "count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 2,
+ "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 64.0
+ },
+ ...
+ "cxf.client.requests": {
+ "count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:808 /soap/hello": 1,
+ "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=http://localhost:8081/soap/hello": 34.0
+ },
+ ...
+}Stable • Since 1.1.0
+Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
+Create a new project using quarkus-cxf-rt-transports-http-hc5 on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-transports-http-hc5</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Once the quarkus-cxf-rt-transports-http-hc5 dependency is available in the classpath,
+CXF will use HttpAsyncClient for asynchronous calls and will continue using HttpURLConnection for synchronous calls.
Asynchronous client invocations require some additional methods in the service endpoint interface. +That code is not generated by default.
+To enable it, you need to create a JAX-WS binding file with enableAsyncMapping set to true:
| + + | ++The sample code snippets used in this section come from the + HC5 integration test + in the source tree of CXF Extensions for Quarkus + | +
<?xml version="1.0"?>
+<bindings
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns="https://jakarta.ee/xml/ns/jaxws"
+ wsdlLocation="CalculatorService.wsdl">
+ <bindings node="wsdl:definitions">
+ <enableAsyncMapping>true</enableAsyncMapping>
+ </bindings>
+</bindings>This file should then be passed to wsdl2java +through its additional-params property:
+quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdl
+quarkus.cxf.codegen.wsdl2java.additional-params = -b,src/main/resources/wsdl/async-binding.xmlOnce the asynchronous stubs are available, it is possible to wrap a client call in io.smallrye.mutiny.Uni as shown below:
package io.quarkiverse.cxf.hc5.it;
+
+import java.util.concurrent.Future;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.eap.quickstarts.wscalculator.calculator.AddResponse;
+import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
+
+import io.quarkiverse.cxf.annotation.CXFClient;
+import io.smallrye.mutiny.Uni;
+
+@Path("/hc5")
+public class Hc5Resource {
+
+ @Inject
+ @CXFClient("myCalculator") // name used in application.properties
+ CalculatorService myCalculator;
+
+ @SuppressWarnings("unchecked")
+ @Path("/add-async")
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<Integer> addAsync(@QueryParam("a") int a, @QueryParam("b") int b) {
+ return Uni.createFrom()
+ .future(
+ (Future<AddResponse>) myCalculator
+ .addAsync(a, b, res -> {
+ }))
+ .map(addResponse -> addResponse.getReturn());
+ }
+
+}Asynchronous clients delivered by this extension leverage ManagedExecutor with a thread pool provided by Quarkus.
+The thread pool can be configured using the quarkus.thread-pool.* family of
+options.
+As a consequence of this, the executor and thread pool related attributes of org.apache.cxf.transports.http.configuration.HTTPClientPolicy are not honored for async clients on Quarkus.
| + + | ++You can see more details about the CXF asynchronous client and how to tune it further in CXF documentation. + | +
🧪Experimental • Since 1.5.3
+| + + | ++This extension is known not to work. Contributions are welcome! + | +
Create a new project using quarkus-cxf-rt-ws-rm on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-rm</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Stable • Since 0.14.0
+Provides CXF framework’s WS-Security implementation.
+Create a new project using quarkus-cxf-rt-ws-security on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-security</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
The CXF framework’s WS-Security implementation is based on WSS4J. The example below shows how to integrate with WSS4J using interceptors.
+| + + | +
+Currently, only the programmatic WSS4JInterceptors are supported. Actions like Timestamp, UsernameToken, Signature, Encryption, etc., can be applied to the interceptors by passing the appropriate configuration properties.
+ |
+
Add the WSS4JInInterceptor to in-interceptors of your web service in application.properties:
quarkus.cxf.endpoint."/rounder".in-interceptors = org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor| + + | ++The sample code snippets used in this section come from the + WS-Security server integration test + in the source tree of CXF Extensions for Quarkus + | +
Then you can configure your WSS4JInInterceptor using CDI like the following:
@ApplicationScoped
+public class WSS4JInInterceptorProducer {
+
+ /** Produced in CxfWssServerTestResource */
+ @ConfigProperty(name = "wss.username", defaultValue = "cxf")
+ String username;
+
+ /** Produced in CxfWssServerTestResource */
+ @ConfigProperty(name = "wss.password", defaultValue = "pwd")
+ String password;
+
+ @Produces
+ @Unremovable
+ @ApplicationScoped
+ WSS4JInInterceptor wssInterceptor() {
+ final CallbackHandler passwordCallback = new CallbackHandler() {
+ @Override
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ for (Callback callback : callbacks) {
+ if (callback instanceof WSPasswordCallback) {
+ final WSPasswordCallback pc = (WSPasswordCallback) callback;
+ if (username.equals(pc.getIdentifier())) {
+ pc.setPassword(password);
+ }
+ return;
+ }
+ }
+ }
+ };
+ final Map<String, Object> props = new HashMap<>();
+ props.put(ConfigurationConstants.ACTION, "UsernameToken");
+ props.put(ConfigurationConstants.PASSWORD_TYPE, "PasswordText");
+ props.put(ConfigurationConstants.USER, username);
+ props.put(ConfigurationConstants.PW_CALLBACK_REF, passwordCallback);
+ return new WSS4JInInterceptor(props);
+ }
+}The corresponding client implementation would be slightly different:
+we will use WSS4JOutInterceptor and out-interceptors in application.properties:
quarkus.cxf.client."wss-client".out-interceptors = org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor| + + | ++The sample code snippets used in this section come from the + WS-Security client integration test + in the source tree of CXF Extensions for Quarkus + | +
Then producing the WSS4JOutInterceptor could look like the following.
@ApplicationScoped
+public class WSS4JOutInterceptorProducer {
+
+ /** Produced in CxfWssClientTestResource */
+ @ConfigProperty(name = "wss.username")
+ String username;
+
+ /** Produced in CxfWssClientTestResource */
+ @ConfigProperty(name = "wss.password")
+ String password;
+
+ @Produces
+ @Unremovable
+ @ApplicationScoped
+ WSS4JOutInterceptor wssInterceptor() {
+ final CallbackHandler passwordCallback = new CallbackHandler() {
+ @Override
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ for (Callback callback : callbacks) {
+ if (callback instanceof WSPasswordCallback) {
+ ((WSPasswordCallback) callback).setPassword(password);
+ }
+ return;
+ }
+ }
+ };
+ final Map<String, Object> props = new HashMap<>();
+ props.put(ConfigurationConstants.ACTION, "UsernameToken");
+ props.put(ConfigurationConstants.PASSWORD_TYPE, "PasswordText");
+ props.put(ConfigurationConstants.USER, username);
+ props.put(ConfigurationConstants.PW_CALLBACK_REF, passwordCallback);
+ props.put(ConfigurationConstants.ADD_USERNAMETOKEN_NONCE, "true");
+ props.put(ConfigurationConstants.ADD_USERNAMETOKEN_CREATED, "true");
+ return new WSS4JOutInterceptor(props);
+ }
+}Please refer to WS-Security and WSS4J documentation for details.
+Stable • Since 1.5.3
+Issue, renew and validate security tokens in context of WS-Trust.
+Create a new project using quarkus-cxf-services-sts on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-services-sts</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Please find an example in the +WS-Trust integration test in the source tree of CXF Extensions for Quarkus +while we are working hard on providing a more user friendly text for this page.
+Stable • Since 1.5.11
+XJC plugins for wsdl2java code generation. +You’ll need to add this extension if you want to use any of the following in +quarkus.cxf.codegen.wsdl2java.additional-params:
+-xjc-Xbg - generate getFoo() instead of isFoo() accessor methods for boolean fields.
-xjc-Xdv - let the generated getter methods return the default value defined in the schema unless the field is set explicitly.
-xjc-Xjavadoc - generate JavaDoc based on xs:documentation present in the schema.
-xjc-Xproperty-listener - add PropertyChangeListener support to the generated beans.
-xjc-Xts - generate toString() methods in model classes.
-xjc-Xwsdlextension - generate beans that can be used directly with WSDL4J as extensors in the WSDL.
| + + | +
+Check the wsdl2java section of User guide for more details about wsdl2java.
+ |
+
Create a new project using quarkus-cxf-xjc-plugins on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-xjc-plugins</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Stable • Since 0.1.0
+Core capabilities for implementing SOAP clients and JAX-WS services.
+Create a new project using quarkus-cxf on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf</artifactId>
+</dependency>| + + | ++Check the User guide and especially its + Dependency management section + for more information about writing applications with CXF Extensions for Quarkus. + | +
Check the following chapters of User guide:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+The default path for CXF resources. +
+
+⚠️ Note that the default value before Quarkus CXF version 2.0.0 was
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Examples: +
+
+
+
+
+
+
+
+Note that file extensions other than
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the file sets selected by
+
+The files from
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+You need to add
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+The universe of class names to which
+
+Examples: +
+
+Let’s say that the application contains two classes annotated with
+
+Then +
+
+
+
+
+
+
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the class names selected by
+
+If you would like to include the generated WSDL files in native image, you need to add them yourself using
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Note that only options related to generation of WSDL from Java are supported currently. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files. +
+
+There are 4 place holders, which can be used in the template: +
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Select the
+
+
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The size in bytes of the chunks of memory allocated when writing data. +
+
+This is a very advanced setting that should only be set if you understand exactly how it affects the output IO operations of the application. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The size of the output stream response buffer in bytes. If a response is larger than this and no content-length is provided then the response will be chunked. +
+
+Larger values may give slight performance increases for large responses, at the expense of more memory usage. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+A comma separated list of glob patterns for selecting WSDL files which should be processed with
+
+Examples: +
+
+
+
+
+
+
+
+Note that file extensions other than
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the file sets selected by
+
+The files from
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of path patterns for selecting WSDL files which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should passed to CXF
+
+You need to add
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting class names which should be processed with
+
+The universe of class names to which
+
+Examples: +
+
+Let’s say that the application contains two classes annotated with
+
+Then +
+
+
+
+
+
+
+
+There is no default value for this option, so
+
+Specifying
+
+Make sure that the class names selected by
+
+If you would like to include the generated WSDL files in native image, you need to add them yourself using
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of glob patterns for selecting java class names which should not be processed with
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of additional command line parameters that should be passed to CXF
+
+Note that only options related to generation of WSDL from Java are supported currently. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A template for the names of generated WSDL files. +
+
+There are 4 place holders, which can be used in the template: +
+
+
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The client service interface class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when configuring a client without annotation
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If
+
+Setting this to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The service endpoint implementation class +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The service endpoint WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The published service endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names or named CDI beans. +
+
+Examples: +
+
+
+
+
+
+In the second case, the
+
+
+
+
+
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The client WSDL path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint namespace +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The client endpoint name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The username for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for HTTP Basic auth +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of fully qualified CXF Feature class names. +
+
+Example: +
+
+
+
+
+
+Note that the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of Handler classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of OutFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The comma-separated list of InFaultInterceptor classes +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Specifies the amount of time, in milliseconds, that the consumer will attempt to establish a connection before it times out. 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies the amount of time, in milliseconds, used when requesting a connection from the connection manager(if appliable). 0 is infinite. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Specifies if the consumer will automatically follow a server issued redirection. (name is not part of standard) +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the maximum amount of retransmits that are allowed for redirects. Retransmits for authorization is included in the retransmit count. Each redirect may cause another retransmit for a UNAUTHORIZED response code, ie. 401. Any negative number indicates unlimited retransmits, although, loop protection is provided. The default is unlimited. (name is not part of standard) +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+If true, the client is free to use chunking streams if it wants, but it is not required to use chunking streams. If false, the client must use regular, non-chunked requests in all cases. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If AllowChunking is true, this sets the threshold at which messages start getting chunked. Messages under this limit do not get chunked. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Specifies the chunk length for a HttpURLConnection. This value is used in java.net.HttpURLConnection.setChunkedStreamingMode(int chunklen). chunklen indicates the number of bytes to write in each chunk. If chunklen is less than or equal to zero, a default value will be used. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Specifies the MIME types the client is prepared to handle (e.g., HTML, JPEG, GIF, etc.) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the language the client desires (e.g., English, French, etc.) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the encoding the client is prepared to handle (e.g., gzip) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the content type of the stream being sent in a post request. (this should be text/xml for web services, or can be set to application/x-www-form-urlencoded if the client is sending form data). +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the Internet host and port number of the resource on which the request is being invoked. This is sent by default based upon the URL. Certain DNS scenarios or application designs may request you to set this, but typically it is not required. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The connection disposition. If close the connection to the server is closed after each request/response dialog. If Keep-Alive the client requests the server to keep the connection open, and if the server honors the keep alive request, the connection is reused. Many servers and proxies do not honor keep-alive requests. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Most commonly used to specify no-cache, however the standard supports a dozen or so caching related directives for requests +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+HTTP Version used for the connection. The "auto" default will use whatever the default is for the HTTPConduit implementation. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+aka User-Agent Specifies the type of browser is sending the request. This is usually only needed when sites have HTML customized to Netscape vs IE, etc, but can also be used to optimize for different SOAP stacks. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider→consumer connection. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the address of proxy server if one is used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the port number used by the proxy server. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Specifies the list of hostnames that will not use the proxy configuration. Examples of value: * "localhost" → A single hostname * "localhost|www.google.com" → 2 hostnames that will not use the proxy configuration * "localhost|www.google.*|*.apache.org" → It’s also possible to use a pattern-like value +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the type of the proxy server. Can be either HTTP or SOCKS. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Username for the proxy authentication +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for the proxy authentication +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Select the
+
+
+
+Environment variable: |
+
+
|
++ |
Here is the list of extensions produced by this project. +Please follow the links under the extension names to learn about how to use them, about their configuration and about any known limitations.
+| Quarkus CXF extension | +Support level | +Since | +Supported standards | +
|---|---|---|---|
Quarkus CXF |
+Stable |
+0.1.0 |
++ |
Quarkus CXF Logging Feature |
+Stable |
+0.14.0 |
++ |
Quarkus CXF Metrics Feature |
+Stable |
+0.14.0 |
++ |
Quarkus CXF WS-Security |
+Stable |
+0.14.0 |
++ |
Quarkus CXF WS-ReliableMessaging |
+Experimental |
+1.5.3 |
++ |
Quarkus CXF Security Token Service (STS) |
+Stable |
+1.5.3 |
++ |
Quarkus CXF HTTP Async Transport |
+Stable |
+1.1.0 |
++ |
Quarkus CXF XJC Plugins |
+Stable |
+1.5.11 |
++ |
Here is a list of CXF modules supported by CXF Extensions for Quarkus. +You should typically not depend on these directly, but rather use some of the extensions listed above that brings the given CXF module as a transitive dependency.
+Out of CXF front ends only the
+JAX-WS front end is fully supported by quarkus-cxf.
The Simple front end may work in JVM mode, but it is not tested properly. +We advise not to use it.
+Out of CXF Data Bindings only the following ones are supported:
+Out of CXF Transports only the following ones are supported:
+quarkus-cxf implements its own custom transport based on Quarkus and Vert.x for serving SOAP endpoints
HTTP client via quarkus-cxf, including
Asynchronous Client HTTP Transport
+via quarkus-cxf-rt-transports-http-hc5
wsdl2Java - see the Generate the Model classes from WSDL
+ section of User guide
java2ws - see the Generate WSDL from Java section of User guide
All CXF WSDL Bindings are supported:
+Here is a list of CXF modules currently not supported by CXF Extensions for Quarkus along with possible alternatives and/or reasons why the given module is not supported.
+| CXF module | +Alternative | +
|---|---|
JAX-RS |
++ |
| + | + |
| + | Use JAXB and JAX-WS |
+
DOSGI |
++ |
JiBX |
+Use JAXB and JAX-WS |
+
Local transport |
+Use HTTP transport |
+
JMS transport |
+Use HTTP transport |
+
JBI |
+Deprecated in CXF use HTTP transport |
+
UDP transport |
+Use HTTP transport |
+
| + | Use HTTP transport |
+
WebSocket transport |
+Use HTTP transport |
+
Clustering |
++ |
CORBA
+ |
+Use JAX-WS |
+
SDO databinding |
++ |
| + | Deprecated in CXF |
+
| + | Use JAX-WS |
+
| + | Use HTTP transport |
+
WS-Transfer runtime |
++ |
Throttling |
+Use load balancer |
+
client-endpoint-url defaultsIf you omit the client-endpoint-url property in application.properties,
+the CXF Quarkus extension will assume that the service is published at http://localhost:8080/{service-path},
+where {service-path} is derived from
Configuration property quarkus.cxf.path (if specified); and the
SEI’s class name in lower case
+Given quarkus.cxf.path = /ws, the default effective client-endpoint-url of the CalculatorService would be
+http://localhost:8080/ws/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
If quarkus.cxf.path is not specified, the client-endpoint-url would be just
+http://localhost:8080/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
In the example above, we configured just a single client called myCalculator.
+Of course, you can configure multiple clients pointing at different URLs and/or implementing different SEIs using multiple identifiers:
cxf.it.calculator.baseUri = http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService
+
+# another client
+quarkus.cxf.client.anotherCalculator.wsdl = https://acme.com/ws/WeatherService?wsdl
+quarkus.cxf.client.anotherCalculator.client-endpoint-url = https://acme.com/ws/WeatherService
+quarkus.cxf.client.anotherCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorServiceBasic authentication for clients is supported by default.
+Just add the following properties to your application.properties:
quarkus.cxf.client.myCalculator.username = user
+quarkus.cxf.client.myCalculator.password = passwordSee the description of
+quarkus.cxf.client.myClient.proxy-* properties.
To globally configure all clients in your application, you can use the example snippet below to configure the
+HttpConduit.
+This allows you to set the HTTPClientPolicy, AuthorizationPolicy, ProxyAuthorizationPolicy or even TLSClientParameters for your clients.
void onStart(@Observes StartupEvent ev) {
+
+ HTTPConduitConfigurer httpConduitConfigurer = new HTTPConduitConfigurer() {
+ public void configure(String name, String address, HTTPConduit c) {
+ AsyncHTTPConduit conduit = (AsyncHTTPConduit)c;
+ // use setter to configure client
+ conduit.getHttpAsyncClient().getCredentialsProvider().setCredentials( AuthScope.ANY,
+ new NTCredentials( USER,PWD, "", DOM ) );
+ conduit.getClient().setAllowChunking( false );
+ conduit.getClient().setAutoRedirect( true );
+ }
+ };
+
+ final Bus bus = BusFactory.getThreadDefaultBus();
+ bus.setExtension(httpConduitConfigurer, HTTPConduitConfigurer.class);
+}To configure the HttpConduit for a single client in your application, use the example snippet below:
@Inject
+ @CXFClient
+ SomePortType portType;
+
+ @PostConstruct
+ void configurePortType() throws NoSuchAlgorithmException, UnrecoverableKeyException, KeyStoreException {
+ final var httpConduit = (HTTPConduit) ClientProxy.getClient(portType).getConduit();
+ final var tlsClientParameters = Optional.ofNullable(httpConduit.getTlsClientParameters()).orElseGet(TLSClientParameters::new);
+ tlsClientParameters.setCertAlias(config.clientCert().keyAlias());
+ tlsClientParameters.setKeyManagers(clientKeyManagers);
+ tlsClientParameters.setTrustManagers(clientTrustManagers);
+ httpConduit.setTlsClientParameters(tlsClientParameters);
+ }Quarkus batch (e.g. periodically scheduled), or command line applications, may do without an HTTP server. +Use the property below to prevent launching the HTTP server at startup:
+quarkus.http.host-enabled = falseCXF client proxies implement java.io.Closeable.
+Therefore, it is important to call ((Closeable) proxy).close() once the client is not needed anymore
+to free all associated system resources, such as threads.
CXF Extensions for Quarkus takes care for closing the clients injected via @io.quarkiverse.cxf.annotation.CXFClient automatically
+as soon as they are disposed by the CDI container.
For client proxies created manually, it is up to you to call ((Closeable) proxy).close():
import java.net.URL;
+import javax.xml.namespace.QName;
+import jakarta.xml.ws.Service;
+import java.io.Closeable;
+
+final URL serviceUrl = new URL("http://localhost/myService?wsdl");
+final QName qName = new QName("http://acme.org/myNamespace", "MyService");
+final Service service = jakarta.xml.ws.Service.create(serviceUrl, qName);
+final MyService proxy = service.getPort(MyService.class);
+
+try {
+ proxy.doSomething();
+} finally {
+ ((Closeable) proxy).close();
+}SOAP requests aimed towards services running on Quarkus can be routed through proxies that generate additional headers
+(e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved.
+In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.
| + + | ++Refer to Quarkus HTTP reference for more details. + | +
CXF Extensions for Quarkus support for various X-Forwarded headers works in line with Quarkus configuration.
| + + | ++Activating this feature leaves the server exposed to several security issues (i.e. information spoofing). Consider activating it only when running behind a reverse proxy. + | +
These are the relevant Quarkus properties and their effect on CXF Extensions for Quarkus:
+quarkus.http.proxy.proxy-address-forwarding - the main switch to enable the rewriting of the request destination parts.
If enabled, the rewriting of the request fields will be effective throughout the whole CXF server stack.
+If enabled, the values passed via X-Forwarded-Proto and X-Forwarded-Port headers
+will be used to set the protocol part and the port part of the URL returned by
+jakarta.servlet.http.HttpServletRequest.getRequestURL() respectively.
If enabled, the value passed via X-Forwarded-For will be returned by jakarta.servlet.ServletRequest.getRemoteAddr().
quarkus.http.proxy.enable-forwarded-host -
+enable the rewriting of the host part of URL returned by jakarta.servlet.http.HttpServletRequest.getRequestURL().
+The actual host name is taken from the header configured via
+quarkus.http.proxy.forwarded-host-header
+(default is X-Forwarded-Host).
quarkus.http.proxy.enable-forwarded-prefix -
+enable the rewriting of the path part of the URL returned by jakarta.servlet.http.HttpServletRequest.getRequestURL()
+and of the URI returned by jakarta.servlet.http.HttpServletRequest.getRequestURI().
+The actual path prefix is taken from the header configured via
+quarkus.http.proxy.forwarded-prefix-header
+(default is X-Forwarded-Prefix).
Here is the most common snippet to copy to your application.properties:
quarkus.http.proxy.proxy-address-forwarding = true
+quarkus.http.proxy.enable-forwarded-host = true
+quarkus.http.proxy.enable-forwarded-prefix = trueOne of the observable effects of these settings is the change of the location value in WSDL served
+on http://localhost:8080/services/my-service?wsdl.
+For example, if the request contains the following headers
X-Forwarded-Proto: https
+X-Forwarded-Host: api.example.com
+X-Forwarded-Port: 443
+X-Forwarded-Prefix: /my-prefixthen the WSDL served on http://localhost:8080/services/my-service?wsdl would contain the following location:
...
+<soap:address location="https://api.example.com:443/my-prefix/services/my-service"/>
+...Camel Quarkus supports CXF since its version 2.12.0. +Under the hood, the implementation is based on CXF Extensions for Quarkus. +Therefore, all functionality available in CXF Extensions for Quarkus is also available in Camel Quarkus.
+Please refer to Camel Quarkus CXF SOAP extension documentation for further details.
+Some issues may appear during the development, testing, and native image building process of your quarkus-cxf project;
+below are some common ones and how to address them.
Sometimes a REST endpoint may be needed in the same project where the Quarkus CXF Extension is used. +The REST endpoint path must be different from the SOAP endpoint path (in order to avoid request +forwarding conflicts between both protocols).
+For example, if a WeatherWebService interface is declared in a WSDL, you can
+begin by creating the org.acme.cxf.WeatherWebServiceImpl class as follows:
package org.acme.cxf;
+
+import ...
+
+@Slf4j
+@WebService(endpointInterface = "org.acme.cxf.WeatherWebService")
+public class WeatherWebServiceImpl implements WeatherWebService {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ private Map<String, DailyTemperature> dailyTempByZipCode = Collections.synchronizedMap(new LinkedHashMap<>());
+
+ public WeatherWebServiceImpl() {
+ this.dailyTempByZipCode.addAll(
+ this.backEndWeatherService.getDailyForecast(Instant.now()));
+ }
+
+ @Override
+ public DailyTemperature estimationTemperatures(String zipCode) {
+ log.info("Daily estimation temperatures forecast called with '{}' zip code paramter", zipCode);
+ return this.dailyTempByZipCode.get(zipCode);
+ }
+}After that, you would need to specify the root context for your CXF web services, as indicated +in the configuration documentation to split the REST (with RESTEasy for example) +and SOAP routes based on their root context paths.
+CXF’s SOAP properties:
+quarkus.cxf.path=/soap
+quarkus.cxf.endpoint."/weather".implementor=org.acme.cxf.WeatherWebServiceImplNow, imagine the following RESTEasy endpoint:
+package org.acme.reasteasy;
+
+import ...
+
+@Slf4j
+@Path("/healthcheck")
+public class HealthCheckResource {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ @GET
+ public Response doHealthCheck() {
+ if(this.backEndWeatherService.isAvailable()) {
+ return Response.ok().build();
+ } else {
+ return Response.status(Response.Status.SERVICE_UNAVAILABLE);
+ }
+ }
+}You can separate your REST endpoint by configuring the REASTEasy path:
+quarkus.resteasy.path=/restYou should now be able to send requests to both your REST and SOAP endpoints deployed within a single project, at:
+http://localhost:8080/soap/weather for SOAP
+Sometimes the wsdl2java autogenerated Java classes may not be +fully compatible with GraalVM due to non ASCII characters getting included in the code. Similar exceptions to +the below may appear during native image builds.
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] compile: 161 459,15 ms, 8,54 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] image: 158 272,73 ms, 8,43 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] write: 205,82 ms, 8,43 GB
+Fatal error:com.oracle.svm.core.util.VMError$HostedError: java.lang.RuntimeException: oops : expected ASCII string! com.oracle.svm.reflect.OperationOrderStatusType_CRÉÉ_f151156b0d42ecdbdfb919501d8a86dda8733012_1456.hashCode
+ at com.oracle.svm.core.util.VMError.shouldNotReachHere(VMError.java:72)Below is an example of auto-generated non ASCII characters in a Java class:
+@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Cr\u00e9\u00e9")
+ CRÉÉ("Cr\u00e9\u00e9"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de r\u00e9ponse")
+ EN_ATTENTE_DE_RÉPONSE("En attente de r\u00e9ponse"),
+ @XmlEnumValue("Attribu\u00e9")
+ ATTRIBUÉ("Attribu\u00e9"),
+ @XmlEnumValue("Clotur\u00e9")
+ CLOTURÉ("Clotur\u00e9"),
+ @XmlEnumValue("Annul\u00e9")
+ ANNULÉ("Annul\u00e9");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Anything starting with \u will be a problem. Consequently the following refactoring is needed:
@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Créé")
+ CREE("Créé"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de réponse")
+ EN_ATTENTE_DE_REPONSE("En attente de réponse"),
+ @XmlEnumValue("Attribué")
+ ATTRIBUE("Attribué"),
+ @XmlEnumValue("Cloturé")
+ CLOTURE("Cloturé"),
+ @XmlEnumValue("Annulé")
+ ANNULE("Annulé");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Both contract first and code first development modes are fully supported by CXF Extensions for Quarkus.
+A SOAP service is described by WSDL.
+It is a contract defining operations, their parameters and return values, etc.
+WSDL is rich enough to be used for generating the code of a complete client.
+CXF provides the wsdl2java utility for that.
CXF Extensions for Quarkus wraps wsdl2java in the quarkus-cxf extension so you do not need to use it directly.
Please follow the Generate the Model classes from WSDL section of the user guide +for more details about how to use it.
+You may also want to check the CXF Developing a Consumer as a general introduction.
+When implementing a service the generation of Java code from WSDL
+may also come in handy.
+wsdl2java can generate the model classes (with JAXB annotations)
+and service interfaces (with JAX-WS annotations) for you.
+Your task is then to provide implementations for those interfaces.
You may want to check the WSDL First Service Development +section of CXF documentation for a better understanding of the underlying concepts.
+Another valid option at your disposal is to write your service in Java, using JAX-WS and JAXB. +Then you have two options how to obtain the WSDL contract:
+Start your service and point your clients at http://your-host/your-service?wsdl
+Generate the WSDL document from Java classes at build time
+| + + | ++Check the Code first development section of CXF documentation for further information. + | +
This guide explains how to set up a new project for a Quarkus application hosting a CXF client or server or both.
+Please read the Prerequisites section of Quarkus getting started guide.
+In addition to that, you may need
+GraalVM with the native-image command installed and the GRAALVM_HOME environment variable set.
+See Building a native executable section of the Quarkus
+documentation.
If you are on Linux, a container runtime like docker is sufficient for the native mode too.
+Use -Pnative -Dquarkus.native.container-build=true instead of -Pnative if you choose this option.
New project skeletons can be generated using code.quarkus.io.
+
+Here you can select the extensions that you want to work with.
+For a simple Hello world Web service or client the quarkus-cxf extension is enough.
Click the blue Generate your application button to download a basic skeleton project.
Unpack the zip file and import the project the into your favorite IDE.
+CXF Extensions for Quarkus is a part of Quarkus Platform since Quarkus Platform version 3.1.0.Final. +Among other things, this means that code.quarkus.io +and other Quarkus development tools generate projects with proper dependency management:
+<project ...>
+ ...
+ <properties>
+ ...
+ <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
+ <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
+ <quarkus.platform.version><!-- Check the latest https://repo1.maven.org/maven2/io/quarkus/platform/quarkus-cxf-bom/ --></quarkus.platform.version>
+ </properties>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>${quarkus.platform.artifact-id}</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>quarkus-cxf-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+...You should always take care to import the same version of io.quarkus.platform:quarkus-bom and io.quarkus.platform:quarkus-cxf-bom into your project.
+That’s the most reliable way to get compatible versions of Quarkus, CXF, CXF Extensions for Quarkus and all their transitive dependencies.
CXF interceptors and CXF features can be added to both your client or server using either annotations or application.properties configurations.
While CXF provides a number of out of the box embedded interceptors and features, you can also integrate your custom developed implementations.
+Annotations can be used on either the service interface or implementor classes.
+@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@org.apache.cxf.interceptor.InInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor" })
+@org.apache.cxf.interceptor.OutInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor","org.acme.Test3Intercetpor" })
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}You may also define your configurations in the application.properties file.
quarkus.cxf.endpoint."/greeting-service".features=org.apache.cxf.ext.logging.LoggingFeature
+quarkus.cxf.endpoint."/greeting-service".in-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".out-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".in-fault-interceptors=org.acme.Test2Interceptor,org.acme.Test3Intercetpor
+quarkus.cxf.endpoint."/greeting-service".out-fault-interceptors=org.acme.Test1Intercetpor| + + | ++Both feature and interceptor classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class. + | +
The integration-tests folder of the codebase provides various examples
+that demonstrate how to use this extension extensively.
In this guide we explain how to create a simple Quarkus application acting as a client of a remote Web service.
+| + + | ++Follow the Project creation guide before proceeding here. + | +
First, we need some remote Web service to connect to. +We can use a simple Calculator Web service running in a container for that purpose.
+$ docker run -p 8082:8080 quay.io/l2x6/calculator-ws:1.0Once the container is up and running, we can inspect its WSDL
+$ curl -s http://localhost:8082/calculator-ws/CalculatorService?wsdl
+<?xml version="1.0" ?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="CalculatorService" targetNamespace="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+
+ ...
+
+ <wsdl:binding name="CalculatorServiceSoapBinding" type="tns:CalculatorService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"></soap:binding>
+ <wsdl:operation name="add">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="add">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="addResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+ <wsdl:operation name="subtract">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="subtract">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="subtractResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+
+ ...
+
+ </wsdl:binding>
+
+ ...
+
+</wsdl:definitions>As you can see in the WSDL, the service offers some basic arithmetic operations, such as add, subtract, etc.
Let’s test it with curl:
$ curl -s \
+ -X POST \
+ -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
+ <Body>
+ <add xmlns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <arg0 xmlns="">7</arg0> (1)
+ <arg1 xmlns="">4</arg1>
+ </add>
+ </Body>
+ </Envelope>' \
+ http://localhost:8082/calculator-ws/CalculatorService
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:addResponse xmlns:ns2="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <return>11</return> (2)
+ </ns2:addResponse>
+ </soap:Body>
+</soap:Envelope>| 1 | +The request to add 7 and 4 |
+
| 2 | +11 - return value of the operation |
+
Now let’s have a look how we can get the client inside a Quarkus application.
+First, we need the Service Endpoint Interface (SEI) and all other model classes it requires.
+There are several ways to get them:
+Write by hand
+Copy from the Web Sevice project, if it is written in Java
+Have a Maven artifact containing the model classes, perhaps it is offered by the Service project
+Generate the model classes from WSDL
+The last option tends to be the easiest and most flexible for client applications.
+| + + | ++If you want to use this approach, please first follow the Generate Java from WSDL section and then continue with the next steps. + | +
In our case, the Service Endpoint Interface (SEI) is org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService.
As usual on Quarkus, we can obtain an instance of it via CDI.
+To make it testable easily, we’ll wrap it in a REST service:
+package io.quarkiverse.cxf.client.it;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
+
+import io.quarkiverse.cxf.annotation.CXFClient;
+
+@Path("/cxf/calculator-client")
+public class CxfClientRestResource {
+
+ @CXFClient("myCalculator") (1)
+ CalculatorService myCalculator;
+
+ @GET
+ @Path("/add")
+ @Produces(MediaType.TEXT_PLAIN)
+ public int add(@QueryParam("a") int a, @QueryParam("b") int b) {
+ return myCalculator.add(a, b); (2)
+ }
+
+}| 1 | +Let the CDI container inject an instance of the client. @CXFClient("myCalculator") is actually equivalent to @Inject @CXFClient("myCalculator") |
+
| 2 | +Invoke the add operation thus calling the remote Web service |
+
Is this all we need for the client to work?
+- No, in addition to the above, we need to tell a few other things to the CXF Quarkus extension in application.properties:
cxf.it.calculator.baseUri=http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService| + + | ++All client configuration properties are documented in the Configuration properties reference. + | +
With all the above files in place, we should be able to start the application in Quarkus dev mode
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and test it by sending some requests to it:
+$ curl -s 'http://localhost:8080/cxf/calculator-client/add?a=5&b=6'
+11where 11 is the correct result of adding 5 and 6.
In this guide we explain how to create a Quarkus application exposing a simple SOAP Web service.
+| + + | ++Follow the Project creation guide before proceeding here. + | +
Having the pom.xml in place, you can add a simple Hello world! Web service in src/main/java.
| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
First add the service interface:
+package io.quarkiverse.cxf.it.server;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+/**
+ * The simplest Hello service.
+ */
+@WebService(name = "HelloService", serviceName = "HelloService")
+public interface HelloService {
+
+ @WebMethod
+ String hello(String text);
+
+}and then the implementation:
+package io.quarkiverse.cxf.it.server;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+/**
+ * The simplest Hello service implementation.
+ */
+@WebService(serviceName = "HelloService")
+public class HelloServiceImpl implements HelloService {
+
+ @WebMethod
+ @Override
+ public String hello(String text) {
+ return "Hello " + text + "!";
+ }
+
+}For the implementation to get exposed under a certain path, you need to add the following configuration to application.properties:
# The context path under which all services will be available
+quarkus.cxf.path = /soap
+
+# Publish "HelloService" under the context path /${quarkus.cxf.path}/hello
+quarkus.cxf.endpoint."/hello".implementor = io.quarkiverse.cxf.it.server.HelloServiceImpl
+quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature| + + | ++All configuration properties are documented in the Configuration properties reference. + | +
With these files in place, you can start Quarkus in dev mode:
$ mvn quarkus:devThis will compile the project and start the application on the background.
+You can test the service using curl or some other SOAP client.
First let’s have a look at the auto-generated WSDL under http://localhost:8080/soap/hello?wsdl:
+$ curl http://localhost:8080/soap/hello?wsdl
+<?xml version='1.0' encoding='UTF-8'?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://server.it.cxf.quarkiverse.io/"
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http"
+ name="HelloService" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <wsdl:types>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://server.it.cxf.quarkiverse.io/" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <xsd:element name="hello" type="tns:hello"/>
+ <xsd:complexType name="hello">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="arg0" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+ <xsd:element name="helloResponse" type="tns:helloResponse"/>
+ <xsd:complexType name="helloResponse">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="return" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+</xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="helloResponse">
+ <wsdl:part element="tns:helloResponse" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="hello">
+ <wsdl:part element="tns:hello" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:portType name="HelloService">
+ <wsdl:operation name="hello">
+ <wsdl:input message="tns:hello" name="hello">
+ </wsdl:input>
+ <wsdl:output message="tns:helloResponse" name="helloResponse">
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="HelloServiceSoapBinding" type="tns:HelloService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+ <wsdl:operation name="hello">
+ <soap:operation soapAction="" style="document"/>
+ <wsdl:input name="hello">
+ <soap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="helloResponse">
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="HelloService">
+ <wsdl:port binding="tns:HelloServiceSoapBinding" name="HelloServicePort">
+ <soap:address location="http://localhost:8080/soap/hello"/>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions>Second, let’s send a SOAP request to the service:
+$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+ </soap:Envelope>' \
+ http://localhost:8080/soap/hello
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return>Hello World!</return>
+ </ns1:helloResponse>
+ </soap:Body>
+</soap:Envelope>Note the expected <return>Hello World!</return> in the SOAP response.
Sometimes it may come in handy to be able to inspect the SOAP messages received or sent by the server or client.
+This is easily doable by adding the quarkus-cxf-rt-features-logging extension to pom.xml.
| + + | ++Try to do that while Quarkus dev mode is running. + You should see the application being recompiled and redeployed upon saving your changes in the source tree. + | +
pom.xml<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-logging</artifactId>
+</dependency>application.propertiesquarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeatureAfter that you can send a new SOAP request and see some SOAP payloads in the application console:
+2023-01-11 22:12:21,315 INFO [org.apa.cxf.ser.Hel.REQ_IN] (vert.x-worker-thread-0) REQ_IN
+ Address: http://localhost:8080/soap/hello
+ HttpMethod: POST
+ Content-Type: text/xml;charset=UTF-8
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {Accept=*/*, User-Agent=curl/7.79.1, content-type=text/xml;charset=UTF-8, Host=localhost:8080, Content-Length=203, x-quarkus-hot-deployment-done=true}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+</soap:Envelope>
+
+
+2023-01-11 22:12:21,327 INFO [org.apa.cxf.ser.Hel.RESP_OUT] (vert.x-worker-thread-0) RESP_OUT
+ Address: http://localhost:8080/soap/hello
+ Content-Type: text/xml
+ ResponseCode: 200
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/"><return>Hello World!</return></ns1:helloResponse></soap:Body></soap:Envelope>You may want to proceed with packaging your application for running on a JVM or natively.
+quarkus-cxf extension supports generating Java classes from WSDL during Quarkus code generation phase.
| + + | ++The code snippets shown in this section come from the + client integration test + in the source tree of CXF Extensions for Quarkus. + You may want to check it as an executable example. + | +
You need to set up a couple of things for CXF code generation to work:
+Have io.quarkiverse.cxf:quarkus-cxf dependency in your project
For Maven projects, the generate-code goal needs to be present in the configuration of quarkus-maven-plugin:
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>For Gradle projects no additional configurarion of io.quarkus plugin is needed
Put your WSDL files under src/main/resources or src/test/resources or any subdirectory thereof.
Your WSDL file names must end with .wsdl
Set quarkus.cxf.codegen.wsdl2java.includes
+configuration property
+to a pattern matching the WSDL files you wish to process.
+If you want to process all WSDL files under src/main/resources/wsdl or src/test/resources/wsdl, set it as follows:
quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdlThis will generate Java classes in target/generated-sources/wsdl2java or
+target/generated-test-sources/wsdl2java directory.
+They will be automatically picked by the compiler plugin there.
+Hence we are free to refer to them from our application or test code.
Note that quarkus-cxf code generation uses the wsdl2Java utility
+from CXF under the hood. wsdl2Java is called separately for each WSDL file selected by includes and excludes.
Passing custom parameters to wsdl2java is possible through
+quarkus.cxf.codegen.wsdl2java.additional-params
+configuration parameter.
If you need different additional-params for each WSDL file, you may want to define a separate named parameter set for
+each one of them. Here is an example:
# Parameters for foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.includes = wsdl/foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.additional-params = -wsdlLocation,wsdl/foo.wsdl
+# Parameters for bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.includes = wsdl/bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.additional-params = -wsdlLocation,wsdl/bar.wsdl,-xjc-Xts| + + | +
+Add io.quarkiverse.cxf:quarkus-cxf-xjc-plugins dependency to your project to be able to use
+ -xjc-Xbg, -xjc-Xdv, -xjc-Xjavadoc, -xjc-Xproperty-listener, -xjc-Xts and -xjc-Xwsdlextension
+ wsdl2java parameters.
+ |
+
If the WSDL served by your service at http://your-host/your-service?wsdl is not enough
+because you e.g. want to distribute it as a Maven artifact,
+then you can use java2ws to generate the WSDL document at build time.
You do not need to invoke the java2ws tool provided by CXF directly,
+neither you have to use the cxf-java2ws-plugin.
quarkus-cxf wraps java2ws and so you can configure it in application.properties
+as any other aspect of your application.
Here is an example:
+| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
quarkus.cxf.java2ws.includes = io.quarkiverse.cxf.it.server.HelloService,io.quarkiverse.cxf.it.server.FaultyHelloService
+quarkus.cxf.java2ws.wsdl-name-template = %TARGET_DIR%/Java2wsTest/%SIMPLE_CLASS_NAME%-from-java2ws.wsdlHere we have instructed java2ws to generate WSDLs for two interfaces,
+namely HelloService and FaultyHelloService.
Note that the Service interfaces must be annotated with jakarta.xml.ws.WebService to be selected for java2ws processing.
The two generated WSDL documents will be stored as target/Java2wsTest/FaultyHelloService-from-java2ws.wsdl
+and target/Java2wsTest/HelloService-from-java2ws.wsdl respectively.
| + + | +
+Unlike wsdl2java which is executed within Quarkus source generation phase,
+ java2ws is a part Quarkus augmentation that happens after compilation.
+ The input of java2ws are, after all, Java class files.
+ Hence you do not need to add <goal>generate-code</goal> to quarkus-maven-plugin
+ for java2ws.
+ |
+
quarkus.cxf.java2ws.* configuration properties of quarkus-cxf
This User guide explains typical use cases of CXF Extensions for Quarkus.
+You may want to start with some of the following topics:
+As an alternative to the @HandlerChain annotation,
+JAX-WS Handlers can be added
+to both your client or server via application.properties:
# A web service endpoint with multiple Handler classes
+quarkus.cxf.endpoint."/greeting-service".handlers=org.acme.MySOAPHandler,org.acme.AnotherSOAPHandler
+
+# A web service client with a single Handler
+quarkus.cxf.client."greeting-client".handlers=org.acme.MySOAPHandlerWhere MySOAPHandler could look like below:
import jakarta.xml.ws.handler.soap.SOAPHandler;
+import jakarta.xml.ws.handler.soap.SOAPMessageContext;
+
+public class MySOAPHandler implements SOAPHandler {
+
+ public boolean handleMessage(SOAPMessageContext messageContext) {
+ SOAPMessage msg = messageContext.getMessage();
+ return true;
+ }
+ // other methods
+} | + + | +
+The SOAPHandler classes will be attempted to be loaded via CDI first.
+ If no CDI beans are available for the given type, then the no parameters constructor will used
+ to instantiate each class.
+ |
+
JAX-WS Providers are fully supported, and can be implemented as shown below.
+Given the following sample Provider implementation:
import jakarta.xml.transform.stream.StreamSource;
+import jakarta.xml.ws.BindingType;
+import jakarta.xml.ws.Provider;
+import jakarta.xml.ws.Service;
+import jakarta.xml.ws.ServiceMode;
+import jakarta.xml.ws.WebServiceProvider;
+import java.io.StringReader;
+
+@WebServiceProvider
+@ServiceMode(value = Service.Mode.PAYLOAD)
+public class StreamSourcePayloadProvider implements Provider {
+
+ public StreamSourcePayloadProvider() {
+ }
+
+ public StreamSource invoke(StreamSource request) {
+ String payload = StaxUtils.toString(request);
+
+ // Do some interesting things ...
+
+ StreamSource response = new StreamSource(new StringReader(payload));
+ return response;
+ }
+} The application.properties can be configured as shown below.
# A web service endpoint with the Provider implementation class
+quarkus.cxf.endpoint."/stream-source".implementor=org.acme.StreamSourcePayloadProvider| + + | +
+Provider classes will be attempted to be loaded via CDI first, and if no CDI beans are available, then the constructor with no parameters will be invoked to instantiate each class.
+ |
+
In this chapter, we explain how to package a Quarkus CXF application for running on a JVM or for running it natively.
+In the introductory guides for SOAP client and SOAP service, we worked only in Quarkus dev mode:
+Quarkus tooling was running on the background,
+watching for changes in our workspace, recompiling and reloading the application as needed.
How do we run the application on a JVM once we are done with the development?
+First we need to package it with Maven:
+$ mvn packageThe libraries needed to run the application on a JVM can be found in target/quarkus-app directory:
$ ls -lh target/quarkus-app
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 app
+drwxr-xr-x. 4 ppalaga ppalaga 4.0K Jan 12 22:29 lib
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 quarkus
+-rw-r--r--. 1 ppalaga ppalaga 6.1K Jan 12 22:29 quarkus-app-dependencies.txt
+-rw-r--r--. 1 ppalaga ppalaga 678 Jan 12 22:29 quarkus-run.jarWe can start the application as follows:
+$ java -jar target/quarkus-app/quarkus-run.jarYou can send some SOAP requests using curl to make sure that the application works.
Quarkus offers first class support for building GraalVM native images +and CXF Extensions for Quarkus fully honors that promise too.
+| + + | ++GraalVM native images are platform specific executable files that you can run directly without a JVM. + They boot faster and spend less memory compared to running the same application in JVM mode. + | +
The pom.xml file generated by code.quarkus.io
+contains the native profile needed for building the native image:
<profile>
+ <id>native</id>
+ <activation>
+ <property>
+ <name>native</name>
+ </property>
+ </activation>
+ <properties>
+ <skipITs>false</skipITs>
+ <quarkus.package.type>native</quarkus.package.type>
+ </properties>
+</profile>Further, as mentioned above, you need the GraalVM native-image tool.
You should either have it installed locally and have GRAALVM_HOME environment variable set properly,
+or — if you only need to produce a Linux native executable — you can use docker.
# Make sure $GRAALVM_HOME is set properly
+$ echo $GRAALVM_HOME
+/home/{user}/.sdkman/candidates/java/{major}.{minor}.r{java-version}-grl
+
+# Produce the native executable
+mvn package -Pnative| + + | +
+Quarkus is quite picky about the GraalVM version.
+ When using the local installation, always make sure that you use the version preferred by Quarkus.
+ You can do that by opening quarkus-bom imported in your pom.xml and searching for graalvm there.
+ If you use Docker, Quarkus takes care for pulling the right version for you.
+ |
+
docker# Produce the native executable
+mvn package -Pnative -Dquarkus.native.container-build=trueThis can take a minute or so for a simple application.
+When the build is done, the native executable should be available in target directory:
$ ls -l target
+...
+-rwxr-xr-x. 1 ppalaga ppalaga 71M Jan 11 22:42 quarkus-cxf-integration-test-server-1.8.0-SNAPSHOT-runner
+...Note the x permission on Linux and the size of just 71 MB.
You can run it as follows:
+$ target/*-runner
+...
+INFO [io.quarkus] (main) quarkus-cxf-integration-test-server 1.8.0-SNAPSHOT native (powered by Quarkus
+2.15.2.Final) started in 0.042s. Listening on: http://0.0.0.0:8080
+...Again, you can send some SOAP requests using curl to make sure that the native executable works.
Do not forget to compare the memory usage, time to first request and other performance metrics +with the stack you used before and share your results!
+You may also refer to the links below which contain tips on how to work with native images.
+Please refer to Quarkus Container image guide.
+Our introductory guides for Quarkus SOAP client +and SOAP service dealt with services +having only primitive parameters and return values such as integers and strings. +Let’s have a look at passing and receiving more complex objects.
+As an example, let’s create an application for managing fruits.
+| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of CXF Extensions for Quarkus + | +
Because our representation of fruit is supposed to be a complex, let’s model it as a Java bean with a couple of attributes:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Objects;
+
+import jakarta.xml.bind.annotation.XmlElement;
+import jakarta.xml.bind.annotation.XmlRootElement;
+import jakarta.xml.bind.annotation.XmlType;
+
+@XmlType(name = "Fruit")
+@XmlRootElement
+public class Fruit {
+
+ private String name;
+
+ private String description;
+
+ public Fruit() {
+ }
+
+ public Fruit(String name, String description) {
+ this.name = name;
+ this.description = description;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ @XmlElement
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ @XmlElement
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.getName(), this.getName());
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.getName());
+ }
+}As you may have noticed, we have used some JAXB annotations,
+such as @XmlElement, @XmlRootElement and @XmlType.
+This is to control the serialization and deserialization of the bean from and to XML.
JAXB is a reflection based serialization framework.
+When learning about GraalVM native images, one of the first things you typically hear is
+that you have to register classes, fields and methods for reflection at build time.
+With plain GraalVM you’d have to do this through reflection-config.json manually.
+Well, at least for the classes you have written yourself.
+Not so with Quarkus. quarkus-jaxb extension (which quarkus-cxf depends on)
+is able to scan your application’s class path for classes annotated with JAXB annotations
+and register them for reflection automatically.
Hence working with complex payloads on Quarkus is not different from stock CXF. +The JAXB serialization and deserialization will work out of the box without any additional configuration.
+The Service Endpoint Interface (SEI) for managing fruits might look like the following:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Set;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+@WebService
+public interface FruitService {
+
+ @WebMethod
+ Set<Fruit> list();
+
+ @WebMethod
+ Set<Fruit> add(Fruit fruit);
+
+ @WebMethod
+ Set<Fruit> delete(Fruit fruit);
+}We can implement the SEI as simply as possible:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+import jakarta.jws.WebService;
+
+@WebService(serviceName = "FruitService")
+public class FruitServiceImpl implements FruitService {
+
+ private Set<Fruit> fruits = Collections.synchronizedSet(new LinkedHashSet<>());
+
+ public FruitServiceImpl() {
+ fruits.add(new Fruit("Apple", "Winter fruit"));
+ fruits.add(new Fruit("Pineapple", "Tropical fruit"));
+ }
+
+ @Override
+ public Set<Fruit> list() {
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> add(Fruit fruit) {
+ fruits.add(fruit);
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> delete(Fruit fruit) {
+ fruits.remove(fruit);
+ return fruits;
+ }
+}application.propertiesThe implementation is pretty straightforward and you just need to define your endpoints using the application.properties.
quarkus.cxf.endpoint."/fruits".implementor = io.quarkiverse.cxf.it.server.FruitServiceImpl
+quarkus.cxf.endpoint."/fruits".features = org.apache.cxf.ext.logging.LoggingFeaturedev mode and curlHaving the above files in place, you can start Quarkus tooling in dev mode:
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and then check whether the service is working by invoking its list operation:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soapenv:Envelope
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <soapenv:Body>
+ <ns1:list/>
+ </soapenv:Body>
+ </soapenv:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:listResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ </ns1:listResponse>
+ </soap:Body>
+</soap:Envelope>As you can see, the endpoint has returned the two fruits Apple and Pineapple available by default.
Now let’s add another fruit, say an Orange:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:add xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <arg0>
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </arg0>
+ </ns2:add>
+ </soap:Body></soap:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:addResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </return>
+ </ns1:addResponse>
+ </soap:Body>
+</soap:Envelope>We can see Orange having been added in the returned list as expected.
You may want to proceed with packaging your application for running on a JVM or natively.
+By default, a SOAP 1.1 binding is used. In order to switch to SOAP 1.2 and/or support MTOM, the config quarkus.cxf.endpoint.key.soap-binding must be set to one of the following values:
Binding |
+Property Value |
+
SOAP 1.1 |
++ |
SOAP 1.2 |
++ |
SOAP 1.1 with MTOM |
++ |
SOAP 1.2 with MTOM |
++ |
git
GraalVM with native-image command installed and GRAALVM_HOME environment variable set, see
+Building a native executable section of the Quarkus
+documentation.
If your are on Linux, docker is sufficient for the native mode too. Use -Pnative,docker instead of -Pnative
+if you choose this option.
Java 17
+Maven (mvn), Maven Daemon (mvnd for fast builds), or Maven Wrapper (mvnw)
Checkout the code
+$ git clone https://github.com/quarkiverse/quarkus-cxf.git -o upstream
+$ cd quarkus-cxfA fast build without tests and various checks:
+$ mvn clean install -DskipTests -Dquarkus.build.skipA build with integration tests in the JVM mode only:
+$ mvn clean installA build with integration tests in both the JVM mode and the native mode:
+$ mvn clean install -Pnativequarkus-cxfTo release version 1.2.3 and set the next development version to 1.2.4-SNAPSHOT, run the following:
$ cd quarkus-cxf
+$ ./release.sh 1.2.3 1.2.4-SNAPSHOTWhat it does:
+Sets the current-version and release-version keys in .github/project.yml file to values passed via CLI parameters
Commits the changes
+Pushes a new branch called trigger-release-1.2.3 to upstream
After that, you need to do the following:
+Create a pull request from the above branch
+Merge it (without waiting for the CI jobs to pass)
+Watch the associated Quarkiverse Release job
+Once all artifacts are available on Maven Central, upgrade the Quarkus CXF version in Quarkus Platform:
+$ export NEW_VERSION=1.2.3
+$ cd projects
+$ git clone https://github.com/quarkusio/quarkus-platform.git -o upstream
+$ cd quarkus-platform
+# Upgrade the version in the root pom
+$ sed -i 's|<quarkus-cxf.version>[^<]*</quarkus-cxf.version>|<quarkus-cxf.version>'$NEW_VERSION'</quarkus-cxf.version>|' pom.xml
+# regenerate the BOMs (may take tens of minutes on a slow internet connection)
+$ ./mvnw -Dsync
+# Install quarkus-bom and quarkus-cxf-bom to local Maven repository
+$ cd generated-platform-project
+$ ../mvnw install -pl quarkus/bom,quarkus-cxf/bom,quarkus-universe/bom -am
+# Make sure the generated tests pass
+$ cd quarkus-cxf/integration-tests
+$ ../../../mvnw verify -Pnative
+# If all is green, commit changes and send a PR
+$ git checkout -b upgrade-qcxf-$NEW_VERSION
+$ git add -A
+$ git commit -m "Upgrade to Quarkus CXF $NEW_VERSION"
+$ git push your-fork upgrade-qcxf-$NEW_VERSIONNow create a new pull request out of your upgrade-qcxf-$NEW_VERSION branch.
Watch whether the CI jobs pass against your new pull request.
+This project aims at porting Apache CXF to Quarkus runtime +including full support for producing GraalVM native images.
+| + + | ++While Apache CXF implements wide range of standards and specifications, +Quarkus CXF is currently focusing only on supporting the ones related to +Simple Object Access Protocol (SOAP) +and Java API for XML Web Services (JAX-WS). +Refer to Reference to learn which parts of CXF are supported. + | +
The documentation is divided in two major parts:
+User guide - explains the typical usage of Quarkus CXF
+Reference - the full list of supported specifications, use cases and configuration options
+Feel free to start a discussion +or open an issue in the GitHub repository in case you need support. +The following general guidelines can be used to determine whether to start a discussion or open an issue.
+Bug reports
+Feature requests
+Q&A and general communication
+RFCs for new features
+Contributions and pull requests from the community are welcome!
+Stable • Since 2.7.0
+Generate OpenTelemetry traces.
+| + + | ++OpenTelemetry Metrics and Logging are not supported yet on neither Quarkus nor CXF side, + hence Quarkus CXF cannot support them either. + | +
Create a new project using quarkus-cxf-integration-tracing-opentelemetry on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-integration-tracing-opentelemetry</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
This extension builds on top of org.apache.cxf.tracing.opentelemetry.OpenTelemetryFeature (for service endpoints)
+and org.apache.cxf.tracing.opentelemetry.OpenTelemetryClientFeature (for clients).
+Instances of these are created and configured internally using the instance of io.opentelemetry.api.OpenTelemetry
+provided by Quarkus OpenTelemetry.
The tracing is enabled by default for all clients and service endpoints created by Quarkus CXF,
+unless you disable it explicitly via quarkus.cxf.otel.enabled-for, quarkus.cxf.client."clients".otel.enabled
+or quarkus.cxf.endpoint."endpoints".otel.enabled.
There is an integration test
+covering OpenTelemetry in the Quarkus CXF source tree.
+It is using InMemorySpanExporter from io.opentelemetry:opentelemetry-sdk-testing,
+so that the spans can be inspected from tests easily.
+Refer to Quarkus OpenTelemetry guide for information
+about other supported span exporters and collectors.
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
+| Configuration property | +Type | +Default | +
|---|---|---|
| + |
|
+
|
+
+
+Specifies whether the OpenTelemetry tracing will be enabled for clients, services, both or none. This global setting
+can be overridden per client or service endpoint using the
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
Stable • Since 0.14.0
+Collect metrics using Micrometer.
+| + + | ++Dropwizard Metrics are not supported. + They do not work in native mode and the are no tests for JVM mode. + | +
Create a new project using quarkus-cxf-rt-features-metrics on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
The integration of CXF into the Quarkus Micrometer ecosystem is implemented using
+io.quarkiverse.cxf.metrics.QuarkusCxfMetricsFeature.
+As long as your application depends on quarkus-cxf-rt-features-metrics,
+an instance of QuarkusCxfMetricsFeature is created internally
+and enabled by default for all clients and service endpoints created by Quarkus CXF.
+You can disable it via quarkus.cxf.metrics.enabled-for, quarkus.cxf.client."clients".metrics.enabled
+and quarkus.cxf.endpoint."endpoints".metrics.enabled properties documented below.
There is an integration test +covering Micrometer Metrics in the Quarkus CXF source tree.
+Unsurprisingly, it depends on quarkus-cxf-rt-features-metrics
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-metrics</artifactId>
+</dependency>It is using quarkus-micrometer-registry-prometheus extension to export the metrics in JSON format and for Prometheus:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
+</dependency>The following configuration is needed to be able to inspect the collected metrics over a REST endpoint:
+quarkus.micrometer.export.json.enabled = true
+quarkus.micrometer.export.json.path = metrics/json
+quarkus.micrometer.export.prometheus.path = metrics/prometheusHaving all the above in place, you can start the application in Dev mode:
+$ mvn quarkus:devNow send a request to the HelloService:
$ curl \
+ -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns2:helloResponse xmlns:ns2="http://it.server.metrics.cxf.quarkiverse.io/"><return>Hello Joe!</return></ns2:helloResponse></soap:Body></soap:Envelope>' \
+ -H 'Content-Type: text/xml' \
+ -X POST \
+ http://localhost:8080/metrics/client/helloAfter that, you should see some metrics under cxf.server.requests in the output of the endpoint you configured above:
$ curl http://localhost:8080/q/metrics/json
+metrics: {
+ ...
+ "cxf.server.requests": {
+ "count;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 2,
+ "elapsedTime;exception=None;faultCode=None;method=POST;operation=hello;outcome=SUCCESS;status=200;uri=/soap/hello": 64.0
+ },
+ ...
+}Configuration property fixed at build time. All other configuration properties are overridable at runtime.
+| Configuration property | +Type | +Default | +
|---|---|---|
| + |
|
+
|
+
+
+Specifies whether the metrics collection will be enabled for clients, services, both or none. This global setting can
+be overridden per client or service endpoint using the
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
Stable • Since 1.1.0
+Implement async SOAP Clients using Apache HttpComponents HttpClient 5.
+Create a new project using quarkus-cxf-rt-transports-http-hc5 on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-transports-http-hc5</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
Once the quarkus-cxf-rt-transports-http-hc5 dependency is available in the classpath,
+CXF will use HttpAsyncClient for asynchronous calls and will continue using HttpURLConnection for synchronous calls.
Asynchronous client invocations require some additional methods in the service endpoint interface. +That code is not generated by default.
+To enable it, you need to create a JAX-WS binding file with enableAsyncMapping set to true:
| + + | +
+
+
+The sample code snippets used in this section come from the +HC5 integration test +in the source tree of Quarkus CXF + |
+
<?xml version="1.0"?>
+<bindings
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+ xmlns="https://jakarta.ee/xml/ns/jaxws"
+ wsdlLocation="CalculatorService.wsdl">
+ <bindings node="wsdl:definitions">
+ <enableAsyncMapping>true</enableAsyncMapping>
+ </bindings>
+</bindings>This file should then be passed to wsdl2java +through its additional-params property:
+quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdl
+quarkus.cxf.codegen.wsdl2java.additional-params = -b,src/main/resources/wsdl/async-binding.xmlOnce the asynchronous stubs are available, it is possible to wrap a client call in io.smallrye.mutiny.Uni as shown below:
package io.quarkiverse.cxf.hc5.it;
+
+import java.util.concurrent.Future;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.eap.quickstarts.wscalculator.calculator.AddResponse;
+import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
+
+import io.quarkiverse.cxf.annotation.CXFClient;
+import io.smallrye.mutiny.Uni;
+
+@Path("/hc5")
+public class Hc5Resource {
+
+ @Inject
+ @CXFClient("myCalculator") // name used in application.properties
+ CalculatorService myCalculator;
+
+ @SuppressWarnings("unchecked")
+ @Path("/add-async")
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public Uni<Integer> addAsync(@QueryParam("a") int a, @QueryParam("b") int b) {
+ return Uni.createFrom()
+ .future(
+ (Future<AddResponse>) myCalculator
+ .addAsync(a, b, res -> {
+ }))
+ .map(addResponse -> addResponse.getReturn());
+ }
+
+}Asynchronous clients delivered by this extension leverage ManagedExecutor with a thread pool provided by Quarkus.
+The thread pool can be configured using the quarkus.thread-pool.* family of
+options.
+As a consequence of this, the executor and thread pool related attributes of org.apache.cxf.transports.http.configuration.HTTPClientPolicy are not honored for async clients on Quarkus.
| + + | +
+
+
+You can see more details about the CXF asynchronous client and how to tune it further in CXF documentation. + |
+
Stable • Since 1.5.3
+WS-ReliableMessaging (WS-RM) is a protocol ensuring a reliable delivery of messages in a distributed environment even in presence of software, system, or network failures.
+This extension provides CXF framework’s WS-ReliableMessaging implementation.
+Create a new project using quarkus-cxf-rt-ws-rm on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-rm</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
Once your application depends on quarkus-cxf-rt-ws-rm, WS-RM is enabled for all clients and service endpoints defined in application.properties.
+This is due to the fact that the quarkus.cxf.client.myClient.rm.enabled and quarkus.cxf.endpoint."/my-endpoint".rm.enabled
+properties are true by default.
Enabling WS-RM for a client or service endpoints means that WS-RM interceptors will be added to the given client or endpoint.
+In addition to that you may want to set some of the options documented below and/or the following WS-Addressing options:
+There is an integration test covering WS-RM with a decoupled endpoint in the Quarkus CXF source tree.
+It is split into two separate applications that communicate with each other:
+To run it, you need to install the server into your local Maven repository first
+$ cd test-util-parent/test-ws-rm-server-jvm
+$ mvn clean installAnd then you can run the +test scenario +implemented in the client module:
+$ cd ../../integration-tests/ws-rm-client
+$ mvn clean testYou should see the exchange of SOAP messages between the client, the server and the decoupled endpoint in the console.
+Configuration property fixed at build time. All other configuration properties are overridable at runtime.
+| Configuration property | +Type | +Default | +
|---|---|---|
| + |
|
++ |
+
+WS-RM version namespace:
+ Environment variable: |
+||
| + |
|
++ |
+
+WS-Addressing version namespace:
+ Environment variable: |
+||
| + |
|
++ |
+
+A time duration in milliseconds after which the associated sequence will be closed if no messages (including +acknowledgments and other control messages) were exchanged between the sender and receiver during that period of +time. If not set, the associated sequence will never be closed due to inactivity. +
+ Environment variable: |
+||
| + |
|
+
|
+
+
+A time duration in milliseconds between successive attempts to resend a message that has not been acknowledged by the +receiver. +
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
| + |
|
++ |
+
+A time duration in milliseconds within which an acknowledgement for a received message is expected to be sent by a RM +destination. If not specified, the acknowledgements will be sent immediately. +
+ Environment variable: |
+||
| + |
|
++ |
+
+A reference to a
+ Environment variable: |
+||
| + |
|
+
|
+
+
+A reference to a
+
+If the value is
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
| + |
|
+
|
+
+
+If
+ Environment variable: |
+||
Stable • Since 0.14.0
+Provides CXF framework’s WS-Security implementation allowing you to:
+Pass authentication tokens between services
+Encrypt messages or parts of messages
+Sign messages
+Timestamp messages
+Create a new project using quarkus-cxf-rt-ws-security on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-ws-security</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
The CXF framework’s WS-Security (WSS) implementation is based on WSS4J. +It can be activated in two ways:
+By using WS-SecurityPolicy
+By adding WSS4J interceptors to your clients and service endpoints.
+WS-SecurityPolicy is preferable because in that way, the security requirements become a part of the WSDL contract. +That in turn greatly simplifies not only the implementation of clients and service endpoints +but also the interoperability between vendors.
+Nevertheless, if you leverage WS-SecurityPolicy, CXF sets up the WSS4J interceptors under the hood for you.
+We won’t explain the manual approach with WSS4J interceptors in detail here, +but you can still refer to our WS-Security integration test as an example.
+| + + | +
+
+
+The sample code snippets used in this section come from the +WS-SecurityPolicy integration test +in the source tree of Quarkus CXF + |
+
Let’s say our aim is to ensure that the communication between the client and service is confidential (through encryption) +and that the message has not been tampered with (through digital signatures). +We also want to assure that the clients are who they claim to be by authenticating themselves by X.509 certificates.
+We can express all these requirements in a single WS-SecurityPolicy document:
+<?xml version="1.0" encoding="UTF-8" ?>
+<wsp:Policy wsu:Id="SecurityServiceEncryptThenSignPolicy"
+ xmlns:wsp="http://www.w3.org/ns/ws-policy"
+ xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
+ xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ (1)
+ <sp:AsymmetricBinding xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
+ <wsp:Policy>
+ (2)
+ <sp:InitiatorToken>
+ <wsp:Policy>
+ <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
+ <wsp:Policy>
+ <sp:WssX509V3Token11/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:InitiatorToken>
+ <sp:RecipientToken>
+ <wsp:Policy>
+ <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
+ <wsp:Policy>
+ <sp:WssX509V3Token11/>
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:RecipientToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256/>
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ <sp:Layout>
+ <wsp:Policy>
+ <sp:Strict/>
+ </wsp:Policy>
+ </sp:Layout>
+ <sp:IncludeTimestamp/>
+ <sp:ProtectTokens/>
+ <sp:OnlySignEntireHeadersAndBody/>
+ <sp:EncryptBeforeSigning/>
+ </wsp:Policy>
+ </sp:AsymmetricBinding>
+ (3)
+ <sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:SignedParts>
+ (4)
+ <sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <sp:Body/>
+ </sp:EncryptedParts>
+ <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
+ <wsp:Policy>
+ <sp:MustSupportRefIssuerSerial/>
+ </wsp:Policy>
+ </sp:Wss10>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy>| 1 | +AsymmetricBinding specifies the use of asymmetric (public/private key) cryptography for securing the communication between two parties |
+
| 2 | +InitiatorToken indicates that the initiator (sender) of the message will use an X.509 certificate token that must always be provided to the recipient. |
+
| 3 | +SignedParts specifies which parts of the SOAP message must be signed to ensure their integrity. |
+
| 4 | +EncryptedParts specifies the parts of the SOAP message that must be encrypted to ensure their confidentiality. |
+
We set this policy on the Service Endpoint Interface (SEI)
+EncryptSignPolicyHelloService
+using @org.apache.cxf.annotations.Policy annotation:
@WebService(serviceName = "EncryptSignPolicyHelloService")
+@Policy(placement = Policy.Placement.BINDING, uri = "encrypt-sign-policy.xml")
+public interface EncryptSignPolicyHelloService extends AbstractHelloService {
+...
+}On the first sight, setting the policy on the SEI should suffice to enforce it on both the service +and all clients generated from the SEI or from the WSDL served by the service. +However, that’s not all. +Security keys, usernames, passwords and other kinds of confidental information cannot be exposed in a public policy.
+Those have to be set in the configuration. Let’s do it for the service first:
+# A service with encrypt-sign-policy.xml set
+quarkus.cxf.endpoint."/helloEncryptSign".implementor = io.quarkiverse.cxf.it.security.policy.EncryptSignPolicyHelloServiceImpl
+# can be jks or pkcs12 - set from Maven profiles in this test
+keystore.type = ${keystore.type}
+# Signature settings
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.username = bob
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.password = bob-keystore-password
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = ${keystore.type}
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = bob-keystore-password
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = bob
+quarkus.cxf.endpoint."/helloEncryptSign".security.signature.properties."org.apache.ws.security.crypto.merlin.file" = bob-keystore.${keystore.type}
+# Encryption settings
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.username = alice
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = ${keystore.type}
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = bob-keystore-password
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = bob
+quarkus.cxf.endpoint."/helloEncryptSign".security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = bob-keystore.${keystore.type}Similar setup is necessary on the client side:
+# A client with encrypt-sign-policy.xml set
+quarkus.cxf.client.helloEncryptSign.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/helloEncryptSign
+quarkus.cxf.client.helloEncryptSign.service-interface = io.quarkiverse.cxf.it.security.policy.EncryptSignPolicyHelloService
+quarkus.cxf.client.helloEncryptSign.features = #messageCollector
+# The client-endpoint-url above is HTTPS, so we have to setup the server's SSL certificates
+quarkus.cxf.client.helloEncryptSign.trust-store = client-truststore.${keystore.type}
+quarkus.cxf.client.helloEncryptSign.trust-store-password = client-truststore-password
+# Signature settings
+quarkus.cxf.client.helloEncryptSign.security.signature.username = alice
+quarkus.cxf.client.helloEncryptSign.security.signature.password = alice-keystore-password
+quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = alice-keystore-password
+quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = alice
+quarkus.cxf.client.helloEncryptSign.security.signature.properties."org.apache.ws.security.crypto.merlin.file" = alice-keystore.${keystore.type}
+# Encryption settings
+quarkus.cxf.client.helloEncryptSign.security.encryption.username = bob
+quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = alice-keystore-password
+quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = alice
+quarkus.cxf.client.helloEncryptSign.security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = alice-keystore.${keystore.type}To inspect the flow of the messages, you can execute the EncryptSignPolicyTest as follows:
# Clone the repository
+$ git clone https://github.com/quarkiverse/quarkus-cxf.git -o upstream
+$ cd quarkus-cxf
+# Build the whole source tree
+$ mvn clean install -DskipTests -Dquarkus.build.skip
+# Run the test
+$ cd integration-tests/ws-security-policy
+$ mvn clean test -Dtest=EncryptSignPolicyTestYou should see some messages containing Signature elements and encrypted bodies in the console output.
Configuration property fixed at build time. All other configuration properties are overridable at runtime.
+| Configuration property | +Type | +Default | +||
|---|---|---|---|---|
| + |
|
++ | ||
+
+The user’s name. It is used as follows: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s password when a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s name for signature. It is used as the alias name in the keystore to get the user’s cert and private key
+for signature. If this is not defined, then
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s password for signature when a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for
+encryption. If this is not defined, then
+
+For the WS-Security web service provider, the
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Crypto property configuration to use for signing, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Crypto property configuration to use for encryption, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A message property for prepared X509 certificate to be used for encryption. If this is not defined, then the
+certificate will be either loaded from the keystore
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The attribute URI of the SAML
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A String of regular expressions (separated by the value specified in
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The separator that is used to parse certificate constraints configured in
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The actor or role name of the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+Whether to always encrypt
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+If
+
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+The "real" security errors should not be returned to the client in production, as they may leak information about the +deployment, or otherwise provide an "oracle" for attacks. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+Works only with
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+
+Caching only applies when either a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+Whether to store bytes (CipherData or BinarySecurityToken) in an attachment. The default is true if MTOM is enabled. +Set it to false to BASE-64 encode the bytes and "inlined" them in the message instead. Setting this to true is more +efficient, as it means that the BASE-64 encoding step can be skipped. This only applies to the DOM WS-Security stack. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+Some frameworks cannot process the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+Some servers may not do client certificate verification at the start of the SSL handshake, and therefore the client +certificates may not be available to the WS-Security layer for policy verification. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The time in seconds to add to the Creation value of an incoming
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds in the future within which the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds to append to the Creation value of an incoming
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds in the future within which the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Set this property to point to a configuration file for the underlying caching implementation for the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Cache Identifier to use with the TokenStore. CXF uses the following key to retrieve a token store:
+
+
+The default
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Subject Role Classifier to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The Subject Role Classifier Type to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then
+the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+This configuration tag allows the user to override the default Asymmetric Signature algorithm (RSA-SHA1) for use in +WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+This configuration tag allows the user to override the default Symmetric Signature algorithm (HMAC-SHA1) for use in +WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+By default, WSS4J uses the
+
+The encrypted passwords must be stored in the format "ENC(encoded encrypted password)". +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a Kerberos
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The security token lifetime value (in milliseconds). +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The JAAS Context name to use for Kerberos. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Kerberos Service Provider Name (spn) to use. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a fully configured
+
+
+To work around the fact that
+
+Tip: Check the Security Token Service (STS) extension page +for more information about WS-Trust. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A URL, resource path or local filesystem path pointing to a WSDL document to use when generating the service proxy of +the STS client. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A fully qualified name of the STS service. Common values include: +
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A fully qualified name of the STS endpoint name. Common values include: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user name to use when authenticating against the STS. It is used as follows: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The password associated with the
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for
+encryption. If this is not defined, then
+
+For the WS-Security web service provider, the
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The Crypto property configuration to use for encryption, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+WCF’s trust server sometimes will encrypt the token in the response IN ADDITION TO the full security on the message. +These properties control the way the STS client will decrypt the EncryptedData elements in the response. +
+
+These are also used by the
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The Crypto property configuration to use for encryption, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The alias name in the keystore to get the user’s public key to send to the STS for the PublicKey KeyType case. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+Whether to write out an X509Certificate structure in UseKey/KeyInfo, or whether to write out a KeyValue structure. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s name. It is used as follows: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The user’s password when a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The user’s name for signature. It is used as the alias name in the keystore to get the user’s cert and private key
+for signature. If this is not defined, then
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The user’s password for signature when a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The user’s name for encryption. It is used as the alias name in the keystore to get the user’s public key for
+encryption. If this is not defined, then
+
+For the WS-Security web service provider, the
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The Crypto property configuration to use for signing, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The Crypto property configuration to use for encryption, if
+
+Example +
+
+
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A message property for prepared X509 certificate to be used for encryption. If this is not defined, then the
+certificate will be either loaded from the keystore
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The attribute URI of the SAML
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A String of regular expressions (separated by the value specified in
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The separator that is used to parse certificate constraints configured in
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The actor or role name of the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+Whether to always encrypt
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+If
+
+
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+If
+
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+The "real" security errors should not be returned to the client in production, as they may leak information about the +deployment, or otherwise provide an "oracle" for attacks. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+Works only with
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+
+Caching only applies when either a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+Whether to store bytes (CipherData or BinarySecurityToken) in an attachment. The default is true if MTOM is enabled. +Set it to false to BASE-64 encode the bytes and "inlined" them in the message instead. Setting this to true is more +efficient, as it means that the BASE-64 encoding step can be skipped. This only applies to the DOM WS-Security stack. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+Some frameworks cannot process the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+Some servers may not do client certificate verification at the start of the SSL handshake, and therefore the client +certificates may not be available to the WS-Security layer for policy verification. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds to add to the Creation value of an incoming
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds in the future within which the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds to append to the Creation value of an incoming
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The time in seconds in the future within which the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Set this property to point to a configuration file for the underlying caching implementation for the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Cache Identifier to use with the TokenStore. CXF uses the following key to retrieve a token store:
+
+
+The default
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Subject Role Classifier to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then the
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The Subject Role Classifier Type to use. If one of the WSS4J Validators returns a JAAS Subject from Validation, then
+the
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+This configuration tag allows the user to override the default Asymmetric Signature algorithm (RSA-SHA1) for use in +WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+This configuration tag allows the user to override the default Symmetric Signature algorithm (HMAC-SHA1) for use in +WS-SecurityPolicy, as the WS-SecurityPolicy specification does not allow the use of other algorithms at present. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+By default, WSS4J uses the
+
+The encrypted passwords must be stored in the format "ENC(encoded encrypted password)". +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a Kerberos
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+A reference to a
+
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+The security token lifetime value (in milliseconds). +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
+
|
+||
+
+If
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+The JAAS Context name to use for Kerberos. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The Kerberos Service Provider Name (spn) to use. +
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A reference to a
+
+This option is experimental, because it is not covered by +tests yet. +
+ Environment variable: |
+||||
Stable • Since 1.5.3
+Issue, renew and validate security tokens in context of WS-Trust.
+Create a new project using quarkus-cxf-services-sts on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-services-sts</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
Here are the key parts of a basic WS-Trust scenario:
+WS-SecurityPolicy - except for defining security requirements, such as transport protocols, encryption and signing,
+it can also contain an <IssuedToken> assertion.
+It specifies the requirements and constraints for these security tokens that the client must adhere to when accessing the service.
Security Token Service (STS) - issues, validates, and renews security tokens upon request. +It acts as a trusted authority that authenticates clients and issues tokens that assert the client’s identity and permissions.
+Client - requests a token from the STS to access a web service. +It must authenticate itself to the STS and provide details about the kind of token required.
+Service - relies on the STS to authenticate clients and validate their tokens.
+There is an integration test +covering WS-Trust in the Quarkus CXF source tree. +Let’s walk through it and see how the individual parts are set to work together.
+The policy is located in asymmetric-saml2-policy.xml file.
+Its key part is the <IssuedToken> assertion requiring a SAML 2.0 token:
<sp:IssuedToken
+ sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
+ <sp:RequestSecurityTokenTemplate>
+ <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
+ <t:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey</t:KeyType>
+ </sp:RequestSecurityTokenTemplate>
+ <wsp:Policy>
+ <sp:RequireInternalReference />
+ </wsp:Policy>
+ <sp:Issuer>
+ <wsaws:Address>http://localhost:8081/services/sts</wsaws:Address>
+ <wsaws:Metadata xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance"
+ wsdli:wsdlLocation="http://localhost:8081/services/sts?wsdl">
+ <wsaw:ServiceName xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
+ xmlns:stsns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"
+ EndpointName="UT_Port">stsns:SecurityTokenService</wsaw:ServiceName>
+ </wsaws:Metadata>
+ </sp:Issuer>
+ </sp:IssuedToken>The STS is implemented in Sts.java:
@WebServiceProvider(serviceName = "SecurityTokenService", portName = "UT_Port", targetNamespace = "http://docs.oasis-open.org/ws-sx/ws-trust/200512/", wsdlLocation = "ws-trust-1.4-service.wsdl")
+public class Sts extends SecurityTokenServiceProvider {
+
+ public Sts() throws Exception {
+ super();
+
+ StaticSTSProperties props = new StaticSTSProperties();
+ props.setSignatureCryptoProperties("stsKeystore.properties");
+ props.setSignatureUsername("sts");
+ props.setCallbackHandlerClass(StsCallbackHandler.class.getName());
+ props.setIssuer("SampleSTSIssuer");
+
+ List<ServiceMBean> services = new LinkedList<ServiceMBean>();
+ StaticService service = new StaticService();
+ final Config config = ConfigProvider.getConfig();
+ final int port = LaunchMode.current().equals(LaunchMode.TEST) ? config.getValue("quarkus.http.test-port", Integer.class)
+ : config.getValue("quarkus.http.port", Integer.class);
+ service.setEndpoints(Arrays.asList(
+ "http://localhost:" + port + "/services/hello-ws-trust",
+ "http://localhost:" + port + "/services/hello-ws-trust-actas",
+ "http://localhost:" + port + "/services/hello-ws-trust-onbehalfof"));
+ services.add(service);
+
+ TokenIssueOperation issueOperation = new TokenIssueOperation();
+ issueOperation.setServices(services);
+ issueOperation.getTokenProviders().add(new SAMLTokenProvider());
+ // required for OnBehalfOf
+ issueOperation.getTokenValidators().add(new UsernameTokenValidator());
+ // added for OnBehalfOf and ActAs
+ issueOperation.getDelegationHandlers().add(new UsernameTokenDelegationHandler());
+ issueOperation.setStsProperties(props);
+
+ TokenValidateOperation validateOperation = new TokenValidateOperation();
+ validateOperation.getTokenValidators().add(new SAMLTokenValidator());
+ validateOperation.setStsProperties(props);
+
+ this.setIssueOperation(issueOperation);
+ this.setValidateOperation(validateOperation);
+ }
+}and configured in application.properties:
quarkus.cxf.endpoint."/sts".implementor = io.quarkiverse.cxf.it.ws.trust.sts.Sts
+quarkus.cxf.endpoint."/sts".logging.enabled = pretty
+
+quarkus.cxf.endpoint."/sts".security.signature.username = sts
+quarkus.cxf.endpoint."/sts".security.signature.password = password
+quarkus.cxf.endpoint."/sts".security.validate.token = false
+
+quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
+quarkus.cxf.endpoint."/sts".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.file" = sts.pkcs12The service is implemented in TrustHelloServiceImpl.java:
@WebService(portName = "TrustHelloServicePort", serviceName = "TrustHelloService", targetNamespace = "https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/test/ws-trust", endpointInterface = "io.quarkiverse.cxf.it.ws.trust.server.TrustHelloService")
+public class TrustHelloServiceImpl implements TrustHelloService {
+ @WebMethod
+ @Override
+ public String hello(String person) {
+ return "Hello " + person + "!";
+ }
+}The asymmetric-saml2-policy.xml mentioned above is set in the Service Endpoint Interface TrustHelloService.java:
@WebService(targetNamespace = "https://quarkiverse.github.io/quarkiverse-docs/quarkus-cxf/test/ws-trust")
+@Policy(placement = Policy.Placement.BINDING, uri = "classpath:/asymmetric-saml2-policy.xml")
+public interface TrustHelloService {
+ @WebMethod
+ @Policies({
+ @Policy(placement = Policy.Placement.BINDING_OPERATION_INPUT, uri = "classpath:/io-policy.xml"),
+ @Policy(placement = Policy.Placement.BINDING_OPERATION_OUTPUT, uri = "classpath:/io-policy.xml")
+ })
+ String hello(String person);
+}The service endpoint is configured in application.properties:
quarkus.cxf.endpoint."/hello-ws-trust".implementor = io.quarkiverse.cxf.it.ws.trust.server.TrustHelloServiceImpl
+quarkus.cxf.endpoint."/hello-ws-trust".logging.enabled = pretty
+
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.username = service
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.password = password
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = service
+quarkus.cxf.endpoint."/hello-ws-trust".security.signature.properties."org.apache.ws.security.crypto.merlin.file" = service.pkcs12
+
+quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
+quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = service
+quarkus.cxf.endpoint."/hello-ws-trust".security.encryption.properties."org.apache.ws.security.crypto.merlin.file" = service.pkcs12Finally, for the SOAP client to be able to communicate with the service, its STSClient needs to be configured.
+It can be done in application.properties:
quarkus.cxf.client.hello-ws-trust.security.sts.client.wsdl = http://localhost:${quarkus.http.test-port}/services/sts?wsdl
+quarkus.cxf.client.hello-ws-trust.security.sts.client.service-name = {http://docs.oasis-open.org/ws-sx/ws-trust/200512/}SecurityTokenService
+quarkus.cxf.client.hello-ws-trust.security.sts.client.endpoint-name = {http://docs.oasis-open.org/ws-sx/ws-trust/200512/}UT_Port
+quarkus.cxf.client.hello-ws-trust.security.sts.client.username = client
+quarkus.cxf.client.hello-ws-trust.security.sts.client.password = password
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.username = sts
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = client
+quarkus.cxf.client.hello-ws-trust.security.sts.client.encryption.properties."org.apache.ws.security.crypto.merlin.keystore.file" = client.pkcs12
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.username = client
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.provider" = org.apache.ws.security.components.crypto.Merlin
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.type" = pkcs12
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.password" = password
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.alias" = client
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.properties."org.apache.ws.security.crypto.merlin.keystore.file" = client.pkcs12
+quarkus.cxf.client.hello-ws-trust.security.sts.client.token.usecert = true| + + | +
+
+
+The properties for configuring the STS client are provided by the |
+
Alternatively, the client can be set as a bean reference:
+quarkus.cxf.client.hello-ws-trust-bean.security.sts.client = #stsClientBeanIn that case, the @Named bean needs to be produced programmatically, e.g. using @jakarta.enterprise.inject.Produces:
import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+import jakarta.inject.Named;
+
+import org.apache.cxf.ws.security.SecurityConstants;
+
+import io.quarkiverse.cxf.ws.security.sts.client.STSClientBean;
+
+public class BeanProducers {
+
+ /**
+ * Create and configure an STSClient for use by the TrustHelloService client.
+ */
+ @Produces
+ @ApplicationScoped
+ @Named("stsClientBean")
+ STSClientBean createSTSClient() {
+ /*
+ * We cannot use org.apache.cxf.ws.security.trust.STSClient as a return type of this bean producer method
+ * because it does not have a no-args constructor. STSClientBean is a subclass of STSClient having one.
+ */
+ STSClientBean stsClient = STSClientBean.create();
+ stsClient.setWsdlLocation("http://localhost:8081/services/sts?wsdl");
+ stsClient.setServiceQName(new QName("http://docs.oasis-open.org/ws-sx/ws-trust/200512/", "SecurityTokenService"));
+ stsClient.setEndpointQName(new QName("http://docs.oasis-open.org/ws-sx/ws-trust/200512/", "UT_Port"));
+ Map<String, Object> props = stsClient.getProperties();
+ props.put(SecurityConstants.USERNAME, "client");
+ props.put(SecurityConstants.PASSWORD, "password");
+ props.put(SecurityConstants.ENCRYPT_PROPERTIES,
+ Thread.currentThread().getContextClassLoader().getResource("clientKeystore.properties"));
+ props.put(SecurityConstants.ENCRYPT_USERNAME, "sts");
+ props.put(SecurityConstants.STS_TOKEN_USERNAME, "client");
+ props.put(SecurityConstants.STS_TOKEN_PROPERTIES,
+ Thread.currentThread().getContextClassLoader().getResource("clientKeystore.properties"));
+ props.put(SecurityConstants.STS_TOKEN_USE_CERT_FOR_KEYINFO, "true");
+ return stsClient;
+ }
+}Stable • Since 1.5.11
+XJC plugins for wsdl2java code generation. +You’ll need to add this extension if you want to use any of the following in +quarkus.cxf.codegen.wsdl2java.additional-params:
+-xjc-Xbg - generate getFoo() instead of isFoo() accessor methods for boolean fields.
-xjc-Xdv - let the generated getter methods return the default value defined in the schema unless the field is set explicitly.
-xjc-Xjavadoc - generate JavaDoc based on xs:documentation present in the schema.
-xjc-Xproperty-listener - add PropertyChangeListener support to the generated beans.
-xjc-Xts - generate toString() methods in model classes.
-xjc-Xwsdlextension - generate beans that can be used directly with WSDL4J as extensors in the WSDL.
| + + | +
+
+
+Check the wsdl2java section of User guide for more details about |
+
Create a new project using quarkus-cxf-xjc-plugins on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-xjc-plugins</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
Stable • Since 0.1.0
+Core capabilities for implementing SOAP clients and JAX-WS services.
+Create a new project using quarkus-cxf on code.quarkus.io
+or add these coordinates to your existing project:
<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf</artifactId>
+</dependency>| + + | +
+
+
+Check the User guide and especially its +Dependency management section +for more information about writing applications with Quarkus CXF. + |
+
There are several chapters in the User guide covering the usage of this extension:
+Configuration property fixed at build time. All other configuration properties are overridable at runtime.
+| Configuration property | +Type | +Default | +||
|---|---|---|---|---|
| + |
|
+
|
+||
+
+The default path for CXF resources. +
+
+
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The size in bytes of the chunks of memory allocated when writing data. +
+
+This is a very advanced setting that should only be set if you understand exactly how it affects the output IO operations +of the application. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The size of the output stream response buffer in bytes. If a response is larger than this and no content-length is +provided then the response will be chunked. +
+
+Larger values may give slight performance increases for large responses, at the expense of more memory usage. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Select the
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+An URI base to use as a prefix of
+
+
+
+
+
+If you invoke your WS client from within a HTTP handler, you can leave this option unspecified and rather set it
+dynamically on the request context of your WS client using the
+
+
+
+
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies whether the message logging will be enabled for clients, services, both or none. This setting can be
+overridden per client or service endpoint using
+
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+A message length in bytes at which it is truncated in the log. This setting can be overridden per client or service
+endpoint using
+
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+A message length in bytes at which it will be written to disk.
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma separated list of XML elements containing sensitive information to be masked in the log. This setting can be
+overridden per client or service endpoint using
+
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma separated list of protocol headers containing sensitive information to be masked in the log. This setting can
+be overridden per client or service endpoint using
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The client service interface class name +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Indicates whether this is an alternative proxy client configuration. If true, then this configuration is ignored when
+configuring a client without annotation
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+
+Setting this to
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The service endpoint implementation class +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The service endpoint WSDL path +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The published service endpoint URL +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A message length in bytes at which it is truncated in the log. The default is given by
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A message length in bytes at which it will be written to disk.
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of XML elements containing sensitive information to be masked in the log. The default is given
+by
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of protocol headers containing sensitive information to be masked in the log. The default is
+given by
+
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma-separated list of fully qualified CXF Feature class names or named CDI beans. +
+
+Examples: +
+
+
+
+
+
+In the second case, the
+
+
+
+
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of Handler classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of InInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of OutInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of OutFaultInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of InFaultInterceptor classes +
+ Environment variable: |
+||||
|
+
|
++ | ||
+
+Select for which messages XML Schema validation should be enabled. If not specified, no XML Schema validation will be
+enforced unless it is enabled by other means, such as
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A URL, resource path or local filesystem path pointing to a WSDL document to use when generating the service proxy of +this client. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The URL of the SOAP Binding, should be one of four values: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The client endpoint URL +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The client endpoint namespace +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The client endpoint name +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The username for HTTP Basic authentication +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The password for HTTP Basic authentication +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A message length in bytes at which it is truncated in the log. The default is given by
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+A message length in bytes at which it will be written to disk.
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+If
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of additional binary media types to add to the default values in the
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of XML elements containing sensitive information to be masked in the log. The default is given
+by
+ Environment variable: |
+||||
|
+List of |
++ | ||
+
+A comma separated list of protocol headers containing sensitive information to be masked in the log. The default is
+given by
+
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+A comma-separated list of fully qualified CXF Feature class names. +
+
+Example: +
+
+
+
+
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of Handler classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of InInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of OutInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of OutFaultInterceptor classes +
+ Environment variable: |
+||||
| + | List of |
++ | ||
+
+The comma-separated list of InFaultInterceptor classes +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the amount of time, in milliseconds, that the consumer will attempt to establish a connection before it times +out. 0 is infinite. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. 0 is +infinite. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the amount of time, in milliseconds, used when requesting a connection from the connection manager(if +appliable). 0 is infinite. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies if the consumer will automatically follow a server issued redirection. (name is not part of standard) +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the maximum amount of retransmits that are allowed for redirects. Retransmits for authorization is included in +the retransmit count. Each redirect may cause another retransmit for a UNAUTHORIZED response code, ie. 401. Any negative +number indicates unlimited retransmits, although, loop protection is provided. The default is unlimited. (name is not +part of standard) +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If true, the client is free to use chunking streams if it wants, but it is not required to use chunking streams. If +false, the client must use regular, non-chunked requests in all cases. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+If AllowChunking is true, this sets the threshold at which messages start getting chunked. Messages under this limit do +not get chunked. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the chunk length for a HttpURLConnection. This value is used in +java.net.HttpURLConnection.setChunkedStreamingMode(int chunklen). chunklen indicates the number of bytes to write in each +chunk. If chunklen is less than or equal to zero, a default value will be used. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the MIME types the client is prepared to handle (e.g., HTML, JPEG, GIF, etc.) +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the language the client desires (e.g., English, French, etc.) +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the encoding the client is prepared to handle (e.g., gzip) +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the content type of the stream being sent in a post request. (this should be text/xml for web services, or can +be set to application/x-www-form-urlencoded if the client is sending form data). +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the Internet host and port number of the resource on which the request is being invoked. This is sent by +default based upon the URL. Certain DNS scenarios or application designs may request you to set this, but typically it is +not required. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The connection disposition. If close the connection to the server is closed after each request/response dialog. If +Keep-Alive the client requests the server to keep the connection open, and if the server honors the keep alive request, +the connection is reused. Many servers and proxies do not honor keep-alive requests. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Most commonly used to specify no-cache, however the standard supports a dozen or so caching related directives for +requests +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+HTTP Version used for the connection. The default value
+
+Some of these values might be unsupported by some
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The value of the
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+An URI path (starting with
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the address of proxy server if one is used. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the port number used by the proxy server. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Specifies the list of hostnames that will not use the proxy configuration. Examples: +
+
+
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+Specifies the type of the proxy server. Can be either HTTP or SOCKS. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Username for the proxy authentication +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Password for the proxy authentication +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Select the
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The key store location for this client. The resource is first looked up in the classpath, then in the file system. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The key store password +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The type of the key store. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The key password. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The trust store location for this client. The resource is first looked up in the classpath, then in the file system. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+The trust store password. +
+ Environment variable: |
+||||
| + |
|
+
|
+||
+
+The type of the trust store. +
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Can be one of the following: +
+
+
+ Environment variable: |
+||||
| + |
|
++ | ||
+
+Select for which messages XML Schema validation should be enabled. If not specified, no XML Schema validation will be
+enforced unless it is enabled by other means, such as
+ Environment variable: |
+||||
Here is the list of extensions produced by this project. +Please follow the links under the extension names to learn about how to use them, about their configuration and about any known limitations.
+| Quarkus CXF extension | +Support level | +Since | +Supported standards | +
|---|---|---|---|
Quarkus CXF |
+Stable |
+0.1.0 |
++ |
Quarkus CXF Metrics Feature |
+Stable |
+0.14.0 |
++ |
Quarkus CXF OpenTelemetry |
+Stable |
+2.7.0 |
++ |
Quarkus CXF WS-Security |
+Stable |
+0.14.0 |
++ |
Quarkus CXF WS-ReliableMessaging |
+Stable |
+1.5.3 |
++ |
Quarkus CXF Security Token Service (STS) |
+Stable |
+1.5.3 |
++ |
Quarkus CXF HTTP Async Transport |
+Stable |
+1.1.0 |
++ |
Quarkus CXF XJC Plugins |
+Stable |
+1.5.11 |
++ |
Here is a list of CXF modules supported by Quarkus CXF. +You should typically not depend on these directly, but rather use some of the extensions listed above that brings the given CXF module as a transitive dependency.
+Out of CXF front ends only the
+JAX-WS front end is fully supported by quarkus-cxf.
The Simple front end may work in JVM mode, but it is not tested properly. +We advise not to use it.
+Out of CXF Data Bindings only the following ones are supported:
+Out of CXF Transports only the following ones are supported:
+quarkus-cxf implements its own custom transport based on Quarkus and Vert.x for serving SOAP endpoints
HTTP client via quarkus-cxf, including
Asynchronous Client HTTP Transport
+via quarkus-cxf-rt-transports-http-hc5
wsdl2Java - see the Generate the Model classes from WSDL
+ section of User guide
java2ws - see the Generate WSDL from Java section of User guide
All CXF WSDL Bindings are supported.
+In order to switch to SOAP 1.2 or to add MTOM, set quarkus.cxf.[client|endpoint]."name".soap-binding to one of the following values:
| Binding | +Property Value | +
|---|---|
SOAP 1.1 (default) |
++ |
SOAP 1.2 |
++ |
SOAP 1.1 with MTOM |
++ |
SOAP 1.2 with MTOM |
++ |
Here is a list of CXF modules currently not supported by Quarkus CXF along with possible alternatives and/or reasons why the given module is not supported.
+| CXF module | +Alternative | +
|---|---|
JAX-RS |
++ |
| + | + |
| + | Use JAXB and JAX-WS |
+
DOSGI |
++ |
JiBX |
+Use JAXB and JAX-WS |
+
Local transport |
+Use HTTP transport |
+
JMS transport |
+Use HTTP transport |
+
JBI |
+Deprecated in CXF use HTTP transport |
+
UDP transport |
+Use HTTP transport |
+
| + | Use HTTP transport |
+
WebSocket transport |
+Use HTTP transport |
+
Clustering |
++ |
CORBA
+ |
+Use JAX-WS |
+
SDO databinding |
++ |
| + | Deprecated in CXF |
+
| + | Use JAX-WS |
+
| + | Use HTTP transport |
+
WS-Transfer runtime |
++ |
Throttling |
+Use load balancer |
+
Here is the status of CXF annotations on Quarkus.
+Unless stated otherwise, the support is available via io.quarkiverse.cxf:quarkus-cxf.
| Annotation | +Status | +
|---|---|
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Only the default value |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported via |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
|
+Supported |
+
major.minor version in sync with QuarkusThe most significant change in this release is the increment of major version of Quarkus CXF from 2 to 3
+so that our major.minor matches the major.minor version of Quarkus.
We did this mostly for practical reasons, so that it is easier for everybody to understand which version of Quarkus CXF +is compatible with which version of Quarkus.
+io.quarkiverse.cxf:quarkus-cxf-rt-features-logging is deprecated since Quarkus CXF 2.7.0,
+when all its functionality including configuration properties moved to io.quarkiverse.cxf:quarkus-cxf.
+In 3.8.0, we stopped mentioning it in the documentation and we removed it from code.quarkus.io.
+To keep backwards compatibility, a dummy io.quarkiverse.cxf:quarkus-cxf-rt-features-logging artifact still exists
+doing nothing else, but outputting a warning.
+You should remove the extension from your projects.
Santuario XMLSec extension was originally hosted under a separate project
+and published as io.quarkiverse.xmlsec:quarkus-xmlsec.
+As Quarkus CXF is the primary user of it, we decided to move it here to simplify the maintenance.
+The new Maven coordinates starting with Quarkus CXF 3.8.0 are io.quarkiverse.cxf:quarkus-cxf-santuario-xmlsec.
The following parts of the documentation were improved:
+The Reference page now contains List of supported CXF annotations.
+New example using WS-SecurityPolicy
+New configuration options for STSClient
+Security Token Service (STS) extension page with a more detailed example
+Release notes documents for major and minor releases are listed in this section.
+client-endpoint-url defaultsIf you omit the client-endpoint-url property in application.properties,
+the CXF Quarkus extension will assume that the service is published at http://localhost:8080/{service-path},
+where {service-path} is derived from
Configuration property quarkus.cxf.path (if specified); and the
SEI’s class name in lower case
+Given quarkus.cxf.path = /ws, the default effective client-endpoint-url of the CalculatorService would be
+http://localhost:8080/ws/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
If quarkus.cxf.path is not specified, the client-endpoint-url would be just
+http://localhost:8080/org.jboss.eap.quickstarts.wscalculator.calculator.calculatorservice.
In the example above, we configured just a single client called myCalculator.
+Of course, you can configure multiple clients pointing at different URLs and/or implementing different SEIs using multiple identifiers:
cxf.it.calculator.baseUri = http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService
+
+# another client
+quarkus.cxf.client.anotherCalculator.wsdl = https://acme.com/ws/WeatherService?wsdl
+quarkus.cxf.client.anotherCalculator.client-endpoint-url = https://acme.com/ws/WeatherService
+quarkus.cxf.client.anotherCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorServiceTo globally configure all clients in your application, you can use the example snippet below to configure the
+HttpConduit.
+This allows you to set the HTTPClientPolicy, AuthorizationPolicy, ProxyAuthorizationPolicy or even TLSClientParameters for your clients.
void onStart(@Observes StartupEvent ev) {
+
+ HTTPConduitConfigurer httpConduitConfigurer = new HTTPConduitConfigurer() {
+ public void configure(String name, String address, HTTPConduit c) {
+ AsyncHTTPConduit conduit = (AsyncHTTPConduit)c;
+ // use setter to configure client
+ conduit.getHttpAsyncClient().getCredentialsProvider().setCredentials( AuthScope.ANY,
+ new NTCredentials( USER,PWD, "", DOM ) );
+ conduit.getClient().setAllowChunking( false );
+ conduit.getClient().setAutoRedirect( true );
+ }
+ };
+
+ final Bus bus = BusFactory.getDefaultBus();
+ bus.setExtension(httpConduitConfigurer, HTTPConduitConfigurer.class);
+}Quarkus batch (e.g. periodically scheduled), or command line applications, may do without an HTTP server. +Use the property below to prevent launching the HTTP server at startup:
+quarkus.http.host-enabled = falseCXF client proxies implement java.io.Closeable.
+Therefore, it is important to call ((Closeable) proxy).close() once the client is not needed anymore
+to free all associated system resources, such as threads.
Quarkus CXF takes care for closing the clients injected via @io.quarkiverse.cxf.annotation.CXFClient automatically
+as soon as they are disposed by the CDI container.
For client proxies created manually, it is up to you to call ((Closeable) proxy).close():
import java.net.URL;
+import javax.xml.namespace.QName;
+import jakarta.xml.ws.Service;
+import java.io.Closeable;
+
+final URL serviceUrl = new URL("http://localhost/myService?wsdl");
+final QName qName = new QName("http://acme.org/myNamespace", "MyService");
+final Service service = jakarta.xml.ws.Service.create(serviceUrl, qName);
+final MyService proxy = service.getPort(MyService.class);
+
+try {
+ proxy.doSomething();
+} finally {
+ ((Closeable) proxy).close();
+}| + + | +
+
+
+The sample code snippets shown in this section come from the +Client and server integration test +in the source tree of Quarkus CXF. You may want to use it as a runnable example. + |
+
Use the following client configuration options provided by
+quarkus-cxf extension
+to pass the username and password for HTTP basic authentication:
Here is an example:
+quarkus.cxf.client.basicAuth.wsdl = http://localhost:${quarkus.http.test-port}/soap/basicAuth?wsdl
+quarkus.cxf.client.basicAuth.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/basicAuth
+quarkus.cxf.client.basicAuth.username = bob
+quarkus.cxf.client.basicAuth.password = bob234By default, the clients created by Quarkus CXF do not send the Authorization header,
+unless you set the quarkus.cxf.client."clients".secure-wsdl-access to true:
quarkus.cxf.client.basicAuthSecureWsdl.wsdl = http://localhost:${quarkus.http.test-port}/soap/basicAuth?wsdl
+quarkus.cxf.client.basicAuthSecureWsdl.client-endpoint-url = http://localhost:${quarkus.http.test-port}/soap/basicAuthSecureWsdl
+quarkus.cxf.client.basicAuthSecureWsdl.username = bob
+quarkus.cxf.client.basicAuthSecureWsdl.password = ${client-server.bob.password}
+quarkus.cxf.client.basicAuthSecureWsdl.secure-wsdl-access = trueThe server-side authentication and authorization is driven by Quarkus Security, +especially when it comes to
+There is a basic example in our Client and server integration test. +Its key parts are:
+io.quarkus:quarkus-elytron-security-properties-file dependency as an Identity provider
Basic authentication enabled and users with their roles configured in application.properties:
quarkus.http.auth.basic = true
+quarkus.security.users.embedded.enabled = true
+quarkus.security.users.embedded.plain-text = true
+quarkus.security.users.embedded.users.alice = alice123
+quarkus.security.users.embedded.roles.alice = admin
+quarkus.security.users.embedded.users.bob = bob234
+quarkus.security.users.embedded.roles.bob = app-userRole-based access control enfoced via @RolesAllowed annotation:
package io.quarkiverse.cxf.it.auth.basic;
+
+import jakarta.annotation.security.RolesAllowed;
+import jakarta.jws.WebService;
+
+import io.quarkiverse.cxf.it.HelloService;
+
+@WebService(serviceName = "HelloService", targetNamespace = HelloService.NS)
+@RolesAllowed("app-user")
+public class BasicAuthHelloServiceImpl implements HelloService {
+ @Override
+ public String hello(String person) {
+ return "Hello " + person + "!";
+ }
+}Camel Quarkus supports CXF since its version 2.12.0. +Under the hood, the implementation is based on Quarkus CXF. +Therefore, all functionality available in Quarkus CXF is also available in Camel Quarkus.
+Please refer to Camel Quarkus CXF SOAP extension documentation for further details.
+Some issues may appear during the development, testing, and native image building process of your quarkus-cxf project;
+below are some common ones and how to address them.
Sometimes a REST endpoint may be needed in the same project where the Quarkus CXF Extension is used. +The REST endpoint path must be different from the SOAP endpoint path (in order to avoid request +forwarding conflicts between both protocols).
+For example, if a WeatherWebService interface is declared in a WSDL, you can
+begin by creating the org.acme.cxf.WeatherWebServiceImpl class as follows:
package org.acme.cxf;
+
+import ...
+
+@Slf4j
+@WebService(endpointInterface = "org.acme.cxf.WeatherWebService")
+public class WeatherWebServiceImpl implements WeatherWebService {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ private Map<String, DailyTemperature> dailyTempByZipCode = Collections.synchronizedMap(new LinkedHashMap<>());
+
+ public WeatherWebServiceImpl() {
+ this.dailyTempByZipCode.addAll(
+ this.backEndWeatherService.getDailyForecast(Instant.now()));
+ }
+
+ @Override
+ public DailyTemperature estimationTemperatures(String zipCode) {
+ log.info("Daily estimation temperatures forecast called with '{}' zip code paramter", zipCode);
+ return this.dailyTempByZipCode.get(zipCode);
+ }
+}After that, you would need to specify the root context for your CXF web services, as indicated +in the configuration documentation to split the REST (with RESTEasy for example) +and SOAP routes based on their root context paths.
+CXF’s SOAP properties:
+quarkus.cxf.path=/soap
+quarkus.cxf.endpoint."/weather".implementor=org.acme.cxf.WeatherWebServiceImplNow, imagine the following RESTEasy endpoint:
+package org.acme.reasteasy;
+
+import ...
+
+@Slf4j
+@Path("/healthcheck")
+public class HealthCheckResource {
+
+ @Inject
+ BackEndWeatherService backEndWeatherService;
+
+ @GET
+ public Response doHealthCheck() {
+ if(this.backEndWeatherService.isAvailable()) {
+ return Response.ok().build();
+ } else {
+ return Response.status(Response.Status.SERVICE_UNAVAILABLE);
+ }
+ }
+}You can separate your REST endpoint by configuring the REASTEasy path:
+quarkus.resteasy.path=/restYou should now be able to send requests to both your REST and SOAP endpoints deployed within a single project, at:
+http://localhost:8080/soap/weather for SOAP
+Sometimes the wsdl2java autogenerated Java classes may not be +fully compatible with GraalVM due to non ASCII characters getting included in the code. Similar exceptions to +the below may appear during native image builds.
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] compile: 161 459,15 ms, 8,54 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] image: 158 272,73 ms, 8,43 GB
+[quarkus-dalkia-ticket-loader-1.0.0-SNAPSHOT-runner:26] write: 205,82 ms, 8,43 GB
+Fatal error:com.oracle.svm.core.util.VMError$HostedError: java.lang.RuntimeException: oops : expected ASCII string! com.oracle.svm.reflect.OperationOrderStatusType_CRÉÉ_f151156b0d42ecdbdfb919501d8a86dda8733012_1456.hashCode
+ at com.oracle.svm.core.util.VMError.shouldNotReachHere(VMError.java:72)Below is an example of auto-generated non ASCII characters in a Java class:
+@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Cr\u00e9\u00e9")
+ CRÉÉ("Cr\u00e9\u00e9"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de r\u00e9ponse")
+ EN_ATTENTE_DE_RÉPONSE("En attente de r\u00e9ponse"),
+ @XmlEnumValue("Attribu\u00e9")
+ ATTRIBUÉ("Attribu\u00e9"),
+ @XmlEnumValue("Clotur\u00e9")
+ CLOTURÉ("Clotur\u00e9"),
+ @XmlEnumValue("Annul\u00e9")
+ ANNULÉ("Annul\u00e9");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Anything starting with \u will be a problem. Consequently the following refactoring is needed:
@XmlType(name = "OperationOrderStatusType")
+@XmlEnum
+public enum OperationOrderStatusType {
+
+ @XmlEnumValue("Créé")
+ CREE("Créé"),
+ @XmlEnumValue("A communiquer")
+ A_COMMUNIQUER("A communiquer"),
+ @XmlEnumValue("En attente de réponse")
+ EN_ATTENTE_DE_REPONSE("En attente de réponse"),
+ @XmlEnumValue("Attribué")
+ ATTRIBUE("Attribué"),
+ @XmlEnumValue("Cloturé")
+ CLOTURE("Cloturé"),
+ @XmlEnumValue("Annulé")
+ ANNULE("Annulé");
+ private final String value;
+
+ OperationOrderStatusType(String v) {
+ value = v;
+ }
+
+ public String value() {
+ return value;
+ }
+
+ public static OperationOrderStatusType fromValue(String v) {
+ for (OperationOrderStatusType c: OperationOrderStatusType.values()) {
+ if (c.value.equals(v)) {
+ return c;
+ }
+ }
+ throw new IllegalArgumentException(v);
+ }
+}Quarkus CXF exposes a large number of configuration options. +Each extension documents its options at the bottom of its reference page.
+The configuration options can be set in application.properties file or via environment variables - see
+Quarkus configuration reference for details.
Several configuration options of Quarkus CXF allow referring to beans present in Quarkus CDI container. +Features and interceptors are typical examples of those.
+There are two ways how to set a bean reference in the configuration: by type or by bean name.
+Here is an example:
+# bean reference by type
+quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeatureWhen using a reference by type name, the resolution proceeds as follows:
+Fist the bean is looked up in Quarkus CDI container by type.
+If the bean is available, it is used.
+If multiple beans assignable to the given type, then an exception is thrown.
+If no matching bean is available, then the class is loaded and an attempt is performed to instantiate it using its default constructor.
+Here is an example:
+# bean reference by bean name
+quarkus.cxf.endpoint."/fruit".features = #myCustomLoggingFeatureWhen using a reference by bean name, then unsurprisingly, the bean is looked up in Quarkus CDI container by name.
+A named bean called myCustomLoggingFeature can be defined as follows:
import org.apache.cxf.ext.logging.LoggingFeature;
+import javax.enterprise.context.ApplicationScoped;
+import javax.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ @Named("myCustomLoggingFeature")
+ LoggingFeature myCustomLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ return loggingFeature;
+ }
+}Both contract first and code first development modes are fully supported by Quarkus CXF.
+A SOAP service is described by WSDL.
+It is a contract defining operations, their parameters and return values, etc.
+WSDL is rich enough to be used for generating the code of a complete client.
+CXF provides the wsdl2java utility for that.
Quarkus CXF wraps wsdl2java in the quarkus-cxf extension so you do not need to use it directly.
Follow the Generate the Model classes from WSDL section of the user guide +for more details about how to use it.
+You may also want to check the CXF Developing a Consumer as a general introduction.
+When implementing a service the generation of Java code from WSDL
+may also come in handy.
+wsdl2java can generate the model classes (with JAXB annotations)
+and service interfaces (with JAX-WS annotations) for you.
+Your task is then to provide implementations for those interfaces.
You may want to check the WSDL First Service Development +section of CXF documentation for a better understanding of the underlying concepts.
+Another valid option at your disposal is to write your service in Java, using JAX-WS and JAXB. +Then you have two options how to obtain the WSDL contract:
+Start your service and point your clients at http://your-host/your-service?wsdl
+Generate the WSDL document from Java classes at build time
+| + + | +
+
+
+Check the Code first development section of CXF documentation for further information. + |
+
This guide explains how to set up a new project for a Quarkus application hosting a CXF client or server or both.
+Read the Prerequisites section of Quarkus getting started guide.
+In addition to that, you may need
+GraalVM with the native-image command installed and the GRAALVM_HOME environment variable set.
+See Building a native executable section of the Quarkus
+documentation.
If you are on Linux, a container runtime like docker is sufficient for the native mode too.
+Use -Pnative -Dquarkus.native.container-build=true instead of -Pnative if you choose this option.
New project skeletons can be generated using code.quarkus.io.
+
+Here you can select the extensions that you want to work with.
+For a simple Hello world Web service or client the quarkus-cxf extension is enough.
Click the blue Generate your application button to download a basic skeleton project.
Unpack the zip file and import the project the into your favorite IDE.
+Quarkus CXF is a part of Quarkus Platform since Quarkus Platform version 3.1.0.Final. +Among other things, this means that code.quarkus.io +and other Quarkus development tools generate projects with proper dependency management:
+<project ...>
+ ...
+ <properties>
+ ...
+ <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
+ <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
+ <quarkus.platform.version><!-- Check the latest https://repo1.maven.org/maven2/io/quarkus/platform/quarkus-cxf-bom/ --></quarkus.platform.version>
+ </properties>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>${quarkus.platform.artifact-id}</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>${quarkus.platform.group-id}</groupId>
+ <artifactId>quarkus-cxf-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+...You should always take care to import the same version of io.quarkus.platform:quarkus-bom and io.quarkus.platform:quarkus-cxf-bom into your project.
+That’s the most reliable way to get compatible versions of Quarkus, CXF, Quarkus CXF and all their transitive dependencies.
CXF interceptors and CXF features can be added to both your client or server using either annotations or application.properties configurations.
While CXF provides a number of out of the box embedded interceptors and features, you can also integrate your custom developed implementations.
+Annotations can be used on either the service interface or implementor classes.
+@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@org.apache.cxf.interceptor.InInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor" })
+@org.apache.cxf.interceptor.OutInterceptors (interceptors = {"org.acme.Test1Interceptor" })
+@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"org.acme.Test2Interceptor","org.acme.Test3Intercetpor" })
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}You may also define your configurations in the application.properties file.
quarkus.cxf.endpoint."/greeting-service".features=org.apache.cxf.ext.logging.LoggingFeature
+quarkus.cxf.endpoint."/greeting-service".in-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".out-interceptors=org.acme.Test1Interceptor
+quarkus.cxf.endpoint."/greeting-service".in-fault-interceptors=org.acme.Test2Interceptor,org.acme.Test3Intercetpor
+quarkus.cxf.endpoint."/greeting-service".out-fault-interceptors=org.acme.Test1Intercetpor| + + | +
+ Class loading
+
+
+Both feature and interceptor classes are loaded via CDI first.. +
+
+If no CDI beans are available, the constructor without parameters will be invoked to instantiate each class. + |
+
The integration-tests folder of the codebase provides various examples
+that demonstrate how to use this extension extensively.
In this guide we explain how to create a simple Quarkus application acting as a client of a remote Web service.
+| + + | +
+ Create project first
+
+
+Follow the Project creation guide before proceeding here. + |
+
First, we need some remote Web service to connect to. +We can use a simple Calculator Web service running in a container for that purpose.
+$ docker run -p 8082:8080 quay.io/l2x6/calculator-ws:1.0Once the container is up and running, we can inspect its WSDL
+$ curl -s http://localhost:8082/calculator-ws/CalculatorService?wsdl
+<?xml version="1.0" ?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="CalculatorService" targetNamespace="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+
+ ...
+
+ <wsdl:binding name="CalculatorServiceSoapBinding" type="tns:CalculatorService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"></soap:binding>
+ <wsdl:operation name="add">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="add">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="addResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+ <wsdl:operation name="subtract">
+ <soap:operation soapAction="" style="document"></soap:operation>
+ <wsdl:input name="subtract">
+ <soap:body use="literal"></soap:body>
+ </wsdl:input>
+ <wsdl:output name="subtractResponse">
+ <soap:body use="literal"></soap:body>
+ </wsdl:output>
+ </wsdl:operation>
+
+ ...
+
+ </wsdl:binding>
+
+ ...
+
+</wsdl:definitions>As you can see in the WSDL, the service offers some basic arithmetic operations, such as add, subtract, etc.
Let’s test it with curl:
$ curl -s \
+ -X POST \
+ -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
+ <Body>
+ <add xmlns="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <arg0 xmlns="">7</arg0> (1)
+ <arg1 xmlns="">4</arg1>
+ </add>
+ </Body>
+ </Envelope>' \
+ http://localhost:8082/calculator-ws/CalculatorService
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:addResponse xmlns:ns2="http://www.jboss.org/eap/quickstarts/wscalculator/Calculator">
+ <return>11</return> (2)
+ </ns2:addResponse>
+ </soap:Body>
+</soap:Envelope>| 1 | +The request to add 7 and 4 |
+
| 2 | +11 - return value of the operation |
+
Now let’s have a look how we can get the client inside a Quarkus application.
+First, we need the Service Endpoint Interface (SEI) and all other model classes it requires.
+There are several ways to get them:
+Write by hand
+Copy from the Web Sevice project, if it is written in Java
+Have a Maven artifact containing the model classes, perhaps it is offered by the Service project
+Generate the model classes from WSDL
+The last option tends to be the easiest and most flexible for client applications.
+| + + | +
+
+
+If you want to use this approach, first follow the Generate Java from WSDL section and then continue with the next steps. + |
+
In our case, the Service Endpoint Interface (SEI) is org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService.
As usual on Quarkus, we can obtain an instance of it via CDI.
+To make it testable easily, we’ll wrap it in a REST service:
+package io.quarkiverse.cxf.client.it;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService;
+
+import io.quarkiverse.cxf.annotation.CXFClient;
+
+@Path("/cxf/calculator-client")
+public class CxfClientRestResource {
+
+ @CXFClient("myCalculator") (1)
+ CalculatorService myCalculator;
+
+ @GET
+ @Path("/add")
+ @Produces(MediaType.TEXT_PLAIN)
+ public int add(@QueryParam("a") int a, @QueryParam("b") int b) {
+ return myCalculator.add(a, b); (2)
+ }
+
+}| 1 | +Let the CDI container inject an instance of the client. @CXFClient("myCalculator") is actually equivalent to @Inject @CXFClient("myCalculator") |
+
| 2 | +Invoke the add operation thus calling the remote Web service |
+
Is this all we need for the client to work?
+- No, in addition to the above, we need to tell a few other things to the CXF Quarkus extension in application.properties:
cxf.it.calculator.baseUri=http://localhost:8082
+quarkus.cxf.client.myCalculator.wsdl = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService?wsdl
+quarkus.cxf.client.myCalculator.client-endpoint-url = ${cxf.it.calculator.baseUri}/calculator-ws/CalculatorService
+quarkus.cxf.client.myCalculator.service-interface = org.jboss.eap.quickstarts.wscalculator.calculator.CalculatorService| + + | +
+
+
+All client configuration properties are documented in the Configuration properties reference. + |
+
With all the above files in place, we should be able to start the application in Quarkus dev mode
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and test it by sending some requests to it:
+$ curl -s 'http://localhost:8080/cxf/calculator-client/add?a=5&b=6'
+11where 11 is the correct result of adding 5 and 6.
In this guide we explain how to create a Quarkus application exposing a simple SOAP Web service.
+| + + | +
+ Create project first
+
+
+Follow the Project creation guide before proceeding here. + |
+
Having the pom.xml in place, you can add a simple Hello world! Web service in src/main/java.
| + + | +
+ Code examples
+
+
+The sample code snippets used in this section come from the +server integration test +in the source tree of Quarkus CXF + |
+
First add the service interface:
+package io.quarkiverse.cxf.it.server;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+/**
+ * The simplest Hello service.
+ */
+@WebService(name = "HelloService", serviceName = "HelloService")
+public interface HelloService {
+
+ @WebMethod
+ String hello(String text);
+
+}and then the implementation:
+package io.quarkiverse.cxf.it.server;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+/**
+ * The simplest Hello service implementation.
+ */
+@WebService(serviceName = "HelloService")
+public class HelloServiceImpl implements HelloService {
+
+ @WebMethod
+ @Override
+ public String hello(String text) {
+ return "Hello " + text + "!";
+ }
+
+}For the implementation to get exposed under a certain path, you need to add the following configuration to application.properties:
# The context path under which all services will be available
+quarkus.cxf.path = /soap
+
+# Publish "HelloService" under the context path /${quarkus.cxf.path}/hello
+quarkus.cxf.endpoint."/hello".implementor = io.quarkiverse.cxf.it.server.HelloServiceImpl
+quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature| + + | +
+
+
+All configuration properties are documented in the Configuration properties reference. + |
+
With these files in place, you can start Quarkus in dev mode:
$ mvn quarkus:devThis will compile the project and start the application on the background.
+You can test the service using curl or some other SOAP client.
First let’s have a look at the auto-generated WSDL under http://localhost:8080/soap/hello?wsdl:
+$ curl http://localhost:8080/soap/hello?wsdl
+<?xml version='1.0' encoding='UTF-8'?>
+<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://server.it.cxf.quarkiverse.io/"
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://schemas.xmlsoap.org/soap/http"
+ name="HelloService" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <wsdl:types>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://server.it.cxf.quarkiverse.io/" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://server.it.cxf.quarkiverse.io/">
+ <xsd:element name="hello" type="tns:hello"/>
+ <xsd:complexType name="hello">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="arg0" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+ <xsd:element name="helloResponse" type="tns:helloResponse"/>
+ <xsd:complexType name="helloResponse">
+ <xsd:sequence>
+ <xsd:element minOccurs="0" name="return" type="xsd:string"/>
+ </xsd:sequence>
+ </xsd:complexType>
+</xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="helloResponse">
+ <wsdl:part element="tns:helloResponse" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="hello">
+ <wsdl:part element="tns:hello" name="parameters">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:portType name="HelloService">
+ <wsdl:operation name="hello">
+ <wsdl:input message="tns:hello" name="hello">
+ </wsdl:input>
+ <wsdl:output message="tns:helloResponse" name="helloResponse">
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="HelloServiceSoapBinding" type="tns:HelloService">
+ <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+ <wsdl:operation name="hello">
+ <soap:operation soapAction="" style="document"/>
+ <wsdl:input name="hello">
+ <soap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="helloResponse">
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="HelloService">
+ <wsdl:port binding="tns:HelloServiceSoapBinding" name="HelloServicePort">
+ <soap:address location="http://localhost:8080/soap/hello"/>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions>Second, let’s send a SOAP request to the service:
+$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+ </soap:Envelope>' \
+ http://localhost:8080/soap/hello
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return>Hello World!</return>
+ </ns1:helloResponse>
+ </soap:Body>
+</soap:Envelope>You can see the expected <return>Hello World!</return> in the SOAP response.
Sometimes it may come in handy to be able to inspect the SOAP messages received or sent by the server or client.
+This is easily doable by adding the quarkus-cxf-rt-features-logging extension to pom.xml.
| + + | +
+
+
+Try to do that while Quarkus dev mode is running. +You should see the application being recompiled and redeployed upon saving your changes in the source tree. + |
+
pom.xml<dependency>
+ <groupId>io.quarkiverse.cxf</groupId>
+ <artifactId>quarkus-cxf-rt-features-logging</artifactId>
+</dependency>application.propertiesquarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeatureAfter that you can send a new SOAP request and see some SOAP payloads in the application console:
+2023-01-11 22:12:21,315 INFO [org.apa.cxf.ser.Hel.REQ_IN] (vert.x-worker-thread-0) REQ_IN
+ Address: http://localhost:8080/soap/hello
+ HttpMethod: POST
+ Content-Type: text/xml;charset=UTF-8
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {Accept=*/*, User-Agent=curl/7.79.1, content-type=text/xml;charset=UTF-8, Host=localhost:8080, Content-Length=203, x-quarkus-hot-deployment-done=true}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body><ns2:hello xmlns:ns2="http://server.it.cxf.quarkiverse.io/"><arg0>World</arg0></ns2:hello></soap:Body>
+</soap:Envelope>
+
+
+2023-01-11 22:12:21,327 INFO [org.apa.cxf.ser.Hel.RESP_OUT] (vert.x-worker-thread-0) RESP_OUT
+ Address: http://localhost:8080/soap/hello
+ Content-Type: text/xml
+ ResponseCode: 200
+ ExchangeId: af10747a-8477-4c17-bf5f-2a4a3a95d61c
+ ServiceName: HelloService
+ PortName: HelloServicePort
+ PortTypeName: HelloService
+ Headers: {}
+ Payload: <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><ns1:helloResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/"><return>Hello World!</return></ns1:helloResponse></soap:Body></soap:Envelope>You may want to proceed with packaging your application for running on a JVM or natively.
+quarkus-cxf extension supports generating Java classes from WSDL during Quarkus code generation phase.
| + + | +
+ Code examples
+
+
+The code snippets shown in this section come from the +client integration test +in the source tree of Quarkus CXF. +You may want to check it as an executable example. + |
+
You need to set up a couple of things for CXF code generation to work:
+Have io.quarkiverse.cxf:quarkus-cxf dependency in your project
For Maven projects, the generate-code goal needs to be present in the configuration of quarkus-maven-plugin:
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>For Gradle projects no additional configurarion of io.quarkus plugin is needed
Put your WSDL files under src/main/resources or src/test/resources or any subdirectory thereof.
Your WSDL file names must end with .wsdl
Set quarkus.cxf.codegen.wsdl2java.includes
+configuration property
+to a pattern matching the WSDL files you wish to process.
+If you want to process all WSDL files under src/main/resources/wsdl or src/test/resources/wsdl, set it as follows:
quarkus.cxf.codegen.wsdl2java.includes = wsdl/*.wsdlThis will generate Java classes in target/generated-sources/wsdl2java or
+target/generated-test-sources/wsdl2java directory.
+They will be automatically picked by the compiler plugin there.
+Hence we are free to refer to them from our application or test code.
Note that quarkus-cxf code generation uses the wsdl2Java utility
+from CXF under the hood. wsdl2Java is called separately for each WSDL file selected by includes and excludes.
Passing custom parameters to wsdl2java is possible through
+quarkus.cxf.codegen.wsdl2java.additional-params
+configuration parameter.
If you need different additional-params for each WSDL file, you may want to define a separate named parameter set for
+each one of them. Here is an example:
# Parameters for foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.includes = wsdl/foo.wsdl
+quarkus.cxf.codegen.wsdl2java.foo-params.wsdl-location = wsdl/foo.wsdl
+# Parameters for bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.includes = wsdl/bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.wsdl-location = wsdl/bar.wsdl
+quarkus.cxf.codegen.wsdl2java.bar-params.xjc = ts| + + | +
+
+
+Add |
+
If the WSDL served by your service at http://your-host/your-service?wsdl is not enough
+because you e.g. want to distribute it as a Maven artifact,
+then you can use java2ws to generate the WSDL document at build time.
You do not need to invoke the java2ws tool provided by CXF directly,
+neither you have to use the cxf-java2ws-plugin.
quarkus-cxf wraps java2ws and so you can configure it in application.properties
+as any other aspect of your application.
Here is an example:
+| + + | +
+
+
+The sample code snippets used in this section come from the +server integration test +in the source tree of Quarkus CXF + |
+
quarkus.cxf.java2ws.includes = io.quarkiverse.cxf.it.server.HelloService,io.quarkiverse.cxf.it.server.FaultyHelloService
+quarkus.cxf.java2ws.wsdl-name-template = %TARGET_DIR%/Java2wsTest/%SIMPLE_CLASS_NAME%-from-java2ws.wsdlHere we have instructed java2ws to generate WSDLs for two interfaces,
+namely HelloService and FaultyHelloService.
| + + | +
+ Annotations
+
+
+Note that the Service interfaces must be annotated with |
+
The two generated WSDL documents will be stored as target/Java2wsTest/FaultyHelloService-from-java2ws.wsdl
+and target/Java2wsTest/HelloService-from-java2ws.wsdl respectively.
| + + | +
+Unlike wsdl2java which is executed within Quarkus source generation phase,
+ java2ws is a part Quarkus augmentation that happens after compilation.
+ The input of java2ws are, after all, Java class files.
+ Hence you do not need to add <goal>generate-code</goal> to quarkus-maven-plugin
+ for java2ws.
+ |
+
quarkus.cxf.java2ws.* configuration properties of quarkus-cxf
This User guide explains typical use cases of Quarkus CXF.
+You may want to start with some of the following topics:
+As an alternative to the @HandlerChain annotation,
+JAX-WS Handlers can be added
+to both your client or server via application.properties:
# A web service endpoint with multiple Handler classes
+quarkus.cxf.endpoint."/greeting-service".handlers=org.acme.MySOAPHandler,org.acme.AnotherSOAPHandler
+
+# A web service client with a single Handler
+quarkus.cxf.client."greeting-client".handlers=org.acme.MySOAPHandlerWhere MySOAPHandler could look like below:
import jakarta.xml.ws.handler.soap.SOAPHandler;
+import jakarta.xml.ws.handler.soap.SOAPMessageContext;
+
+public class MySOAPHandler implements SOAPHandler<SOAPMessageContext> {
+
+ public boolean handleMessage(SOAPMessageContext messageContext) {
+ SOAPMessage msg = messageContext.getMessage();
+ return true;
+ }
+ // other methods
+}| + + | +
+ Class loading
+
+
+The
+
+If no CDI beans are available, the constructor without parameters will be invoked to instantiate each class. + |
+
JAX-WS Providers are fully supported, and can be implemented as shown below.
+Given the following sample Provider implementation:
import jakarta.xml.transform.stream.StreamSource;
+import jakarta.xml.ws.BindingType;
+import jakarta.xml.ws.Provider;
+import jakarta.xml.ws.Service;
+import jakarta.xml.ws.ServiceMode;
+import jakarta.xml.ws.WebServiceProvider;
+import java.io.StringReader;
+
+@WebServiceProvider
+@ServiceMode(value = Service.Mode.PAYLOAD)
+public class StreamSourcePayloadProvider implements Provider<StreamSource> {
+
+ public StreamSourcePayloadProvider() {
+ }
+
+ public StreamSource invoke(StreamSource request) {
+ String payload = StaxUtils.toString(request);
+
+ // Do some interesting things ...
+
+ StreamSource response = new StreamSource(new StringReader(payload));
+ return response;
+ }
+}The application.properties can be configured as shown below.
# A web service endpoint with the Provider implementation class
+quarkus.cxf.endpoint."/stream-source".implementor=org.acme.StreamSourcePayloadProvider| + + | +
+ Class loading
+
+
+
+
+If no CDI beans are available, the constructor without parameters will be invoked to instantiate each class. + |
+
In this chapter, we explain how to package a Quarkus CXF application for running on a JVM or for running it natively.
+In the introductory guides for SOAP client and SOAP service, we worked only in Quarkus dev mode:
+Quarkus tooling was running on the background,
+watching for changes in our workspace, recompiling and reloading the application as needed.
How do we run the application on a JVM once we are done with the development?
+First we need to package it with Maven:
+$ mvn packageThe libraries needed to run the application on a JVM can be found in target/quarkus-app directory:
$ ls -lh target/quarkus-app
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 app
+drwxr-xr-x. 4 ppalaga ppalaga 4.0K Jan 12 22:29 lib
+drwxr-xr-x. 2 ppalaga ppalaga 4.0K Jan 12 22:29 quarkus
+-rw-r-r--. 1 ppalaga ppalaga 6.1K Jan 12 22:29 quarkus-app-dependencies.txt
+-rw-r-r--. 1 ppalaga ppalaga 678 Jan 12 22:29 quarkus-run.jarWe can start the application as follows:
+$ java -jar target/quarkus-app/quarkus-run.jarYou can send some SOAP requests using curl to make sure that the application works.
Quarkus offers first class support for building GraalVM native images +and Quarkus CXF fully honors that promise too.
+| + + | +
+ Images
+
+
+GraalVM native images are platform specific executable files that you can run directly without a JVM. +They boot faster and spend less memory compared to running the same application in JVM mode. + |
+
The pom.xml file generated by code.quarkus.io
+contains the native profile needed for building the native image:
<profile>
+ <id>native</id>
+ <activation>
+ <property>
+ <name>native</name>
+ </property>
+ </activation>
+ <properties>
+ <skipITs>false</skipITs>
+ <quarkus.package.type>native</quarkus.package.type>
+ </properties>
+</profile>Further, as mentioned in the Create a new project section, you need the GraalVM native-image tool.
You should either have it installed locally and have GRAALVM_HOME environment variable set properly,
+or — if you only need to produce a Linux native executable — you can use docker.
# Make sure $GRAALVM_HOME is set properly
+$ echo $GRAALVM_HOME
+/home/{user}/.sdkman/candidates/java/{major}.{minor}.r{java-version}-grl
+
+# Produce the native executable
+mvn package -Pnative| + + | +
+
+
+Quarkus is quite picky about the GraalVM version.
+When using the local installation, always make sure that you use the version preferred by Quarkus.
+You can do that by opening |
+
docker# Produce the native executable
+mvn package -Pnative -Dquarkus.native.container-build=trueThis can take a minute or so for a simple application.
+When the build is done, the native executable should be available in target directory:
$ ls -l target
+...
+-rwxr-xr-x. 1 ppalaga ppalaga 71M Jan 11 22:42 quarkus-cxf-integration-test-server-1.8.0-SNAPSHOT-runner
+...As you can see, it has a size of only 71 MB, and is executable.
+You can run it as follows:
+$ target/*-runner
+...
+INFO [io.quarkus] (main) quarkus-cxf-integration-test-server 1.8.0-SNAPSHOT native (powered by Quarkus
+2.15.2.Final) started in 0.042s. Listening on: http://0.0.0.0:8080
+...Again, you can send some SOAP requests using curl to make sure that the native executable works.
Do not forget to compare the memory usage, time to first request and other performance metrics +with the stack you used before and share your results!
+You may also refer to the links below which contain tips on how to work with native images.
+Refer to Quarkus Container image guide.
+Refer to Quarkus Logging guide for basic information about logging on Quarkus, such as
+Getting a logger in your application code
+| + + | +
+ History
+
+
+Since Quarkus CXF 2.6.0, the payload logging functionality is available via
+ |
+
The payload logging functionality is implemented primarily through the org.apache.cxf.ext.logging.LoggingFeature class.
There are several ways how you can set the feature on a client or service endpoint.
+The global logging options exist since Quarkus CXF 2.6.0.
+If enabled via quarkus.cxf.logging.enabled = true, Quarkus CXF creates a global LoggingFeature instance
+and sets it on every client and service endpoint in the application.
+The global settings can be overriden on the client or service endpoint level.
# Global settings
+quarkus.cxf.logging.enabled = true
+quarkus.cxf.logging.pretty = trueAll logging configuration options are listed on quarkus-cxf reference page.
| + + | +
+
+
+All logging properties mentioned on this page are runtime configuration options.
+Hence you can pass them when starting the application without having to rebuild it.
+It can be done either by passing a system property on the command line (e.g. |
+
Since Quarkus CXF 2.5.0, the LoggingFeature can be configured and attached to a client or a service
+endpoint declaratively by setting the appropriate options in application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".logging.enabled = true
+quarkus.cxf.endpoint."/hello".logging.pretty = true
+# For a client:
+quarkus.cxf.client.hello.logging.enabled = true
+quarkus.cxf.client.hello.logging.pretty = trueAll logging configuration options are documented on quarkus-cxf reference page:
LoggingFeature to a client or serviceTo attach an instance with default settings, you can do one of the following:
+In application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeature
+# For a client:
+quarkus.cxf.client."myClient".features=org.apache.cxf.ext.logging.LoggingFeature| + + | +
+
+
+There is an example in Your first SOAP Web service chapter of the User guide. + |
+
or alternatively
+Use the @Features annotation of CXF:
@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+ public long sayHi(long arg) {
+ return arg;
+ }
+ //...
+}LoggingFeature beanIf you need some custom logic to setup the LoggingFeature, you can produce a named LoggingFeature bean:
import org.apache.cxf.ext.logging.LoggingFeature;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.inject.Produces;
+
+class Producers {
+
+ @Produces
+ @ApplicationScoped
+ @Named("limitedLoggingFeature") // "limitedLoggingFeature" is redundant if the name of the method is the same
+ LoggingFeature limitedLoggingFeature() {
+ LoggingFeature loggingFeature = new LoggingFeature();
+ loggingFeature.setPrettyLogging(true);
+ loggingFeature.setLimit(1024);
+ return loggingFeature;
+ }
+}Then you can refer to it by its name prefixed with # in application.properties:
# For a service:
+quarkus.cxf.endpoint."/hello".features = #limitedLoggingFeature
+# For a client:
+quarkus.cxf.client.hello.features = #limitedLoggingFeatureSOAP requests aimed towards services running on Quarkus can be routed through proxies that generate additional headers
+(e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved.
+In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.
| + + | +
+
+
+Refer to Quarkus HTTP reference for more details. + |
+
Quarkus CXF support for various X-Forwarded headers works in line with Quarkus configuration.
| + + | ++Activating this feature leaves the server exposed to several security issues (i.e. information spoofing). Consider activating it only when running behind a reverse proxy. + | +
These are the relevant Quarkus properties and their effect on Quarkus CXF:
+quarkus.http.proxy.proxy-address-forwarding - the main switch to enable the rewriting of the request destination parts.
If enabled, the rewriting of the request fields will be effective throughout the whole CXF server stack.
+If enabled, the values passed via X-Forwarded-Proto and X-Forwarded-Port headers
+will be used to set the protocol part and the port part of the URL returned by
+jakarta.servlet.http.HttpServletRequest.getRequestURL() respectively.
If enabled, the value passed via X-Forwarded-For will be returned by jakarta.servlet.ServletRequest.getRemoteAddr().
quarkus.http.proxy.enable-forwarded-host -
+enable the rewriting of the host part of URL returned by jakarta.servlet.http.HttpServletRequest.getRequestURL().
+The actual host name is taken from the header configured via
+quarkus.http.proxy.forwarded-host-header
+(default is X-Forwarded-Host).
quarkus.http.proxy.enable-forwarded-prefix -
+enable the rewriting of the path part of the URL returned by jakarta.servlet.http.HttpServletRequest.getRequestURL()
+and of the URI returned by jakarta.servlet.http.HttpServletRequest.getRequestURI().
+The actual path prefix is taken from the header configured via
+quarkus.http.proxy.forwarded-prefix-header
+(default is X-Forwarded-Prefix).
Here is the most common snippet to copy to your application.properties:
quarkus.http.proxy.proxy-address-forwarding = true
+quarkus.http.proxy.enable-forwarded-host = true
+quarkus.http.proxy.enable-forwarded-prefix = trueOne of the observable effects of these settings is the change of the location value in WSDL served
+on http://localhost:8080/services/my-service?wsdl.
+For example, if the request contains the following headers
X-Forwarded-Proto: https
+X-Forwarded-Host: api.example.com
+X-Forwarded-Port: 443
+X-Forwarded-Prefix: /my-prefixthen the WSDL served on http://localhost:8080/services/my-service?wsdl would contain the following location:
...
+<soap:address location="https://api.example.com:443/my-prefix/services/my-service"/>
+...Our introductory guides for Quarkus SOAP client +and SOAP service dealt with services +having only primitive parameters and return values such as integers and strings. +Let’s have a look at passing and receiving more complex objects.
+As an example, let’s create an application for managing fruits.
+| + + | ++The sample code snippets used in this section come from the + server integration test + in the source tree of Quarkus CXF + | +
Because our representation of fruit is supposed to be a complex, let’s model it as a Java bean with a couple of attributes:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Objects;
+
+import jakarta.xml.bind.annotation.XmlElement;
+import jakarta.xml.bind.annotation.XmlRootElement;
+import jakarta.xml.bind.annotation.XmlType;
+
+@XmlType(name = "Fruit")
+@XmlRootElement
+public class Fruit {
+
+ private String name;
+
+ private String description;
+
+ public Fruit() {
+ }
+
+ public Fruit(String name, String description) {
+ this.name = name;
+ this.description = description;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ @XmlElement
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getDescription() {
+ return description;
+ }
+
+ @XmlElement
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (!(obj instanceof Fruit)) {
+ return false;
+ }
+
+ Fruit other = (Fruit) obj;
+
+ return Objects.equals(other.getName(), this.getName());
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(this.getName());
+ }
+}As you may have noticed, we have used some JAXB annotations,
+such as @XmlElement, @XmlRootElement and @XmlType.
+This is to control the serialization and deserialization of the bean from and to XML.
JAXB is a reflection based serialization framework.
+When learning about GraalVM native images, one of the first things you typically hear is
+that you have to register classes, fields and methods for reflection at build time.
+With plain GraalVM you’d have to do this through reflection-config.json manually.
+Well, at least for the classes you have written yourself.
+Not so with Quarkus. quarkus-jaxb extension (which quarkus-cxf depends on)
+is able to scan your application’s class path for classes annotated with JAXB annotations
+and register them for reflection automatically.
Hence working with complex payloads on Quarkus is not different from stock CXF. +The JAXB serialization and deserialization will work out of the box without any additional configuration.
+The Service Endpoint Interface (SEI) for managing fruits might look like the following:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Set;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+@WebService
+public interface FruitService {
+
+ @WebMethod
+ Set<Fruit> list();
+
+ @WebMethod
+ Set<Fruit> add(Fruit fruit);
+
+ @WebMethod
+ Set<Fruit> delete(Fruit fruit);
+}We can implement the SEI as simply as possible:
+package io.quarkiverse.cxf.it.server;
+
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+import jakarta.jws.WebService;
+
+@WebService(serviceName = "FruitService")
+public class FruitServiceImpl implements FruitService {
+
+ private Set<Fruit> fruits = Collections.synchronizedSet(new LinkedHashSet<>());
+
+ public FruitServiceImpl() {
+ fruits.add(new Fruit("Apple", "Winter fruit"));
+ fruits.add(new Fruit("Pineapple", "Tropical fruit"));
+ }
+
+ @Override
+ public Set<Fruit> list() {
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> add(Fruit fruit) {
+ fruits.add(fruit);
+ return fruits;
+ }
+
+ @Override
+ public Set<Fruit> delete(Fruit fruit) {
+ fruits.remove(fruit);
+ return fruits;
+ }
+}application.propertiesThe implementation is pretty straightforward and you just need to define your endpoints using the application.properties.
quarkus.cxf.endpoint."/fruits".implementor = io.quarkiverse.cxf.it.server.FruitServiceImpl
+quarkus.cxf.endpoint."/fruits".features = org.apache.cxf.ext.logging.LoggingFeaturedev mode and curlHaving the above files in place, you can start Quarkus tooling in dev mode:
$ mvn quarkus:dev
+...
+INFO [io.quarkus] (Quarkus Main Thread) ... Listening on: http://localhost:8080and then check whether the service is working by invoking its list operation:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soapenv:Envelope
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <soapenv:Body>
+ <ns1:list/>
+ </soapenv:Body>
+ </soapenv:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:listResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ </ns1:listResponse>
+ </soap:Body>
+</soap:Envelope>As you can see, the endpoint has returned the two fruits Apple and Pineapple available by default.
Now let’s add another fruit, say an Orange:
$ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
+ -d \
+ '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns2:add xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <arg0>
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </arg0>
+ </ns2:add>
+ </soap:Body></soap:Envelope>' \
+ http://localhost:8080/soap/fruits
+...
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:addResponse xmlns:ns1="http://server.it.cxf.quarkiverse.io/">
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Winter fruit</description>
+ <name>Apple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Tropical fruit</description>
+ <name>Pineapple</name>
+ </return>
+ <return xmlns:ns2="http://server.it.cxf.quarkiverse.io/">
+ <description>Mediterranean fruit</description>
+ <name>Orange</name>
+ </return>
+ </ns1:addResponse>
+ </soap:Body>
+</soap:Envelope>We can see Orange having been added in the returned list as expected.
You may want to proceed with packaging your application for running on a JVM or natively.
+This chapter documents various use cases related to SSL, TLS and HTTPS.
+| + + | ++The sample code snippets used in this section come from the + WS-SecurityPolicy integration test + in the source tree of Quarkus CXF + | +
If your client is going to communicate with a server whose SSL certificate is not trusted by the client’s operating system,
+then you need to set up a custom trust store for your client.
+Tools like openssl or Java keytool are commonly used for doing that.
+You may want to check
+some
+examples
+in Quarkus CXF source tree.
Once you have prepared the trust store, you need to configure your client to use it.
+application.propertiesThis is the easiest way to set the client trust store. +The key role is played by the following properties:
+Here is an example:
+keystore.type = jks (1)
+quarkus.cxf.client.hello.client-endpoint-url = https://localhost:${quarkus.http.test-ssl-port}/services/hello
+quarkus.cxf.client.hello.service-interface = io.quarkiverse.cxf.it.security.policy.HelloService
+quarkus.cxf.client.hello.trust-store-type = ${keystore.type}
+(2)
+quarkus.cxf.client.hello.trust-store = client-truststore.${keystore.type}
+quarkus.cxf.client.hello.trust-store-password = client-truststore-password| 1 | +pkcs12 trust store type is a common alternative to jks. |
+
| 2 | +The referenced client-truststore.jks file has to be available in src/main/resources directory. |
+
The server SSL configuration is driven by Quarkus HTTP layer a.k.a. Vert.x. +Quarkus HTTP guide provides the information about the configuration options.
+Here is a basic example:
+(1)
+quarkus.http.ssl.certificate.key-store-file = localhost-keystore.${keystore.type}
+quarkus.http.ssl.certificate.key-store-password = localhost-keystore-password
+quarkus.http.ssl.certificate.key-store-key-alias = localhost
+quarkus.http.ssl.certificate.key-store-key-password = localhost-keystore-password| 1 | +The referenced localhost.jks file has to be available in src/main/resources directory. |
+
The requirement for the clients to connect through HTTPS can be defined in a policy.
+The functionality is provided by quarkus-cxf-rt-ws-security extension.
Here is an example of a policy file:
+<?xml version="1.0" encoding="UTF-8"?>
+<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
+ xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
+ xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate="false" />
+ </wsp:Policy>
+ </sp:TransportToken>
+ <sp:IncludeTimestamp />
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic128 />
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy>The policy has to be referenced from a service endpoint interface (SEI):
+package io.quarkiverse.cxf.it.security.policy;
+
+import jakarta.jws.WebMethod;
+import jakarta.jws.WebService;
+
+import org.apache.cxf.annotations.Policy;
+
+/**
+ * A service implementation with a transport policy set
+ */
+@WebService(serviceName = "HttpsPolicyHelloService")
+@Policy(placement = Policy.Placement.BINDING, uri = "https-policy.xml")
+public interface HttpsPolicyHelloService extends AbstractHelloService {
+
+ @WebMethod
+ @Override
+ public String hello(String text);
+
+}With this setup in place, any request delivered over HTTP will be rejected by the PolicyVerificationInInterceptor:
ERROR [org.apa.cxf.ws.pol.PolicyVerificationInInterceptor] Inbound policy verification failed: These policy alternatives can not be satisfied:
+ {http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}TransportBinding: TLS is not enabled
+ ...Quarkus Dapr Extension provides a DevService to enhance your experience with Quarkus and Dapr.
+Dev Services for Dapr are disabled by default unless:
+quarkus.dapr.devservices.enabled is set to true
Dev Services for Dapr uses the latest daprio/daprd image (diagrid/daprd:latest). You can change this image using the quarkus.dapr.devservices.image-name property.
By default, Dapr DevServices create a Dapr container containing in-memory Pub/Sub and in-memory State Store building blocks.
+If you want to add a custom Dapr component, you need to add it to the src/main/resources/components folder.
Example of Pub/Sub using Redis.
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: pubsub
+spec:
+ type: pubsub.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""Example of State Store using Redis:
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: statestore
+spec:
+ type: state.redis
+ version: v1
+ metadata:
+ - name: keyPrefix
+ value: name
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""Dapr is a portable, event-driven runtime that makes it easy for any developer to build resilient, stateless and +stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
+Leveraging the benefits of a sidecar architecture, Dapr helps you tackle the challenges that come with building +microservices and keeps your code platform agnostic.
+For more information about Dapr, please go https://dapr.io/.
+Quarkus Dapr is a Quarkus extension to integrate with Dapr.
+Quarkus Dapr Extension enables Java developers to create ultra lightweight Java native applications for Function +Computing and FaaS scenes, which is also particularly suitable for running as serverless.
+With the help of Dapr, these ultra lightweight Java native applications can easily interact with external application +and resources. Dapr provides many useful building blocks to build modern distributed application: service invocation, +state management, input/output bindings, publish & subscribe, secret management……
+Because of the advantages of sidecar model, the native applications can benefit from Dapr’s distributed capabilities +while remain lightweight without introducing too many dependencies. This is not only helping to keep the size of java +native applications, but also making the native applications easy to build as native images.
+If you want to use this extension, you need to add the io.quarkiverse.dapr:quarkus-dapr extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.dapr</groupId>
+ <artifactId>quarkus-dapr</artifactId>
+</dependency>With Quarkus Dapr Extension, it’s pretty easy for java developers.
+To publish events to your message broker, just inject a dapr client to your bean and call it’s publishEvent() method:
+@Inject
+SyncDaprClient dapr;
+
+dapr.publishEvent("messagebus", "topic1", content.getBytes(StandardCharsets.UTF_8), new HashMap<>());To subscribe events for your message broker, adding some annotations on your method is enough:
+@POST
+@Path("/topic1")
+@Topic(name = "topic1", pubsubName = "messagebus")
+public String eventOnTopic2(String content) {......}For more details and hands-on experiences, please reference to our Demo.
+Quarkus Dapr Extension provides a DevService to enhance your experience with Quarkus and Dapr.
+Dev Services for Dapr are disabled by default unless:
+quarkus.dapr.devservices.enabled is set to true
Dev Services for Dapr uses the latest daprio/daprd image (diagrid/daprd:latest). You can change this image using the quarkus.dapr.devservices.image-name property.
By default, Dapr DevServices create a Dapr container containing in-memory Pub/Sub and in-memory State Store building blocks.
+If you want to add a custom Dapr component, you need to add it to the src/main/resources/components folder.
Example of Pub/Sub using Redis.
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: pubsub
+spec:
+ type: pubsub.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""Example of State Store using Redis:
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: statestore
+spec:
+ type: state.redis
+ version: v1
+ metadata:
+ - name: keyPrefix
+ value: name
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The web path where Dashbuilder dashboards will be available. By default, this value will be resolved as a path relative to
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Comma separated list of dashboards to be rendered by Dashbuilder. If not used then Dashbuilder scan all
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If true samples will also be included in the final JAR +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Dashboards properties +
+
+Environment variable: |
+
|
++ |
Dashbuilder is a tool for running client side dashboards defined in declarative languages, such as YAML. This extension aims to bring Dashbuilder bundle to your application.
+If you want to use this extension, you need to add the io.quarkiverse.dashbuilder:quarkus-dashbuilder extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.dashbuilder</groupId>
+ <artifactId>quarkus-dashbuilder</artifactId>
+ <version>0.32.0</version>
+</dependency>| Property | +Type | +Default | +Description | +
|---|---|---|---|
|
+string |
+
|
+Web context for dashbuilder |
+
|
+list of strings |
++ | comma separated list of paths to dashboards files. If empty dashbuilder scans for |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The web path where Dashbuilder dashboards will be available. By default, this value will be resolved as a path relative to
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Comma separated list of dashboards to be rendered by Dashbuilder. If not used then Dashbuilder scan all
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If true samples will also be included in the final JAR +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Dashboards properties +
+
+Environment variable: |
+
|
++ |
Application commands are Discord’s newest way of interacting with bots in Discord, replacing the traditional method of parsing out message content.
+It’s possible to interface with application commands using Gateway listener methods, but the quarkus-discord4j-commands extension comes with some additional goodies that make it easy to develop application commands.
Add the quarkus-discord4j-commands artifact to your Quarkus app:
<dependency>
+ <groupId>io.quarkiverse.discord4j</groupId>
+ <artifactId>quarkus-discord4j-commands</artifactId>
+ <version>0.0.1</version>
+</dependency>Before you can start listening for commands in code, you first need to define your application commands and register them in Discord so they can be used. The easiest way to do this is by defining your commands using JSON. Quarkus Discord Bot will automatically serialize and register the JSON files found in META-INF/commands and subdirectories as application commands (when configured to do so).
| + + | ++Discord supports two types of application commands: global commands and guild commands. Global commands take an hour to propagate after being registered, so it’s recommended to register your commands as guild commands while you’re developing. + | +
Let’s create a guild command by creating the following JSON file in META-INF/commands/test:
{
+ "name": "foo"
+ "description": "Foo command"
+ "options": [
+ {
+ "type": 3,
+ "name": "name",
+ "description": "The text to reply to the command with"
+ }
+ ]
+}You can find the full JSON schema of application commands here.
+Now that you’ve created a guild command using JSON, you need to configure the ID of the guild command, and configure your Quarkus Discord Bot to register the command when your app starts. You can do that by configuring the following properties:
+quarkus.discord4j.guild-commands.test.overwrite-on-start=true
+quarkus.discord4j.guild-commands.test.guild-id=<test guild ID>The configuration name of the guild commands, test, must match the name of the subdirectory in META-INF/commands we created earlier.
| + + | +
+To obtain the ID of your test guild, turn on developer mode in your Discord client by going to User Settings > App Settings > Advanced and checking the Developer Mode option. Then, right click your server’s icon and click Copy ID.
+ |
+
You can find the full list of configurable properties in the Reference.
+To listen for the command you just defined, create the following class:
+class FooCommand {
+
+ @Command(value="foo", guild="test") (1)
+ Mono<Void> onFoo(ChatInputInteractionEvent event) { (2)
+ String name = event.getOption("name")
+ .flatMap(ApplicationCommandInteractionOption::getValue)
+ .map(ApplicationCommandInteractionOptionValue::asString)
+ .get(); (3)
+
+ return event.reply(name); (4)
+ }
+}| 1 | +The guild value indicates that we’re listening to a guild command from the guild ID we configured under the name test. Simply omit the guild value if you want to listen for global commands. |
+
| 2 | +Like Gateway listener methods, command methods can return Mono, Uni, Flux, or Multi. |
+
| 3 | +Here, we extract the value of the name option passed to our foo command. |
+
| 4 | +When we receive a command, we have to acknowledge it. Here, we acknowledge the command by immediately replying. | +
| + + | ++It is planned to allow option values to be injected directly into command methods in the future. + | +
You can listen for subcommands and subcommand groups using a slightly different class hierarchy. Let’s imagine the command we defined earlier includes subcommands and subcommand groups, and create the following class for it:
+@Command(value="foo", guild="test")
+class FooCommands {
+
+ @SubCommand("baz") (1)
+ Mono<Void> onBaz(ChatInputInteractionEvent event) {
+ // acknowledge command
+ }
+
+ @SubCommandGroup("bar")
+ class BarCommands {
+
+ @SubCommand("baz") (2)
+ Mono<Void> onBaz(ChatInputInteractionEvent event) {
+ // acknowledge command
+ }
+ }
+}| 1 | +We listen for /foo baz commands |
+
| 2 | +We listen for /foo bar baz commands |
+
Before you create your Quarkus Discord bot, you’ll need to create a Discord developer application and spin up a new bot user. If you already have a Discord bot set up, skip to Installation to start experimenting.
+Create a new Discord developer application by going to the Discord developer portal and clicking New Application.
| + + | ++As each Discord app can only have one bot user, it’s a good idea to create two separate apps so that you can create separate bots for development and production. + | +
You can create a bot by going to Bot and clicking the Add Bot button. After your bot has appeared, be sure to copy the token and set it aside for later so that you can configure your Quarkus app.
| + + | +
+Be sure to uncheck the Public Bot if you don’t want other users to be able to add your bot to their server.
+ |
+
| + + | +
+If you plan to listen for and read messages in servers, you should check the Message Content Intent option.
+ |
+
Go to OAuth2 > URL Generator and select the bot scope. For a bot, you won’t require any other scopes unless you plan to register application commands, then you’ll need the applications.commands scope.
Now you can select any permissions your bot needs. You can grant more permissions to your bot later in your own server, but for public bots, it’s important that your generated URL has the correct permissions that it needs to function.
+Once you’re done selecting permissions, go to the generated URL and add your bot to a server.
+| + + | ++You should add your bot to a server that only you’re in until you’re done developing. This is because incoming Gateway events from activity in the server can trigger live reload in dev mode. + | +
To create a Quarkus Discord bot, you need Quarkus. You can create a Quarkus application with the Quarkus Discord4J extension using Maven:
+mvn io.quarkus:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=my-discord-bot \
+ -Dextensions="io.quarkiverse.discord4j:quarkus-discord-bot:0.0.1"Alternatively, just add the Quarkus Discord4J dependency to your existing Quarkus application:
+<dependency>
+ <groupId>io.quarkiverse.discord4j</groupId>
+ <artifactId>quarkus-discord4j</artifactId>
+ <version>0.0.1</version>
+</dependency>Or, you can bootstrap a new Quarkus app using Gradle from https://code.quarkus.io.
+You can configure your bot in any of the ways that Quarkus supports. See the Configuration reference guide for more information.
+Because we have a token that we don’t want to commit, let’s use a .env
+file:
QUARKUS_DISCORD4J_TOKEN=<your bot token>
+QUARKUS_DISCORD4J_ENABLED_INTENTS=<set of enabled Gateway intents>Your bot’s token obtained from your app’s Bot section in the Discord developer portal
The set of Gateway intents corresponding to the Gateway events you want your bot to receive
+Now you can start coding and handling Gateway events.
+For example, create the following class:
+class AddReaction {
+ Mono<Void> onMessageCreate(@GatewayEvent MessageCreateEvent event) {
+ return event.getMessage().addReaction(ReactionEmoji.of("🤖"));
+ }
+}Your bot will now react to each message sent in servers and via DM with 🤖.
+The method is called automatically each time your bot receives a MessageCreateEvent.
You can start dev mode to take advantage of live reload and improve productivity.
+Quarkus will automatically restart your application (and bot) when it detects code changes after receiving a Gateway event. The best part is that the event won’t be sent to your code until after your bot restarts, meaning you can test new code only when you’re ready.
+| + + | ++It’s a good idea to have a separate dev bot and server for this reason. If your dev bot is in multiple servers, someone else can trigger live reload by sending a message when you’re not ready. A separate server allows you to be in control of when live reload is triggered. + | +
Just execute the following command to run Quarkus in dev mode:
+./mvnw quarkus:devFrom here, you can do whatever you want with your bot by observing any of the supported Gateway events. You can also use all the extensions and other goodies that Quarkus has to offer.
+When you’re done developing your bot, it might be a good idea to generate a native executable so you can benefit from a reduced memory footprint and a faster startup time in production.
+More information about these features (and more) can be found in the Reference.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||
|---|---|---|---|---|
+
+
+
+
+
+Whether a health check should be published for the Gateway clients managed by this extension if the quarkus-smallrye-health extension is present +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+Whether metrics should be collected for the Gateway clients managed by this extension if the quarkus-micrometer or quarkus-smallrye-metrics extension is present +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+Whether to serialize and register the JSON files found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The path to the JSON files of the global commands. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Whether to delete registered global commands whose JSON representation is not found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The bot token used to authenticate to the Discord API. +
+
+Environment variable: |
+string |
+required |
+||
+
+
+
+
+
+The status of the bot. +
+
+Environment variable: |
+
+
|
++ | ||
+
+
+
+
+
+The Gateway intents that should be enabled. Specific Gateway intents are required to receive certain Gateway events. Non-privileged intents will be enabled by default. +
+
+Environment variable: |
+list of Intent |
++ | ||
+
+
+
+
+
+The strategy to use for retrieving Discord entities. Default is
+
+Environment variable: |
+EntityRetrievalStrategy |
++ | ||
+
+
+
+
+
+The number of shards that this bot should be split into. +
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+Which shards from the configured number of shards that this bot will receive events from. The bot will receive events from all specified shards by default. +
+
+Environment variable: |
+list of int |
+
|
+||
+
+
+
+
+
+The number of shards that this bot will concurrently identify to the Gateway. +
+
+
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+Whether to serialize and register the JSON files found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The path to the JSON files of the guild commands. By default, the path is
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+Whether to delete commands registered in this guild whose JSON representation is not found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The ID of the guild. +
+
+Environment variable: |
+long |
+
|
+||
Activity configuration +This configuration section is optional |
+Type |
+Default |
+||
+
+
+
+
+
+The type of activity. +
+
+Environment variable: |
+
+
|
+required |
+||
+
+
+
+
+
+The name of the activity. +
+
+Environment variable: |
+string |
+required |
+||
+
+
+
+
+
+The YouTube or Twitch URL of the stream, if the activity type is
+
+Environment variable: |
+string |
++ |
Quarkus Discord4J is an extension to streamline the development of WebSocket-based (Gateway) Discord bots in Quarkus.
+Listen to Gateway events using annotations, generate a native executable, increase productivity with live reload, and more.
+Uses the Discord4J library.
+You should be somewhat familiar with the Quarkus framework before creating your Quarkus Discord bot. Quarkus has extensive documentation at https://quarkus.io/guides to help you get started.
+Additionally, the Discord4J documentation and the Discord API Gateway event documentation are essential resources to have on hand.
+| + + | +
+Discord4J uses Project Reactor as its reactive framework instead of Mutiny, the reactive layer most Quarkus users will be familiar with. For this reason, reactive listener methods support returning Mono instead of Uni and Flux instead of Multi, but you can still convert your Reactor streams into Mutiny streams if you want.
+ |
+
The Choosing an Operator guide might be useful to you if you don’t want to convert your streams.
+To listen to Gateway events, simply declare a method with an event type parameter and annotate it with @GatewayEvent. The method can return Mono, Uni, Flux, or Multi.
Here’s an example of an imperative listener method:
+class AddReaction {
+ Mono<Void> onMessageCreate(@GatewayEvent MessageCreateEvent event) {
+ return event.getMessage().addReaction(ReactionEmoji.of("🤖"));
+ }
+}A few details about Gateway listener methods:
+The declaring class and method can be public, protected, or package private
+The declaring class has to be a concrete class
+The method should be concrete
+The annotated event must be the first parameter
+All the currently supported event types can be found by checking out the subclasses of the Event class.
+You can inject a GatewayDiscordClient bean that exposes high level methods to manage Discord resources via REST, access the underlying entity cache, and manage your bot’s connection to the Gateway and Voice Gateway.
| + + | +
+This usually isn’t necessary as each Discord4J event exposes the Gateway client via Event#getClient(), and you can manage most resources directly from its corresponding entity instance.
+ |
+
An example:
+@ApplicationScoped
+class MyBean {
+ @Inject
+ GatewayDiscordClient gateway;
+
+ // do something with gateway
+}If your Quarkus app uses a metrics extension like Micrometer or SmallRye Metrics, you can enable metrics collection for your bot exposed at the /q/metrics endpoint by setting the configuration property quarkus.discord4j.metrics.enabled to true.
Currently, metrics are collected for the number of servers your bot is in and the number of voice channels your bot is in.
+A readiness health check for your bot is automatically exposed at the /q/health/ready endpoint if your Quarkus app depends on SmallRye Health. All of your bot’s shards will be checked and the health status will be DOWN if any shard isn’t connected.
You can disable the health check by setting quarkus.discord4j.health.enabled to false.
You can package your Discord bot into a native executable with GraalVM or Mandrel to reduce its memory footprint and speed up its boot time. See the Building a native executable guide for more information.
+You can configure the following properties:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||
|---|---|---|---|---|
+
+
+
+
+
+Whether a health check should be published for the Gateway clients managed by this extension if the quarkus-smallrye-health extension is present +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+Whether metrics should be collected for the Gateway clients managed by this extension if the quarkus-micrometer or quarkus-smallrye-metrics extension is present +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+Whether to serialize and register the JSON files found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The path to the JSON files of the global commands. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Whether to delete registered global commands whose JSON representation is not found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The bot token used to authenticate to the Discord API. +
+
+Environment variable: |
+string |
+required |
+||
+
+
+
+
+
+The status of the bot. +
+
+Environment variable: |
+
+
|
++ | ||
+
+
+
+
+
+The Gateway intents that should be enabled. Specific Gateway intents are required to receive certain Gateway events. Non-privileged intents will be enabled by default. +
+
+Environment variable: |
+list of Intent |
++ | ||
+
+
+
+
+
+The strategy to use for retrieving Discord entities. Default is
+
+Environment variable: |
+EntityRetrievalStrategy |
++ | ||
+
+
+
+
+
+The number of shards that this bot should be split into. +
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+Which shards from the configured number of shards that this bot will receive events from. The bot will receive events from all specified shards by default. +
+
+Environment variable: |
+list of int |
+
|
+||
+
+
+
+
+
+The number of shards that this bot will concurrently identify to the Gateway. +
+
+
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+Whether to serialize and register the JSON files found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The path to the JSON files of the guild commands. By default, the path is
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+Whether to delete commands registered in this guild whose JSON representation is not found in
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The ID of the guild. +
+
+Environment variable: |
+long |
+
|
+||
Activity configuration +This configuration section is optional |
+Type |
+Default |
+||
+
+
+
+
+
+The type of activity. +
+
+Environment variable: |
+
+
|
+required |
+||
+
+
+
+
+
+The name of the activity. +
+
+Environment variable: |
+string |
+required |
+||
+
+
+
+
+
+The YouTube or Twitch URL of the stream, if the activity type is
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The SQL dialect. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The batch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The fetch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The max rows. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The query timeout limit in seconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode: +
+
+* In dev and test modes, it defaults to
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The SQL file repository. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The naming convention controller. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SQL log type that determines the SQL log format in exceptions. +
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+The SQL dialect. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The batch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The fetch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The max rows. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The query timeout limit in seconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode: +
+
+* In dev and test modes, it defaults to
+
+Environment variable: |
+string |
+
|
+
Doma is a database access framework with support for type-safe Criteria API and SQL templates.
+Quarkus Doma provides the following features for Doma:
+Hot reloading
+Automatic bean register
+Automatic SQL execution on startup
+Configuration
+Multiple Datasources
+Support for native images
+In development mode, Doma extension reloads SQL and Script files when they are changed.
+Doma extension registers all DAO beans to the Quarkus CDI container.
+You can write the following configurations in your application.properties file:
+quarkus.doma.sql-file-repository=greedy-cache +quarkus.doma.naming=none +quarkus.doma.exception-sql-log-type=none +quarkus.doma.dialect=h2 +quarkus.doma.batch-size=10 +quarkus.doma.fetch-size=50 +quarkus.doma.max-rows=500 +quarkus.doma.query-timeout=5000 +quarkus.doma.sql-load-script=import.sql+
The above properties are all optional.
+You can bind Doma’s configurations to each datasource as follows:
+# default datasource +quarkus.datasource.db-kind=h2 +quarkus.datasource.username=username-default +quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default +quarkus.datasource.jdbc.min-size=3 +quarkus.datasource.jdbc.max-size=13 + +# inventory datasource +quarkus.datasource.inventory.db-kind=h2 +quarkus.datasource.inventory.username=username2 +quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory +quarkus.datasource.inventory.jdbc.min-size=2 +quarkus.datasource.inventory.jdbc.max-size=12 + +# Doma's configuration bound to the above default datasource +quarkus.doma.dialect=h2 +quarkus.doma.batch-size=10 +quarkus.doma.fetch-size=50 +quarkus.doma.max-rows=500 +quarkus.doma.query-timeout=5000 +quarkus.doma.sql-load-script=import.sql + +# Doma's configuration bound to the above inventory datasource +quarkus.doma.inventory.dialect=h2 +quarkus.doma.inventory.batch-size=10 +quarkus.doma.inventory.fetch-size=50 +quarkus.doma.inventory.max-rows=500 +quarkus.doma.inventory.query-timeout=5000 +quarkus.doma.inventory.sql-load-script=import.sql+
You can inject the named Doma’s resource
+using the io.quarkus.agroal.DataSource qualifier as follows:
@Inject
+Config defaultConfig;
+
+@Inject
+Entityql defaultEntityql;
+
+@Inject
+NativeSql defaultNativeSql;
+
+@Inject
+@DataSource("inventory")
+Config invetoryConfig;
+
+@Inject
+@DataSource("inventory")
+Entityql inventoryEntityql;
+
+@Inject
+@DataSource("inventory")
+NativeSql inventoryNativeSql;dependencies {
+ annotationProcessor("org.seasar.doma:doma-processor:2.55.1")
+ implementation("org.seasar.doma:doma-core:2.55.1")
+ implementation("io.quarkiverse.doma:quarkus-doma:0.0.9")
+}...
+<properties>
+ <doma.version>2.55.1</doma.version>
+ <quarkus-doma.version>0.0.9</quarkus-doma.version>
+ <compiler-plugin.version>3.9.0</compiler-plugin.version>
+</properties>
+...
+<dependencies>
+ <dependency>
+ <groupId>org.seasar.doma</groupId>
+ <artifactId>doma-core</artifactId>
+ <version>${doma.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.doma</groupId>
+ <artifactId>quarkus-doma</artifactId>
+ <version>${quarkus-doma.version}</version>
+ </dependency>
+</dependencies>
+...
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>${compiler-plugin.version}</version>
+ <configuration>
+ <source>17</source>
+ <target>17</target>
+ <!-- the parameters=true option is critical so that RESTEasy works fine -->
+ <parameters>true</parameters>
+ <annotationProcessorPaths>
+ <path>
+ <groupId>org.seasar.doma</groupId>
+ <artifactId>doma-processor</artifactId>
+ <version>${doma.version}</version>
+ </path>
+ </annotationProcessorPaths>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The SQL dialect. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The batch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The fetch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The max rows. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The query timeout limit in seconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode: +
+
+* In dev and test modes, it defaults to
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The SQL file repository. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The naming convention controller. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The SQL log type that determines the SQL log format in exceptions. +
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+The SQL dialect. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The batch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The fetch size. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The max rows. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The query timeout limit in seconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Name of the file containing the SQL statements to execute when Doma starts. Its default value differs depending on the Quarkus launch mode: +
+
+* In dev and test modes, it defaults to
+
+Environment variable: |
+string |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Directory where persistence information is hold +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How long PostgreSQL will have to start before it times out. Value is milliseconds. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Optionally configurable port for the postgresql server. If not set, 62537 is picked. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Set string type +
+
+Environment variable: |
+string |
+
|
+
An alternative to quarkus-jdbc-postgres that rather than instantiating a pgsql server, uses zonky embedded library, reducing memory footprint.
+It is mainly oriented for single pod k8s deployments or integration testing.
+If you want to use this extension, you need to add the io.quarkiverse.embedded.postgresql:quarkus-embedded-postgresql extension to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.embedded.postgresql</groupId>
+ <artifactId>quarkus-embedded-postgresql</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Directory where persistence information is hold +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How long PostgreSQL will have to start before it times out. Value is milliseconds. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Optionally configurable port for the postgresql server. If not set, 62537 is picked. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Set string type +
+
+Environment variable: |
+string |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Keystore path. + |
+String |
++ |
+
+
+
+
+
+Keystore secret. + |
+String |
++ |
+
+
+
+
+
+Encryption key which was used to mask the keystore secret. + |
+String |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine if the File Vault extension is enabled + |
+boolean |
+
|
+
+
+
+
+
+
+Key Store configuration which can include Map |
+Map |
++ |
+
+
+
+
+
+Set the alias which is used to extract a secret from the key store as a 'user' property. + |
+boolean |
+true |
+
This project provides Quarkus CredentialsProvider and MicroProfile [ConfigSource](https://quarkus.io/guides/config-extending-support#custom-config-source) which extracts passwords and other sensitive data from Java KeyStore.
Java KeyStore is used as a file-based Vault. Sensitive data can be imported to and securely stored in this Vault as Java SecretKey values. Imported certificates are also supported.
If you would like to use File Vault as CredentialsProvider then add the io.quarkiverse.file-vault:quarkus-file-vault dependency in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.file-vault</groupId>
+ <artifactId>quarkus-file-vault</artifactId>
+</dependency>If you would like to use File Vault as ConfigSource then add the io.quarkiverse.file-vault:quarkus-file-vault-config-source dependency in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.file-vault</groupId>
+ <artifactId>quarkus-file-vault-config-source</artifactId>
+</dependency>First a Java Keystore has to be created and the data imported to it using a Java keytool and its -importpass option, for example:
keytool -importpass -alias quarkus_test -keystore dbpasswords.p12 -storepass storepassword -storetype PKCS12This command creates a keystore dbpasswords.p12 with a secret key whose alias is quarkus_test.
Once you have one or more keystore prepared you can use File Vault as CredentialsProvider with Quarkus extensions which integrate with CredentialsProvider.
For example, here is how you can configure it with Agroal:
quarkus.datasource.db-kind=postgresql
+quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/quarkus_test
+quarkus.datasource.credentials-provider=quarkus.file.vault.provider.db1
+
+quarkus.file.vault.provider.db1.path=dbpasswords.p12
+quarkus.file.vault.provider.db1.secret=storepassword
+quarkus.file.vault.provider.db1.alias=quarkus_test
+
+quarkus.hibernate-orm.database.generation=drop-and-create
+quarkus.hibernate-orm.log.sql=true
+quarkus.hibernate-orm.sql-load-script=import.sqlIn this example quarkus.datasource.credentials-provider refers to FileVaultCredentialsProvider as quarkus.file.vault.provider.db1.
The name format is quarkus.file.vault.provider.<name>, where <name> identifies a specific keystore configuration which in this case is:
quarkus.file.vault.provider.db1.path=dbpasswords.p12
+quarkus.file.vault.provider.db1.secret=storepassword
+quarkus.file.vault.provider.db1.alias=quarkus_testYou can configure as many keystores as required.
+Note setting a keystore alias (quarkus.file.vault.provider.db1.alias=quarkus_test) in the properties is optional. Instead you can pass it like this:
quarkus.datasource.db-kind=postgresql
+quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/quarkus_test
+quarkus.datasource.credentials-provider=quarkus.file.vault.provider.db1.quarkus_test
+
+quarkus.file.vault.provider.db1.path=dbpasswords.p12
+quarkus.file.vault.provider.db1.secret=storepasswordThis is way you can refer to the same keystore but use a different alias each time.
+FileVaultCredentialsProvider will return the extracted secret key as a password property. It will also use alias value to return a user property. The extensions such as Agroal will accept both properties.
However, you can choose for only a password property be returned with quarkus.file.vault.set-alias-as-user=false. In this case you will need to configure a username with the extension specific property, for example, when working with Agroal you can use quarkus.datasource.username.
Finally, if a keystore alias is not set in application.properties (for example, quarkus.file.vault.provider.db1.alias=quarkus_test) and is not encoded in the credentials provider name (for example, quarkus.datasource.credentials-provider=quarkus.file.vault.provider.db1.quarkus_test) then the provider will return all the keystore entries.
You can access this CredentialsProvider like this from your code:
package io.quarkiverse.filevault.it;
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.cert.CertificateFactory;
+import java.security.cert.X509Certificate;
+
+import java.util.Map;
+import io.quarkus.credentials.CredentialsProvider;
+import io.quarkus.credentials.runtime.CredentialsProviderFinder;
+...
+
+CredentialsProvider cp = CredentialsProviderFinder.find("quarkus.file.vault");
+
+// Use a `quarkus_test` alias to get a secret value from the keystore `db1`
+// where the alias is set in `application.properties`:
+
+cp.getCredentials("quarkus.file.vault.provider.db1");
+
+// Use a `quarkus_test` alias to get a secret value from the keystore `db1` by passing it directly to the provider:
+
+Map<String, String> props = cp.getCredentials("quarkus.file.vault.provider.db1.quarkus_test");
+String user = props.get(CredentialsProvider.USER_PROPERTY_NAME);
+String secret = props.get(CredentialsProvider.PASSWORD_PROPERTY_NAME);
+
+// Use a `quarkus_cert` alias to get the encoded `X509Certificate` from the keystore `db1` by passing it directly to the provider:
+
+Map<String, String> props = cp.getCredentials("quarkus.file.vault.provider.db1.quarkus_cert");
+String user = props.get(CredentialsProvider.USER_PROPERTY_NAME);
+String encodedCert = props.get("certificate");
+CertificateFactory cf = CertificateFactory.getInstance("X.509");
+X509Certificate cert = (X509Certificate) cf
+ .generateCertificate(new ByteArrayInputStream(encodedCert.getBytes(StandardCharsets.ISO_8859_1)));Once you have a keystore prepared you can use File Vault as ConfigSource.
For example, here is how you can configure it with Agroal:
quarkus.datasource.db-kind=postgresql
+quarkus.datasource.jdbc.url=jdbc:postgresql://localhost/quarkus_test
+quarkus.datasource.username=quarkus_test
+quarkus.datasource.password=${quarkus_test}
+
+quarkus.file.vault-config-source.keystore-path=dbpasswords.p12
+quarkus.file.vault-config-source.keystore-secret=storepassword
+
+quarkus.hibernate-orm.database.generation=drop-and-create
+quarkus.hibernate-orm.log.sql=true
+quarkus.hibernate-orm.sql-load-script=import.sqlYou need to specify a keystore password in application.properties for Quarkus File Vault be able to extract secrets from the keystore.
+However this keystore password is a sensitive value and therefore you should consider how to minimize a risk of leaking it and how to protect it.
One important thing you should be aware of is that leaking this password does not necessarily mean the actual secrets stored in the keystore will also be leaked since an unauthorized person will also need to access the actual keystore file. Restricting an access to the keystore file to a limited number of roles and having Quarkus processes running in one of these roles will make it harder for anyone outside of this group access the keystore. The keystore password can be set as an environment variable and this password should be periodically changed to limit a window during which an attacker can try to get to the keystore.
+However if you do need to avoid setting a keystore password in application.properties then you can use a custom MicroProfile ConfigSource, for example.
package io.quarkiverse.filevault.it;
+
+import java.util.Set;
+
+import org.eclipse.microprofile.config.spi.ConfigSource;
+
+public class KeyStoreConfigSource implements ConfigSource {
+
+ @Override
+ public Set<String> getPropertyNames() {
+ return Set.of("db1.storepassword");
+ }
+
+ @Override
+ public String getValue(String propertyName) {
+ return "db1.storepassword".equals(propertyName) ? "storepassword" : null;
+ }
+
+ @Override
+ public String getName() {
+ return "file-vault-config-source";
+ }
+
+}add org.eclipse.microprofile.config.spi.ConfigSource service provider entry listing io.quarkiverse.filevault.it.KeyStoreConfigSource to META-INF/services.
Next, refer to the keystore password like this if you use File Vault as CredentialsProvider:
quarkus.file.vault.provider.db1.path=dbpasswords.p12
+quarkus.file.vault.provider.db1.secret=${db1.storepassword}or refer to the keystore password like this if you use File Vault as ConfigSource:
quarkus.file.vault-config-source.keystore-path=dbpasswords.p12
+quarkus.file.vault-config-source.keystore-secret=${db1.storepassword}Please note that in this example, hardcoding a keystore password such as db1.storepassword in KeyStoreConfigSource is only done to simplify the documentation.
+In real world applications, custom ConfigSource implementations will read it from a DB or other secure storage.
For example, Quarkus Vault extension provides a ConfigSource which can fetch secrets from a HashiCorp Vault.
If you need to mask a keystore password (quarkus.file.vault.provider.<name>.secret) you will need to build and package the Vault Utils project.
mvn clean installAfter that, you will be able to execute the --help command:
$ java -jar target/quarkus-app/quarkus-run.jar --help
+
+Usage: Encrypt Secret Util [-hV] [-e=<encryptionKey>] -p=<keystorePassword>
+ -e, --encryption-key=<encryptionKey> (optional) Encryption Key
+ -h, --help Show this help message and exit.
+ -p, --keystore-password=<keystorePassword> (mandatory) Keystore password
+ -V, --version Print version information and exit.The only mandatory parameter is a keystore password: -p, --keystore-password.
+The encryption key will be auto-generated unless it is provided with: -e, --encryption-key.
Here is how you can mask a keystore password:
+$ java -jar target/quarkus-app/quarkus-run.jar -p storedpass -e justsomestringhereYou should see something like this at the output:
+#######################################################################################################################################################
+Please add the following parameters to application.properties if you use File Vault as CredentialsProvider and replace the <keystore-name>:
+
+quarkus.file.vault.provider.<name>.encryption-key=justsomestringhere
+quarkus.file.vault.provider.<name>.secret=4VLLc9bk+WMnQMR3ezJcpw
+
+Please add the following parameters to application.properties if you use File Vault as ConfigSource:
+
+quarkus.file.vault-config-source.encryption-key=justsomestringhere
+quarkus.file.vault-config-source.keystore-secret=4VLLc9bk+WMnQMR3ezJcpw
+########################################################################################################################################################Note even though you now have the keystore password storedpass masked as 4VLLc9bk+WMnQMR3ezJcpw, the encryption key which was used to mask it remains in a clear text so it should be protected similarly to how an unmasked keystore password should be, for example, using a ConfigSource or environment variables. As such the main advantage of masking the password is to introduce an extra level of indirection to make it more complex to get to the keystore password itself.
Quarkus Vault extension can be used as a ConfigSource with Quarkus File Vault to protect the keystore passwords, but it can also act as an alternative to Quarkus File Vault as a CredentialsProvider implementation.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine if the File Vault extension is enabled + |
+boolean |
+
|
+
+
+
+
+
+
+Key Store configuration which can include Map |
+Map |
++ |
+
+
+
+
+
+Set the alias which is used to extract a secret from the key store as a 'user' property. + |
+boolean |
+true |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Keystore path. + |
+String |
++ |
+
+
+
+
+
+Keystore secret. + |
+String |
++ |
+
+
+
+
+
+Encryption key which was used to mask the keystore secret. + |
+String |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way. + |
+list of string |
+
|
+
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located + |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. + |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. + |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. + |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. + |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. + |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. + |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way.
+Defaults relevant for this option are documented on
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The base path of this template set. Template set is a triple of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of globs to select FreeMarker templates for inclusion in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of globs not to include in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The base path of this template set. Template set is a triple of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of globs to select FreeMarker templates for inclusion in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of globs not to include in the native image.
+
+
+Environment variable: |
+list of string |
++ |
Freemarker is a very popular and mature templating engine. Its integration as a Quarkus extension +provides developers ease of configuration, and offers support for native images. +In this guide, you will learn how to easily render Freemarker templates in your application.
+If you want to use Freemarker you need to add the quarkiverse-freemarker extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkiverse-freemarker</artifactId>
+ <version>{project-version}</version>
+</dependency>We’ll start with a very simple template:
+Hello ${name}! (1)| 1 | +${name} is a value expression that is evaluated when the template is rendered. |
+
Now let’s inject the template in the resource class.
+package org.acme.quarkus.sample;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.QueryParam;
+
+import freemarker.template.Template;
+import io.quarkiverse.freemarker.runtime.TemplatePath;
+
+@Path("hello")
+public class HelloResource {
+
+ @Inject
+ @TemplatePath("hello.ftl") (1)
+ Template hello;
+
+ @GET
+ @Produces(TEXT_PLAIN)
+ public String hello(@QueryParam("name") String name) throws IOException, TemplateException {
+ StringWriter stringWriter = new StringWriter();
+ hello.process(Map.of("name", name), stringWriter); (2)
+ return stringWriter.toString();
+ }
+}| 1 | +The @TemplatePath qualifier specifies the template name, found in either jar resource paths or external file paths. |
+
| 2 | +Map.of("name", name) provides the model. |
+
If your application is running, you can request the endpoint:
+$ curl -w "\n" http://localhost:8080/hello?name=bob
+Hello bob!The application code can either directly inject a Freemarker Template bean as we saw above.
+In that case it must provide a TemplatePath qualifier annotation with the name
+of the template to select.
Or it can inject a Freemarker Configuration bean, from which templates
+can be obtained programmatically. The Configuration is a Singleton
+DefaultBean that can be replaced by an application provided implementation.
The default Configuration bean is configured from quarkus exposed
+properties. Among those, 2 are build time:
resource-paths is a list of resource paths contained in the classpath (e.g.
+typically in jars of the application). Each path is traversed recursively, and
+all files get added as native resources when building a native image.
directives is a map of directive alias to directive class name. Each directive
+class is added as a shared variable in the Configuration bean.
Here is an example of using a Configuration bean instead of a Template bean:
@Inject
+ Configuration configuration;
+
+ @GET
+ @Produces(TEXT_PLAIN)
+ public String hello(@QueryParam("name") String name, @QueryParam("ftl") String ftl) throws IOException, TemplateException {
+ StringWriter stringWriter = new StringWriter();
+ configuration.getTemplate(ftl).process(model, stringWriter);
+ return stringWriter.toString();
+ }The rest of the configuration properties can be provided at runtime, such as
+a list of external filesystem paths where to find additional templates,
+and optional properties that can be configured on the Freemarker Configuration class.
Freemarker can be extended using custom directives. For instance if we wanted
+to transform some text in base64, we could write:
package org.acme.quarkus.sample;
+
+public class Base64Directive implements TemplateDirectiveModel {
+ @Override
+ public void execute(Environment environment, Map map, TemplateModel[] templateModels, TemplateDirectiveBody body)
+ throws TemplateException, IOException {
+ StringWriter sw = new StringWriter();
+ body.render(sw);
+ byte[] bytes = Base64.getEncoder().encode(sw.toString().getBytes(UTF_8));
+ environment.getOut().write(new String(bytes, UTF_8));
+ }
+}Then we would have to configure the application with:
+quarkus.freemarker.directives.base64=org.acme.quarkus.sample.Base64DirectiveAnd finally, we would use it in templates such as:
+Hello <@base64>$\{name}</@base64>!This would be rendered as:
+Hello Ym9i!Freemarker supports Map or Object based data models.
+When using objects, it is important to configure
+quarkus.freemarker.object-wrapper-expose-fields=true if model classes
+do not have getters.
Additionnaly, they should be annotated with
+@RegisterForReflection to support native images.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way.
+Defaults relevant for this option are documented on
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The base path of this template set. Template set is a triple of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of globs to select FreeMarker templates for inclusion in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of globs not to include in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The base path of this template set. Template set is a triple of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of globs to select FreeMarker templates for inclusion in the native image.
+
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A comma separated list of globs not to include in the native image.
+
+
+Environment variable: |
+list of string |
++ |
This extension allows you to use Java FX to your Quarkus application.
+In order to use this extension, you need to add the io.quarkiverse.fx:quarkus-fx dependency to your project.
Maven
+<dependency>
+ <groupId>io.quarkiverse.fx</groupId>
+ <artifactId>quarkus-fx</artifactId>
+ <version>0.3.0</version>
+</dependency>Gradle
+dependencies {
+ implementation 'io.quarkiverse.fx:quarkus-fx:0.3.0'
+}The extension allows using cdi features in JavaFX controller classes.
+The FXMLLoader is made a CDI bean and can be injected in your application.
@Inject
+FXMLLoader fxmlLoader;
+
+public void load() {
+ Parent root = this.fxmlLoader.load(this.getClass().getResourceAsStream("/app.fxml"));
+ Scene scene = new Scene(root);
+ stage.setScene(scene);
+ stage.show();
+}public class MyFxmlController {
+
+ @Inject
+ MyService myService;
+
+ @FXML
+ private void onButtonClicked() {
+ this.myService.doSomething();
+ }
+}The application will automatically be launched (thanks to a call to javafx.application.Application::launch) when the extension is present.
If you need to customize the launch, you can provide a custom @QuarkusMain, such as :
package io.quarkiverse.fx.fxapp;
+
+import io.quarkiverse.fx.FxApplication;
+import io.quarkus.runtime.QuarkusApplication;
+import io.quarkus.runtime.annotations.QuarkusMain;
+import javafx.application.Application;
+
+@QuarkusMain
+public class QuarkusFxApplication implements QuarkusApplication {
+ @Override
+ public int run(final String... args) {
+ Application.launch(FxApplication.class, args);
+ return 0;
+ }
+}When the application is started, you can get obtain access to the primary Stage instance by observing the FxStartupEvent CDI event :
void onStart(@Observes final FxStartupEvent event) {
+ Stage stage = event.getPrimaryStage();
+}@RunOnFxThread annotation offers for a convenient way to execute the target on JavaFX UI thread (JavaFX Application Thread).
Annotation can be applied on method level or on class level (to mark all methods within a class)
+Example
+VBox vBox = new VBox();
+
+public void start(@Observes final FxStartupEvent event) {
+
+ Stage = event.getPrimaryStage();
+
+ Scene scene = new Scene(this.vBox);
+ stage.setScene(scene);
+ stage.show();
+
+ try (ExecutorService executorService = Executors.newVirtualThreadPerTaskExecutor()) {
+ executorService.submit(() -> this.showNode(this.createExpensiveNode()));
+ }
+}
+
+Node createExpensiveNode() {(1)
+ return new Label(LocalTime.now().toString());
+}
+
+@RunOnFxThread
+void showNode(final Node node) {(2)
+ this.vBox.getChildren().add(node);
+}| 1 | +createExpensiveNode method will be executed in a thread from executor service |
+
| 2 | +showNode method will be executed on JavaFx UI thread (JavaFX Application Thread) |
+
To synchronize the application with JavaFX readiness, one can use the FxStartupLatch bean.
It provides an await method that is released when JavaFX app is ready (primary Stage instance is available).
That is used in the inner @RunOnFxThread to ensure app is ready.
@Inject
+FxStartupLatch startupLatch;
+
+// Blocking until FX env is ready
+startupLatch.await();
+
+// FX is readyAlternatively, the FxStartupEvent can be observed.
Example of a SkipPredicated that can be used in conjunction with a @Scheduled
@Singleton
+public class FxApplicationNotStarted implements SkipPredicate {
+
+ private volatile boolean started;
+
+ void onFxStartup(@Observes final FxStartupEvent event) {
+ this.started = true;
+ }
+
+ @Override
+ public boolean test(final ScheduledExecution execution) {
+ return !this.started;
+ }
+}GitHub Actions have to be hosted in a GitHub repository that is dedicated to the action.
+Thus the first step in the creation of a GitHub Action is to create a new GitHub repository.
+Create a completely empty repository (e.g. no README nor .gitignore nor license file), that will make the next steps easier.
+You can add them later on.
| + + | +
+
+
+Do not initialize or clone the repository. +We will initialize a local Git repository and push it to GitHub in the following steps. + |
+
The full name of your repository (either username/repository-name or org-name/repository-name) is going to be useful in the next step so keep it handy.
+In the following sections, we will consider it named my/action-github-repository.
| + + | +
+
+
+If you created a private repository to host your action, +make your action visible to your other private repositories by following these instructions. +
+
+Note that actions stored in private repositories are not runnable in public repositories. + |
+
A Quarkus GitHub Action is a standard Quarkus application.
+You can create one including the Quarkus GitHub Action extension using the following Quarkus CLI command:
+| + + | +
+Make sure you use the 📋 button to copy the command.
+ |
+
quarkus create app \
+ -x quarkus-github-action \ (1)
+ org.acme:my-github-action:999-SNAPSHOT \ (2)
+ --name="My Action" \ (3)
+ --description="Description of my action" \ (4)
+ --data=quarkiverse-github-action-codestart.github-repository=my/action-github-repository (5)| 1 | +The Quarkus GitHub Action extension. Add it right away so that the tooling can generate a full Quarkus GitHub Action application using Codestarts. | +
| 2 | +The GAV of your Maven project. | +
| 3 | +The name of the action. It is used both in the pom.xml and in the descriptor of the action (action.yml). |
+
| 4 | +The description of the action. It is used both in the pom.xml and in the descriptor of the action (action.yml). |
+
| 5 | +The full name of the GitHub repository hosting the action (in the form username/repository-name or org-name/repository-name). |
+
| + + | +
+
+
+On Windows and macOS, it is recommended to concatenate all the options on one line (without |
+
| + + | +
+
+
+We highly recommend the usage of the Quarkus CLI but if you cannot install it or prefer using Maven, +you can create a Quarkus GitHub Action project using the following Maven command: +
+
+
+
+
+
+
+
+
+
+
|
+
This command creates a regular Quarkus Maven project. +You can add additional Quarkus extensions or Java dependencies.
+Once the project is created, go to the my-github-action directory:
cd my-github-actionIf you have carefully followed the instructions above, you should be in your newly created project directory.
+The next step is to push your GitHub Action to its GitHub repository (GitHub describes the instructions in the repository page):
+git init
+git add .
+git commit -m "Init the project"
+git branch -M main
+git remote add origin git@github.com:my/action-github-repository.git (1)
+git push -u origin main| 1 | +Replace my/action-github-repository with the full name of the repository you created to host the GitHub Action. |
+
| + + | +
+
+
+Be careful to strictly follow the organization of the created project:
+the |
+
Once you pushed the repository to GitHub,
+the Publish action artifact to GitHub project’s Maven repository workflow will automatically publish your action to the Maven repository of the action’s repository.
Wait for it to complete before using your action.
+Go to the Actions tab of your action’s repository to check the workflow status.
| + + | +
+
+
+When pushing new code to your action,
+the action will be updated only after the |
+
Now is a good time to take a step back and have a closer look at what we pushed to the repository:
+.
+├── README.md (1)
+├── mvnw (2)
+├── mvnw.cmd (2)
+├── pom.xml (3)
+├── action.yml (4)
+├── action.docker.yml (5)
+└── src
+ └── main
+ ├── docker (6)
+ │ ├── Dockerfile.jvm
+ │ ├── Dockerfile.legacy-jar
+ │ ├── Dockerfile.native
+ │ └── Dockerfile.native-micro
+ ├── java
+ │ └── org
+ │ └── acme
+ │ └── MyAction.java (7)
+ └── resources
+ └── application.properties (8)| 1 | +The root README.md. Add some content here so that users can understand what your GitHub Action does. |
+
| 2 | +The Maven wrapper. | +
| 3 | +The pom.xml descriptor as we created a Maven project. Nothing specific here except a <distributionManagement> deploying the artifact to the repository’s Maven repository. |
+
| 4 | +The action.yml descriptor, more on that later. |
+
| 5 | +An alternative action.yml if you want to use a Docker-packaged native executable, more on that later. |
+
| 6 | +Some default Dockerfiles provided for Quarkus. Only useful if using action.docker.yml. |
+
| 7 | +A simple GitHub Action example. | +
| 8 | +An application.properties with some default configuration properties to silence Quarkus at startup (no banner, only log errors). |
+
action.yml is the GitHub Action descriptor and it is important to understand what it is doing.
The default one you obtain when creating a GitHub Action as described above is the following:
+name: 'My Action' (1)
+description: 'Description of my action' (2)
+inputs:
+ github-token: (3)
+ description: 'GitHub token'
+ required: true
+ action: (4)
+ description: 'Name of the action (if named)'
+ required: false
+runs:
+ using: "composite" (5)
+ steps:
+ - name: Inject quarkus-github-action repository credentials (6)
+ shell: bash
+ run: |
+ if [ -f ~/.m2/settings.xml ]; then
+ if ! grep -q '<id>quarkus-github-action</id>' ~/.m2/settings.xml; then
+ sed -i.bak 's@</servers>@<server><id>quarkus-github-action</id><username>${env.GITHUB_ACTOR}</username><password>${env.GITHUB_TOKEN}</password></server></servers>@' ~/.m2/settings.xml
+ fi
+ else
+ mkdir -p ~/.m2/
+ cat <<\EOF > ~/.m2/settings.xml
+ <?xml version="1.0"?>
+ <settings>
+ <servers>
+ <server>
+ <id>quarkus-github-action</id>
+ <username>${env.GITHUB_ACTOR}</username>
+ <password>${env.GITHUB_TOKEN}</password>
+ </server>
+ </servers>
+ </settings>
+ EOF
+ fi
+ - name: Set up JBang
+ uses: jbangdev/setup-jbang@main (7)
+ - name: Run the action
+ id: action
+ run: jbang --java 21 --fresh --repos 'quarkus-github-action=https://maven.pkg.github.com/gsmet/my-github-action/' --repos 'mavencentral' org.acme:my-github-action:999-SNAPSHOT (8)
+ shell: bash
+ env:
+ JSON_INPUTS: ${{ toJSON(inputs) }} (9)
+ GITHUB_TOKEN: ${{ inputs.github-token }} (10)| 1 | +The name of the action passed at creation. | +
| 2 | +The description of the action passed at creation. | +
| 3 | +The GitHub token is mandatory if you stick to publishing the action Maven artifact to the GitHub hosted Maven repository. | +
| 4 | +The optional action name, used for routing named actions to action methods. | +
| 5 | +The action is a composite action which has a few specificities. You can add additional steps if required. | +
| 6 | +Inject the credentials for the quarkus-github-action repository in the ~/.m2/settings.xml, allowing authenticated access to GitHub-hosted Maven repositories. |
+
| 7 | +Install JBang, which is used to run the jar file. | +
| 8 | +Execute the jar file. It is downloaded from the Maven repository of the action GitHub repository. JBang will download a JDK if necessary. | +
| 9 | +Inputs are not transmitted to composite actions so we need to push them manually. The action will deserialize the JSON input automatically and make the inputs available. | +
| 10 | +The token is required to download the artifact from the GitHub hosted repository and will be used to authenticate the GitHub clients you can inject in your action code. | +
| + + | +
+
+
+A composite action can be executed on all sorts of hosts, Linux, macOS or Windows. + |
+
| + + | +
+
+
+Given it is a composite action, you can add additional steps to the action. +
+
+You can also tweak the existing steps of the action.
+For instance, if you want to use a Java version different from the one used by default for executing your code,
+you can adjust the
+
+
+
+
+
+
|
+
Another alternative is to build a Docker image with your application and use it as a Docker container action.
+In the generated application, we provide both an alternative action.docker.yml (that you need to rename to action.yml) and a workflow file to publish the Docker image to the Docker repository of the action repository.
| + + | +
+
+
+Using Docker container actions comes with some constraints as you can only run them on Linux hosts. +
+
+It is a limitation of GitHub Actions. +
+
+Except if you have specific requirements, it is recommended to use the default composite action approach. + |
+
The default application.properties contains some configuration properties to make Quarkus startup silent:
quarkus.log.category."io.quarkus".level=SEVERE
+quarkus.banner.enabled=falseThis file is just an example of a very simple action:
+package org.acme;
+
+import io.quarkiverse.githubaction.Action;
+import io.quarkiverse.githubaction.Commands;
+
+public class MyAction {
+
+ @Action
+ void action(Commands commands) {
+ commands.notice("Hello from Quarkus GitHub Action");
+
+ commands.appendJobSummary(":wave: Hello from Quarkus GitHub Action");
+ }
+}The action() method will be called when the action is run on GitHub Actions and will:
Log a Hello from Quarkus GitHub Action notice
Append Hello from Quarkus GitHub Action to the job summary
From there, everything is ready to run your simple GitHub Action,
+provided you waited for the Publish action artifact to GitHub project’s Maven repository initial workflow run of your action’s repository to finish.
| + + | +
+
+
+To check if the |
+
Create a workflow in a separate repository with the following step:
+ - name: Run my action
+ uses: my/action-github-repository@main
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }} (1)| 1 | +${{ secrets.GITHUB_TOKEN }} is a temporary secret created by GitHub when initializing the workflow, you don’t need to define it yourself.
+The token is required when consuming the GitHub REST or GraphQL APIs so, in most cases, you need to pass it to the action. |
+
Obviously, you can do a lot more with Quarkus GitHub Action and we describe all its features in the Developer reference.
+Here is all you need to know to develop GitHub Actions with Quarkus GitHub Action.
+An action method is a method that is going to be executed when the GitHub Action is executed.
+You can have several action methods, in which case they will be executed in no particular order.
+You can also name your action methods to be able to trigger a specific method by passing an input to the action.
+An action method is a method of a public class and is annotated with @io.quarkiverse.githubaction.Action:
public class MyAction {
+
+ @Action
+ void action() {
+ // do something
+ }
+}As explained above, you can have several action methods, and they can be in several classes:
+public class MyAction1 {
+
+ @Action
+ void action1() {
+ // do something
+ }
+
+ @Action
+ void action2() {
+ // do something
+ }
+}
+
+public class MyAction2 {
+
+ @Action
+ void action3() {
+ // do something
+ }
+
+ @Action
+ void action4() {
+ // do something
+ }
+}When executing the action, action1(), action2(), action3(), and action4() will be executed in no particular order.
With this kind of setup, you can call your action with:
+ - name: Run my action
+ uses: my/action-github-repository@main
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}It might be practical for you to develop one GitHub Action for several related purposes. +Quarkus GitHub Action comes with a nice feature for that: named actions.
+public class MyAction1 {
+
+ @Action("action1")
+ void action1() {
+ // do something
+ }
+
+ @Action("action2")
+ void action2() {
+ // do something
+ }
+}You can then specifically get action1() to run with:
- name: Run my action
+ uses: my/action-github-repository@main
+ with:
+ action: action1 (1)
+ github-token: ${{ secrets.GITHUB_TOKEN }}| 1 | +action is a special input that is used to route the action to the named action method, here action1. |
+
Most of the other features of Quarkus GitHub Action are handled via parameter injection: +you can inject parameters of different types into your action methods, +Quarkus GitHub Action will automatically pass the parameters, properly initialized.
+You can of course pass several of the following parameter types to the action methods.
+Inputs are values that are passed from the GitHub workflow to the GitHub Action, for instance with the following step:
+ - name: Run my action
+ uses: my/action-github-repository@main
+ with:
+ my-input: "My value"
+ github-token: ${{ secrets.GITHUB_TOKEN }}It is required to declare the inputs in the action.yml descriptor:
name: 'My Action'
+description: 'Description of my action'
+inputs:
+ my-input:
+ description: 'My input'
+ required: true (1)
+ default: 'My default value' (2)
+
+# ... rest of the descriptor ...| 1 | +An input can be required or optional (optional by default). | +
| 2 | +An input can have a default value. | +
Getting the my-input input from an action method is easy:
@Action
+ void action(Inputs inputs) {
+ String myInput = inputs.getRequired("my-input");
+ }Inputs offers all sorts of utility methods such as get(String) which returns an Optional, getRequired(String) which makes sure the input is provided, getBoolean(String), getLong(String), getInteger(String)…
You can also get all the inputs as a Map<String, String> with all().
| + + | +
+
+
+Contributions are welcome to add more utility methods to |
+
You can find more information about inputs in the GitHub Actions documentation.
+A GitHub action is executed within a context, which provides all sorts of information about the execution environment of the action.
+To access the context, inject a Context instance into your action method:
@Action
+ void action(Context context) {
+ String runnerOs = context.getRunnerOs(); (1)
+
+ context.print(); (2)
+ }| 1 | +Get the GitHub Actions runner operating system. | +
| 2 | +Print all the available values. Useful to discover what is provided by the context. | +
GitHub Actions provides various commands which allows you to interact with the workflow run.
+For instance, you can set output variables, attach a job summary…
+All these commands are made available through a io.quarkiverse.githubaction.Commands instance,
+that you can inject into your action methods.
Outputs are an important part of GitHub Actions. +They are used to export values from an action +so that they can be consumed in further steps.
+The first step in defining an output is to modify the action.yml descriptor to declare the output:
outputs:
+ my-output:
+ value: ${{ steps.action.outputs.my-output }}This is required because we use a composite action. +The output from the inner step needs to be mapped to an output of the action.
+Next step is to actually produce the output in your action method:
+ @Action
+ void action(Commands commands) {
+ commands.setOutput("my-output", "My value");
+ }| + + | +
+
+
+You can produce several outputs. + |
+
And finally you can consume the output in another step of a GitHub Actions workflow:
+ steps:
+ - name: Run my action
+ id: my-action
+ uses: my/action-github-repository@main
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ - name: Display output
+ run: |
+ echo "${{steps.my-action.outputs.my-output}}"A job summary is a Markdown content that you can attach to workflow run summary page. +It can be used to provide an execution report for instance.
+Adding a job summary is easy:
+ @Action
+ void action(Commands commands) {
+ commands.jobSummary("# Markdown content"); (1)
+ commands.appendJobSummary("Some additional content"); (2)
+ commands.removeJobSummary(); (3)
+ }| 1 | +Set the job summary to # Markdown content. |
+
| 2 | +Append Some additional content to a potentially preexisting job summary. |
+
| 3 | +Remove the job summary. Not extremely useful but it is there just in case. | +
One common use case of GitHub Actions is to perform calls on the GitHub REST or GraphQL APIs.
+Quarkus GitHub Action has this use case covered and you can inject in your action methods:
+An authenticated GitHub client (from the Hub4j GitHub API)
An authenticated DynamicGraphQLClient client (from SmallRye GraphQL)
@Action
+ void action(GitHub gitHub) throws IOException {
+ gitHub.getRepository("another/repository");
+ } @Action
+ void action(DynamicGraphQLClient graphqlClient) throws ExecutionException, InterruptedException {
+ graphqlClient.executeSync("your GraphQL query");
+ }| + + | +
+
+
+The clients are authenticated using the provided GitHub token. + |
+
A GitHub workflow run is started when an event is triggered, +and to this event corresponds a payload which contains all the information about the event.
+Typically, when an issue is opened, you can obtain an issues payload.
+When a pull request is opened, you can obtain a pull_request payload.
Quarkus GitHub Action is able to parse the payload and inject it into an action method.
+Payloads can also be used to restrict the use of an action to a particular event type, +or to execute code that is specific to an event type.
+A payload comes with an authenticated GitHub client, +which makes it possible to access the GitHub REST API.
+The following action method is executed any time an issues event is triggered
+(for instance when an issue is opened or edited):
@Action
+ void test(@Issue GHEventPayload.Issue issuePayload) throws IOException {
+ GHIssue issue = issuePayload.getIssue();
+
+ System.out.println("Repository: " + issue.getRepository().getFullName()); (1)
+ System.out.println("Issue title: " + issue.getTitle());
+
+ issue.comment("A new comment"); (2)
+ }| 1 | +Access some information from the payload. | +
| 2 | +Create a new comment in the issue. | +
| + + | +
+
+
+Given you can have several action methods in the same GitHub Actions, +it is possible to execute code for several event types. + |
+
You can restrict the action method to a particular action of the event type. +The following action method is executed when a new issue is opened:
+ @Action
+ void test(@Issue.Opened GHEventPayload.Issue issuePayload) {
+ System.out.println("Repository: " + issuePayload.getIssue().getRepository().getFullName());
+ System.out.println("Issue title: " + issuePayload.getIssue().getTitle());
+ }| + + | +
+
+
+You can find the list of all the supported event types in the Quarkus GitHub App documentation. + |
+
You can easily inject config files stored in the repository for which the action is run.
+If the file is a YAML or JSON file, it can be automatically deserialized by Jackson.
+If the file is a .txt file, it can be injected as a String.
+Text files can be used to inject templates.
For now, the file is read from the default branch of the repository (typically main).
If the path is relative, the file is searched in the .github directory.
+If the path is absolute, the file is searched from the root of the repository.
@Action
+ void test(@ConfigFile("example-config-file.yml") ConfigFileBean configFileBean) { (1)
+ System.out.println("Value 1: " + configFileBean.value1);
+ System.out.println("Value 2: " + configFileBean.value2);
+ }
+
+ public static class ConfigFileBean {
+
+ public String value1;
+
+ public String value2;
+ }| 1 | +Read .github/example-config-file.yml from the default branch of the repository and inject the values into ConfigFileBean via Jackson deserialization. |
+
If you need to debug the behavior of the Quarkus GitHub Action extension,
+you can enable debug logging by adding the following configuration property to your application.properties:
quarkus.log.category."io.quarkiverse.githubaction".level=DEBUGNow is time to add some tests and push your GitHub Action to production.
+This extensions simplifies the development of GitHub Actions in Java with Quarkus.
+Developing custom GitHub Actions is extremely useful. +People usually develop them in JavaScript or TypeScript.
+This Quarkus extension provides an alternative to develop your GitHub Actions in Java. +It also brings the ability to share code between GitHub Apps and GitHub Actions +by using both Quarkus GitHub App and Quarkus GitHub Action.
+Why use Quarkus GitHub Action to develop your GitHub Actions:
+If you are more familiar with the Java ecosystem, it comes in handy.
+It doesn’t bring any Quarkus-induced complexity, it just makes things easier.
+It comes with several nice features to simplify the development of GitHub Actions in Java.
+It relies on the Hub4j GitHub API so you have all the GitHub REST API at your fingertips.
+You can also inject an authenticated GraphQL client to talk to the GitHub GraphQL API.
+A simple GitHub Action will look like:
+class MyAction {
+
+ @Action
+ void doSomething() {
+ // do something useful here
+ }
+}The extension takes care of all the wiring.
+Let’s start by creating our first GitHub Action.
+The Maven project created by the extension contains all the necessary GitHub Actions workflows to push your GitHub Action to production.
+The versioning model used for GitHub Action is a bit hard to map to the Maven versioning model.
+However, it is possible to come up with a reasonable solution that allows you to have a main version and also more stable releases.
We recommend to keep the main version as 999-SNAPSHOT, a workflow will publish it to the Maven repository to the GitHub repository.
+This will be your rolling main version.
If you want to maintain a stable version, follow these instructions:
+create a Git branch locally, for instance v1
adjust the version in the POM, for instance with mvn versions:set -DnewVersion=1.0.2-SNAPSHOT -DgenerateBackupPoms=false
adjust the version of the jar in the action.yml
commit your version adjustments
+push your branch to the GitHub repository
+wait for GitHub Actions to deploy the new version to the Maven repository
+you can then reference your action with my/action-github-repository@v1
Quarkus GitHub Actions are regular Quarkus command mode applications and can be tested with @QuarkusMainTest.
A simple test would look like:
+@QuarkusMainTest
+public class SimpleActionTest {
+
+ @Test
+ @Launch(value = {})
+ public void testLaunchCommand(LaunchResult result) {
+ assertThat(result.getOutput()).contains(SimpleAction.TEST_OUTPUT);
+ }
+}While a more involved test pushing inputs and a suitable environment for output command execution would look like:
+@QuarkusMainTest
+@TestProfile(CommandsActionTestProfile.class) (1)
+public class CommandsActionTest {
+
+ @Test
+ @Launch(value = {})
+ public void testLaunchCommand(LaunchResult result) throws IOException {
+ assertThat(Path.of(System.getProperty("java.io.tmpdir") + "/temp-github-output.txt")).content()
+ .contains("testOutputKey=test output value" + System.lineSeparator());
+ }
+
+ public static class CommandsActionTestProfile implements QuarkusTestProfile {
+
+ @Override
+ public Set<Class<?>> getEnabledAlternatives() {
+ return Set.of(MockInputsInitializer.class, MockCommandsInitializer.class);
+ }
+ }
+
+ @Alternative
+ @Singleton
+ public static class MockInputsInitializer implements InputsInitializer {
+
+ @Override
+ public Inputs createInputs() {
+ return new DefaultTestInputs(Map.of(Inputs.ACTION, CommandsAction.ACTION_NAME)); (2)
+ }
+ }
+
+ @Alternative
+ @Singleton
+ public static class MockCommandsInitializer implements CommandsInitializer {
+
+ @Override
+ public Commands createCommands() {
+ try {
+ Path githubOutputPath = Path.of(System.getProperty("java.io.tmpdir") + "/temp-github-output.txt");
+ Files.deleteIfExists(githubOutputPath);
+
+ return new CommandsImpl(Map.of(EnvFiles.GITHUB_OUTPUT, githubOutputPath.toString()));
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+ }
+}| 1 | +We use a test profile to push alternative beans for InputsInitializer and CommandsInitializer,
+allowing to provide inputs and a suitable environment for output command execution. |
+
| 2 | +DefaultTestInputs is provided by:
+
+
+
+ |
+
You can find more test examples in the Quarkus GitHub Action integration-tests module.
A popular requirement for GitHub Apps is to react to comments to perform commands e.g. @bot do something.
While you can rely on the traditional listeners presented previously and implement the parsing of the comments by yourself,
+Quarkus GitHub App comes with an additional extension called quarkus-github-app-command-airline which makes it extremely easy to develop comment-based commands.
| + + | +
+
+
+This extension is based on the popular Airline library and you can use all the features of the library to develop your commands. + |
+
| + + | +
+
+
+You can mix traditional event listeners and comment-based commands in the same GitHub App. +They use the exact same infrastructure. + |
+
First things first, add the quarkus-github-app-command-airline dependency to your GitHub App pom.xml:
<dependency>
+ <groupId>io.quarkiverse.githubapp</groupId>
+ <artifactId>quarkus-github-app-command-airline</artifactId>
+ <version>2.3.2</version>
+</dependency>Let’s say we want to implement a command to re-run a CI workflow.
+The idea is to react to users submitting a comment containing @mybot retest in a pull request.
This is as simple as:
+@Cli(name = "@bot", commands = { RetestCommand.class }) (1)
+public class MyFirstCli {
+
+ @Command(name = "retest") (2)
+ static class RetestCommand implements Runnable { (3)
+
+ @Override
+ public void run() { (4)
+ // do something
+ }
+ }
+}| 1 | +First thing is to declare a @Cli class. The name of the @Cli is what will trigger the parsing of the command. |
+
| 2 | +We create a command called retest. |
+
| 3 | +All the commands of a same @Cli have to implement the same interface, in this case Runnable. |
+
| 4 | +Your interface must have a run(…) method. You can inject parameters as we will see later but it has to be called run. |
+
That is all that is necessary.
+Every time a comment containing @bot retest is posted in your project,
+the run() method above is called.
By default, the command is run whether the comment is added to issues or pull requests +(as far as comments are concerned a pull request is just another type of issue). +We will see a bit later how we can configure it.
+| + + | +
+
+
+Be careful about permissions when exposing commands, +typically, in this example, we probably don’t want all the users to be able to trigger a new CI run. +
+
+Make sure to implement the proper permission checks. + |
+
IssueComment payloadTo turn the command above into something actually useful, we miss a few things:
+We don’t have any context about the comment (which issue or pull request was it posted in?).
+We don’t have a GitHub client around.
This is a very common requirement and something you can’t do without, really.
+Luckily for us, we can get all this injected into the run() method of our commands.
Let’s take a first example:
+@Cli(name = "@bot", commands = { Command1.class, Command2.class })
+public class PayloadInjectionCli {
+
+ interface Commands { (1)
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException; (2)
+ }
+
+ @Command(name = "command1")
+ static class Command1 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException { (3)
+ issueCommentPayload.getIssue().comment("Ack");
+ }
+ }
+
+ @Command(name = "command2")
+ static class Command2 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ if (issueCommentPayload.getIssue().isPullRequest()) {
+ GHPullRequest pullRequest = issueCommentPayload.getRepository()
+ .getPullRequest(issueCommentPayload.getIssue().getNumber()); (4)
+
+ // do something with the pull request
+ }
+ }
+ }
+}| 1 | +As already mentioned, we have to define a common interface for all commands with a run(…) method. |
+
| 2 | +It is possible to inject the IssueComment payload, from which you can get the issue (or the comment).
+Keep in mind a pull request is also an issue. |
+
| 3 | +Unfortunately, most of GitHub API calls throw IOExceptions in case an error occurs. It is not pretty but just throw them from your methods, the framework will handle them for you. |
+
| 4 | +This is how you can get to a GHPullRequest instance that represents a pull request from the pull request associated issue. |
+
| + + | +
+
+
+From the |
+
GitHub clientYou can inject a GitHub client as a parameter.
+It is authenticated with your GitHub App installation’s token.
This is especially useful if you want to execute REST API calls that are outside of the bounds of your current GHRepository.
@Cli(name = "@bot", commands = { Command1.class, Command2.class })
+public class GitHubInjectionCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException; (1)
+ }
+
+ @Command(name = "command1")
+ static class Command1 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException {
+ // do something with the gitHub client
+ }
+ }
+
+ @Command(name = "command2")
+ static class Command2 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException {
+ // do something with the gitHub client
+ }
+ }
+}| 1 | +You can inject a GitHub instance in your run() method. |
+
In a similar way, you can inject a DynamicGraphQLClient as a parameter if you want to execute GraphQL queries.
+It is authenticated with your GitHub App installation’s token.
You can inject CDI beans as parameters but it is not a recommended practice as it makes your common command interface more cluttered. +See CDI injection for more details.
+You can inject any CDI bean in your commands, either via parameters of the run() method or via field injection.
It is recommended to use field injection to avoid cluttering the run() method:
@Cli(name = "@bot", commands = { Command1.class })
+public class CdiInjectionCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException;
+ }
+
+ @Command(name = "command1")
+ static class Command1 implements Commands {
+
+ @Inject
+ CdiBean cdiBean; (1)
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ cdiBean.doSomething();
+ }
+ }
+}| 1 | +You can inject the @ApplicationScoped CdiBean via the CDI jakarta.inject.Inject annotation. |
+
@Command optionsWith the @CommandOptions annotation, you can fine tune the behavior of a @Command.
By default, commands are executed for both issues and pull requests. +Some commands might only make sense for issues or pull requests.
+Luckily, you can limit the scope of a command using @CommandOptions(scope = …):
@Command(name = "only-for-issues")
+ @CommandOptions(scope = CommandScope.ISSUES) (1)
+ static class CommandOnlyForIssues implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }| 1 | +This command will only be executed in the context of an issue. | +
@Command(name = "only-for-pull-requests")
+ @CommandOptions(scope = CommandScope.PULL_REQUESTS) (1)
+ static class CommandOnlyForPullRequests implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }| 1 | +This command will only be executed in the context of a pull request. | +
By default, when an execution error occurs, a MINUS_ONE reaction is added to the comment but that’s it.
+You might want to customize this behavior and have your GitHub App post a comment:
@Command(name = "execution-error-strategy")
+ @CommandOptions(executionErrorStrategy = ExecutionErrorStrategy.COMMENT_MESSAGE) (1)
+ static class CommandWithCustomExecutionErrorStrategy implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }| 1 | +When an error occurs executing the command, a comment containing > `%s`\n\n:rotating_light: An error occurred while executing the command. will be posted. |
+
If you want to go further, you can customize this message:
+ @Command(name = "execution-error-message")
+ @CommandOptions(executionErrorStrategy = ExecutionErrorStrategy.COMMENT_MESSAGE, executionErrorMessage = "Your custom error message") (1)
+ static class CommandWithCustomExecutionErrorMessage implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }| 1 | +When an error occurs executing the command, a comment containing Your custom error message will be posted. |
+
| + + | +
+
+
+Use |
+
By default, the Command Airline extension provides feedback about command execution with reactions.
+It is possible to configure this behavior. +For instance to disable them entirely:
+ @Command(name = "reaction-strategy")
+ @CommandOptions(reactionStrategy = ReactionStrategy.NONE)
+ static class CommandWithCustomReactionStrategy implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }@Cli optionsYou can fine tune the behavior of your @Cli via the @CliOptions annotation.
The name attribute of the @Cli annotation defines how your commands will be invoked.
+For instance, @Cli(name = "@bot") means that your commands will be executed if a user starts their comments with @bot.
You might want to define several aliases for this invocation (e.g. @bot, @quarkus-bot, @quarkusbot),
+which you can do as follows:
@Cli(name = "@quarkus-bot", commands = { AliasesCliCommand.class })
+@CliOptions(aliases = { "@quarkusbot", "@bot" }) (1)
+public class CliOptionsAliasesCli {| 1 | +Commands will be executed for comments starting with @quarkus-bot, @bot or @quarkusbot. |
+
As seen above, you can fine tune command options with the @CommandOptions annotation.
If you need to define common command options, you can do it at the @Cli level:
@Cli(name = "@bot", commands = { DefaultCommandOptionsCliCommand.class })
+@CliOptions(defaultCommandOptions = @CommandOptions(scope = CommandScope.ISSUES)) (1)
+public class CliOptionsDefaultCommandOptionsCli {| 1 | +Commands will be executed for comments starting with @quarkus-bot, @bot or @quarkusbot. |
+
| + + | +
+
+
+You can override the default command options by adding a |
+
By default, when an error occurs parsing the command, a comment is posted containing:
+> `%s`\n\n:rotating_light: Unable to parse the command. (%s being the parsed command)
the errors
+the help generated by Airline for this given @Cli, when relevant
This behavior can be customized:
+@Cli(name = "@bot", commands = { ParseErrorStrategyCliCommand.class })
+@CliOptions(parseErrorStrategy = ParseErrorStrategy.NONE) (1)
+public class CliOptionsParseErrorStrategyCli {| 1 | +In this case, no comment will be added when a parse error occurs.
+A CONFUSED reaction will be added to the comment though. |
+
The following strategies are available:
+NONE - Nothing is done.
COMMENT_MESSAGE - A comment containing the parse error message is posted.
COMMENT_MESSAGE_HELP - A comment containing the parse error message and the generated help is posted.
COMMENT_MESSAGE_ERRORS - A comment containing the parse error message and the parse errors is posted.
COMMENT_MESSAGE_HELP_ERRORS - A comment containing the parse error message, the generated help and the parse errors is posted.
You can also customize the error message:
+@Cli(name = "@bot", commands = { ParseErrorMessageCliCommand.class })
+@CliOptions(parseErrorStrategy = ParseErrorStrategy.COMMENT_MESSAGE, parseErrorMessage = "Your custom message") (1)
+public class CliOptionsParseErrorMessageCli {| 1 | +A comment containing Your custom message is posted when a parse error occurs. |
+
| + + | +
+
+
+Use |
+
GitHub has 3 levels of permissions for a repository:
+Read
+Write
+Admin
+The Read permission is not very useful in our case as anyone able to add a comment to an issue or pull request has the Read permission. +But restricting some commands to users with the Write or Admin permission is a common requirement.
+Note that when requiring a permission, you require that the user has at least the given permission. +So, if you require the Write permission, users with the Admin permission are also authorized to execute the command.
+Requiring a permission for a command is as easy as adding a @Permission annotation to your command:
@Cli(name = "@bot", commands = { WriteCommand.class })
+public class PermissionCli {
+
+ interface Commands {
+
+ void run() throws IOException;
+ }
+
+ @Command(name = "write-command")
+ @Permission(GHPermissionType.WRITE) (1)
+ static class WriteCommand implements Commands {
+
+ @Override
+ public void run() throws IOException {
+ // do something
+ }
+ }
+}| 1 | +To execute the write-command, the Write permission is required. |
+
Note that you can also define a permission at the @Cli level.
+In this case, the permission will be applied to all commands,
+except if you override it with a @Permission annotation at the command level.
@Cli(name = "@bot", commands = { WriteCommand.class, AdminCommand.class })
+@Permission(GHPermissionType.WRITE) (1)
+public class PermissionOverrideCli {
+
+ interface Commands {
+
+ void run() throws IOException;
+ }
+
+ @Command(name = "write-command") (2)
+ static class WriteCommand implements Commands {
+
+ @Override
+ public void run() throws IOException {
+ // do something
+ }
+ }
+
+ @Command(name = "admin-command")
+ @Permission(GHPermissionType.ADMIN) (3)
+ static class AdminCommand implements Commands {
+
+ @Override
+ public void run() throws IOException {
+ // do something
+ }
+ }
+}| 1 | +For all commands in this @Cli, the Write permission is required if not defined otherwise. |
+
| 2 | +The write-command doesn’t have any @Permission annotation so the default one is used:
+the Write permission is required. |
+
| 3 | +The admin-command overrides the default permission: the Admin permission is required. |
+
Team permissions behaves in exactly the same way as standard permissions,
+except for the usage of the @Team annotation.
You can define several teams in the @Team annotation.
+Permission is granted if the user is part of at least one team (logical OR).
Use the slug of the team to reference a team i.e. the team identifier in the team page URL.
@Cli(name = "@bot", commands = { MyTeamCommand.class })
+public class TeamPermissionCli {
+
+ interface Commands {
+
+ void run() throws IOException;
+ }
+
+ @Command(name = "command")
+ @Team({ "my-team1", "my-team2" }) (1)
+ static class MyTeamCommand implements Commands {
+
+ @Override
+ public void run() throws IOException {
+ // do something
+ }
+ }
+}| 1 | +The command will be executed only if the user is part of my-team1 or my-team2. |
+
| + + | +
+
+
+When using team permissions, the GitHub App requires the |
+
Feedback to commands is handled via reactions added to the comment.
+The following reactions can be added:
+ROCKET - command is executed, this reaction will be removed on command completion.
PLUS_ONE - command was executed successfully.
MINUS_ONE - the user doesn’t have the permission to execute the command or there was an error executing the command.
CONFUSED - there was an error parsing the command.
If you propose a lot of features, +it might be useful for the users to be able to get a description of the available commands and what they are doing.
+Luckily, Airline can generate a comprehensive help description from your commands. +Obviously, the help will be more comprehensive if you describe your commands with the appropriate annotation attributes.
+As we already mentioned, the Quarkus extension requires all your commands to implement the same command interface. +This is why we provide an abstract class that you can subclass to implement your help command.
+Providing a help command to the users would look like:
+@Cli(name = "@bot", commands = { Command1.class, Command2.class,
+ HelpCommand.class }, description = "Your helpful bot doing all sorts of things") (1)
+public class HelpCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException;
+ }
+
+ @Command(name = "command1", description = "Do command1 with style") (2)
+ static class Command1 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException {
+ // do something
+ }
+ }
+
+ @Command(name = "command2", description = "Do command2 with style")
+ static class Command2 implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException {
+ // do something
+ }
+ }
+
+ @Command(name = "help", description = "Print help")
+ static class HelpCommand extends AbstractHelpCommand implements Commands { (3)
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload, GitHub gitHub) throws IOException {
+ super.run(issueCommentPayload); (4)
+ }
+ }
+}| 1 | +Add a description to your @Cli annotation.
+Also add the help command to your commands. |
+
| 2 | +Add descriptions to your commands so that they are included in the help. | +
| 3 | +Have your help command extend AbstractHelpCommand.
+AbstractHelpCommand adds a comment with the help when someone execute the commands. |
+
| 4 | +Call the run() method of AbstractHelpCommand.
+AbstractHelpCommand requires a GHEventPayload.IssueComment payload to be injected. |
+
In this section, you will find a couple of common Airline examples.
+For more information about what you can do with Airline, please refer to the Airline documentation.
+You can have Airline injecting command arguments to your command:
+@Cli(name = "@bot", commands = { CommandWithArguments.class })
+public class ArgumentsCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException;
+ }
+
+ @Command(name = "add-users")
+ static class CommandWithArguments implements Commands {
+
+ @Arguments(description = "List of GitHub usernames") (1)
+ List<String> usernames;
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ issueCommentPayload.getIssue().comment("Hello " + String.join(", ", usernames)); (2)
+ }
+ }
+}| 1 | +Use the @Arguments annotation to inject the arguments. |
+
| 2 | +You can then consume them in your run() method. |
+
Airline support command groups.
+A popular example is how the git command line is architectured e.g. git remote ….
@Cli(name = "@bot", groups = { @Group(name = "remote", commands = { ListCommand.class, ShowCommand.class }) }) (1)
+public class GroupCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException;
+ }
+
+ @Command(name = "list") (2)
+ static class ListCommand implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }
+
+ @Command(name = "show") (3)
+ static class ShowCommand implements Commands {
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // do something
+ }
+ }
+}| 1 | +Define groups in the @Cli annotation.
+Each group has a name and is composed of a list of commands. |
+
| 2 | +To execute this command, add a comment with @bot remote list. |
+
| 3 | +To execute this command, add a comment with @bot remote show. |
+
You can inject Airline metadata instances (e.g. GlobalMetadata, CommandMetadata) into the commands:
@Cli(name = "@bot", commands = { Command1.class })
+public class InjectMetadataCli {
+
+ interface Commands {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException;
+ }
+
+ @Command(name = "command1")
+ static class Command1 implements Commands {
+
+ @AirlineInject (1)
+ GlobalMetadata<InjectMetadataCli> globalMetadata;
+
+ @AirlineInject (1)
+ CommandMetadata commandMetadata;
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ // ...
+ }
+ }
+}| 1 | +Use @AirlineInject to inject Airline metadata. |
+
You can use composition to create reusable Airline components:
+@Cli(name = "@composition", commands = { TestCompositionCommand.class })
+public class CompositionCli {
+
+ @Command(name = "test")
+ static class TestCompositionCommand implements DefaultCommand {
+
+ @AirlineModule (1)
+ VerboseModule verboseModule = new VerboseModule();
+
+ @Override
+ public void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException {
+ if (verboseModule.verbose) {
+ issueCommentPayload.getIssue().comment("hello from @composition test - verbose");
+ } else {
+ issueCommentPayload.getIssue().comment("hello from @composition test");
+ }
+ }
+ }
+
+ public static class VerboseModule {
+
+ @Option(name = { "-v", "--verbose" }, description = "Enables verbose mode")
+ protected boolean verbose = false;
+ }
+
+ public interface DefaultCommand {
+
+ void run(GHEventPayload.IssueComment issueCommentPayload) throws IOException;
+ }
+}| 1 | +Use @AirlineModule to inject the reusable options into the command. |
+
A Quarkus GitHub App is a standard Quarkus application.
+You can create one including the Quarkus GitHub App extension using the following Quarkus CLI command:
+| + + | +
+Make sure you use the 📋 button to copy the command.
+ |
+
quarkus create app \
+ -x quarkus-github-app \ (1)
+ org.acme:my-github-app \ (2)
+ --no-code (3)| 1 | +The Quarkus GitHub App extension. | +
| 2 | +The GA of your Maven project. | +
| 3 | +Do not include unrelated generated code in the project. | +
| + + | +
+
+
+On Windows and macOS, it is recommended to concatenate all the options on one line (without |
+
| + + | +
+
+
+We highly recommend the usage of the Quarkus CLI but if you cannot install it or prefer using Maven, +you can create a Quarkus GitHub Action project using the following Maven command: +
+
+
+
+
+
+
+
+
+
+
|
+
This command creates a regular Quarkus Maven project. +You can add additional Quarkus extensions or Java dependencies.
+Once the project is created, go to the my-github-app directory.
As the configuration is environment-specific and you probably don’t want to commit it in your repository,
+the best is to create a .env file.
The content of your .env file should be as follows:
QUARKUS_GITHUB_APP_APP_ID=<the numeric app id>
+QUARKUS_GITHUB_APP_APP_NAME=<the name of your app>
+QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL=<your Smee.io channel URL>
+QUARKUS_GITHUB_APP_WEBHOOK_SECRET=<your webhook secret>
+QUARKUS_GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\
+ <your private key> \
+-----END RSA PRIVATE KEY-----The numeric app id appearing in the App ID field.
The name of your app is the one appearing in the GitHub URL. +It is only used to improve usability in dev mode.
+The URL you obtained when you created your Smee.io channel.
+The webhook secret you created at the previous step.
+The content of the private key you generated and downloaded. +Open the key file with a text editor as key viewers usually only show fingerprints.
+| + + | +
+
+
+Don’t forget to add backslashes at the end of the lines of your private key (except the last one). +In a property file, that is how a multi-line value is considered one value. + |
+
Once you have created your .env, you are all set.
If you are familiar with Quarkus, you already know the dev mode which improves productivity a lot. +If you are not, the principle is that you start your application once and code: +Quarkus will take care of reloading the application when it receives a request.
+Just execute the following command to start Quarkus in dev mode:
+quarkus dev| + + | +
+
+
+If you have a configuration error, it’s probably because you did something wrong with the |
+
From now on, you are done with the setup and you can code your GitHub App. +Sky is the limit.
+For instance, you can create the following class:
+class CreateComment {
+
+ void onOpen(@Issue.Opened GHEventPayload.Issue issuePayload) throws IOException {
+ issuePayload.getIssue().comment("Hello from my GitHub App");
+ }
+}From now on, every time you create an issue in your GitHub project, a comment will be added by your GitHub App.
+In details:
+No need for the public modifier, your classes and methods can be package protected.
We listen to the @Issue.Opened event i.e. this method will be called for each issue opened.
A payload of type GHEventPayload.Issue will be injected in our method automatically.
+This class is provided by the Hub4j GitHub API.
You are done developing your first Quarkus GitHub App.
+Obviously the one we developed is not very useful, but it is a good start and using this framework:
+You can listen to all the events currently supported by the Hub4j GitHub API.
+You have the full power of Quarkus with live coding, easy configuration, dependency injection, native executables and more.
+You can write automated tests that simulate GitHub events and assert the behavior of your application.
+You have at your disposal the full ecosystem of Quarkus extensions and the broader Java ecosystem.
+Our Replay UI will come handy while developing your GitHub App.
+You can learn more about all the events you can listen to in our Developer Reference.
+When you are done developing your application, please refer to Push to Production.
+To listen to an event, you need to create a method with one of the event annotations:
+class CreateComment {
+
+ void onOpen(@Issue.Opened GHEventPayload.Issue issuePayload) throws IOException {
+ issuePayload.getIssue().comment("Hello from my GitHub App");
+ }
+}A few observations:
+The method may either be package-protected or public.
+Most of the GitHub API methods throw IOExceptions so your methods need to propagate it. We have some nice error handling.
The payload type needs to be consistent with the event type.
+A method may listen to several events as long as they share the same payload type:
+class IssueListener {
+
+ void onOpenOrEdit(@Issue.Opened @Issue.Edited GHEventPayload.Issue issuePayload) {
+ // do something
+ }
+}Several methods can listen to the same event types but you cannot control the order of their execution. +We use CDI events under the hood and the execution of event observer methods cannot be ordered. +If you need ordering for several steps, use a single method to control the execution of these steps. +They can be split in smaller private methods if need be.
+Here are all the events currently supported, together with the type of the payload that will be injected.
+| GitHub Event Type | +Events | +Payload | +
|---|---|---|
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
| + |
|
++ |
If you want to access the low level JSON payload, you can use the raw GitHubEvent, either by substituting it to the API payload:
class TriageIssue {
+
+ void triageIssue(@Issue.Opened GitHubEvent gitHubEvent) {
+ // do something
+ }
+}Or by adding it as an additional parameter:
+class TriageIssue {
+
+ void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, GitHubEvent gitHubEvent) {
+ // do something
+ }
+}The GitHubEvent exposes the raw JSON either as a string or as a Vert.x JsonObject,
+together with some additional information like the installation id, the event or the action.
If you miss an event type, it is also possible to listen to events by using the @RawEvent annotation.
+The @RawEvent annotation allows you to listen to all events/actions, and you may also specify the event and the action you want to listen to.
When using the @RawEvent annotation, the only allowed payload parameter type is GitHubEvent.
class ActOnDeploymentProtectionRule {
+
+ void onDeploymentProtectionRule(@RawEvent(event = "deployment_protection_rule", action = "requested") GitHubEvent gitHubEvent) {
+ // do something
+ }
+}Both event and action are optional and you can listen to all events by using the following code:
class CatchAll {
+
+ void catchAll(@RawEvent GitHubEvent gitHubEvent) {
+ // do something
+ }
+}| + + | +
+
+
+If you miss an event type, please report it by creating an issue. +We try to add to contribute to the Hub4j GitHub API all the event types that are useful. +
+
+When missing an event type, there are two options: +
+
+
|
+
For some usage, you might need to include a configuration file that is repository-specific and versioned.
+The Quarkus GitHub App extension supports the following features:
+Automatic injection of config files into your methods.
+YAML, JSON or text config files.
+Automatic deserialization of your YAML or JSON config files into Java POJOs using Jackson.
+Injecting a configuration file in your method is as simple as:
+class TriageIssue {
+
+ void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload,
+ @ConfigFile("quarkus-bot-java.yml") QuarkusBotConfigFile quarkusBotConfigFile) {
+ // do something
+ }
+}The configuration file .github/quarkus-bot-java.yml present in the default branch of the repository
+for which the event has been triggered
+is parsed and deserialized to a QuarkusBotConfigFile instance using Jackson.
If the file does not exist in the repository, quarkusBotConfigFile will be null.
If you want to get the content of the configuration file as is, use a String.
Note that @ConfigFile injection supports using Optional<YourConfigType>.
| + + | +
+
+
+If your repository is private, reading configuration files requires your GitHub App to have the |
+
| + + | +
+
+
+By default, the config file path is relative to the
+
+You can reference a file outside this directory by using an |
+
The Quarkus GitHub App extension provides an error handler that will log errors with as many details as possible.
+You can customize the error handler by creating a CDI bean implementing io.quarkiverse.githubapp.error.ErrorHandler:
| + + | +
+
+
+Some errors may be triggered before the payload has been parsed.
+In this case, the |
+
When you need to access the authenticated GitHub instance, for instance to call GitHub#getMyself(),
+simply inject it into your method:
class TriageIssue {
+
+ void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, GitHub gitHub) {
+ gitHub.getMyself();
+ }
+}The injected GitHub instance is authenticated as an installation.
For some purposes, using the GitHub GraphQL API might get handy (typically to access the Discussions API that is only available in the GraphQL API).
+In the same way you can inject an authenticated GitHub instance, you can inject an authenticated DynamicGraphQLClient as follows:
class TriageIssue {
+
+ void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, DynamicGraphQLClient gitHubGraphQLClient) {
+ // do something GraphQLy with gitHubGraphQLClient
+ }
+}The injected DynamicGraphQLClient instance is authenticated as an installation.
The Quarkus GitHub App extension exposes the following configuration properties:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The numeric application id provided by GitHub. +
+
+Optional for tests, but mandatory in production and dev mode. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The GitHub name of the application. +
+
+Optional, only used for improving the user experience. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Read the configuration files from the source repository in case of a fork. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The RSA private key. +
+
+Optional for tests, but mandatory in production and dev mode. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The webhook secret if defined in the GitHub UI. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Smee.io proxy URL used when testing locally. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The GitHub instance endpoint. +
+
+Defaults to the public github.com instance. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The REST API endpoint. +
+
+Defaults to the public github.com instance REST API endpoint. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The GraphQL API endpoint. +
+
+Defaults to the public github.com instance GraphQL endpoint. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A directory in which the payloads are saved. +
+
+Environment variable: |
+path |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The numeric application id provided by GitHub. +
+
+Optional for tests, but mandatory in production and dev mode. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The GitHub name of the application. +
+
+Optional, only used for improving the user experience. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Read the configuration files from the source repository in case of a fork. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The RSA private key. +
+
+Optional for tests, but mandatory in production and dev mode. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The webhook secret if defined in the GitHub UI. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Smee.io proxy URL used when testing locally. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The GitHub instance endpoint. +
+
+Defaults to the public github.com instance. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The REST API endpoint. +
+
+Defaults to the public github.com instance REST API endpoint. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The GraphQL API endpoint. +
+
+Defaults to the public github.com instance GraphQL endpoint. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A directory in which the payloads are saved. +
+
+Environment variable: |
+path |
++ |
When maintaining large projects on GitHub, GitHub Apps come handy: +they allow you to automate most of the repetitive tasks.
+The principle is simple: +for each event your application listens to, +GitHub will call your webhook URL with a payload +and from there, it is on you to handle the payload and do something with it.
+There are already a ton of existing GitHub Apps +and they can improve the overall throughput of your project +and avoid human errors.
+That being said, +your project might also have specific requirements or workflows +or you might be uncomfortable giving the keys of your repository +to an external entity.
+We have some good news for you: +developing GitHub Apps is easy.
+Until now, your best option was GitHub’s own Probot, +but if you prefer Java over JavaScript or TypeScript, +you have come to the right place: +Quarkus GitHub App is designed to make developing GitHub Apps in Java +easy and fun.
+And with all the Quarkus goodness: developer joy, live reload and native executables.
+Eager to start? First step is to register your GitHub App.
+There is a good chance you will continue to develop your GitHub App to add features and fix issues. +A good practice is to register a new GitHub App specific to production instead of reusing the one you created for development.
+To do so, please follow the instructions in Register a GitHub App again.
+You can build your application as a jar using the following command:
+
+quarkus buildThe application can be easily deployed to a Kubernetes or OpenShift cluster using the Kubernetes/OpenShift extensions.
+Or you can simply build a container using the Container image extensions.
+One of the great benefits of Quarkus is that you can easily build a native executable from your Java applications. +Native executables offer faster boot and lower memory footprint.
+GitHub Apps are good candidates for native executables (but deploying as a jar is also perfectly valid).
+Your GitHub App is no exception and you can build a native executable using GraalVM with:
+quarkus build --native| + + | +
+
+
+Building a native executable takes a while and is both CPU and memory intensive. + |
+
You can then start the native executable with:
+./target/my-github-app-1.0.0-SNAPSHOT-runner| + + | +
+
+
+For more information about building native executables, +see Building a native executable on the Quarkus website. +
+
+This particular guide also covers deploying native applications as containers. + |
+
There are some specific requirements for production:
+The webhook URL points to the root of your deployed GitHub App.
+Your GitHub App must be publicly available.
+You have to define a webhook secret.
+| + + | +
+
+
+Do not use the Smee.io service for your production GitHub App. +
+
+Use it only for testing purposes. + |
+
The first step when working on a new GitHub App is to register it on GitHub.
+That is one of our main differences with Probot: +we don’t perform the magic to register your application when initializing it.
+For now, we think it is better that you understand what you are doing +when registering your application, +especially since you will need to do it again when pushing your app to production.
+| + + | +
+
+
+We might revisit this decision at a later stage depending on your feedback. + |
+
Create a test repository that will serve as a playground for experimenting.
+We will install our GitHub App in this repository.
+To register a new application, go to GitHub Apps and click New GitHub App.
You can access this page by clicking on your profile picture at the top and then
+Settings > Developer Settings > GitHub Apps > New GitHub App.
Fill in the following information.
+When you are going to push your app to production, you will register a new GitHub App.
+So you might want to make it clear in the name that this app is for development/test.
+You can skip this section for now: it’s not useful for a minimal app.
+There is a good chance your development box is not directly accessible from the Internet.
+To solve this issue, GitHub provides the Smee.io service which uses Server Side Events to distribute the events to your locally running app.
+Go to https://smee.io/ and click on Start a new channel.
The URL in the Webhook Proxy URL field at the top will be your webhook URL.
+Keep it around, we will need it later.
| + + | +
+
+
+For now, you don’t need to set up a webhook secret: +secret signature checking is disabled when using Smee.io as it modifies the original payload. + |
+
| + + | +
+
+
+No need to start a Smee.io client: +Quarkus GitHub App connects to Smee.io automatically when a webhook proxy url is defined in your configuration. + |
+
When running in dev mode, we don’t enforce signature checking +(one big reason for this is that Smee.io doesn’t pass the payloads as is).
+However it is good practice to define a webhook secret as it is enforced in production mode.
+To generate a webhook secret, you can use the method recommended by GitHub:
+ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'You can also use pwgen:
pwgen -N 1 -s 40This webhook secret will be required later so keep it around.
+Depending on what your application will do, you will need to set up the appropriate permissions.
+Just start with enabling the Issues and Pull requests Read & write Repository permissions.
+That is a good starting point to experiment.
| + + | +
+
+
+You can add more permissions later but each installation of your GitHub App will need to validate the added permissions. +
+
+That is not really a problem when developing your app so don’t overthink it. + |
+
| + + | +
+
+
+The GitHub documentation contains a good reference of the permissions required by each REST API call. + |
+
Now that you have registered your first GitHub App, there is one more thing you need to do: +generate a private key.
+Scroll down, and in the Private keys section, click on Generate a private key.
You will be asked to download the key, keep it around, we will need it later.
+Install the GitHub App in your playground project.
+This can be done from the Install App tab of the application’s page (https://github.com/settings/apps then Edit and Install App).
OK, there is a lot more you can do in there and we will discuss more things in details later, +but for now, you are done: you have registered your first GitHub App +and you can start experimenting with it.
+When developing GitHub Apps, more often than not, being able to replay an event is useful. +It can be cumbersome to trigger the events from the GitHub UI by creating issues, pull requests, commenting…
+GitHub offers a replay UI for this purpose in the Advanced tab of your application page.
+It is not very practical when developing though as you are not able to search and,
+sometimes, the details of the events are not available immediately.
Quarkus GitHub App offers an integrated Replay UI when developing in dev mode. +You can inspect the received payloads and replay events from there. +It is available at http://localhost:8080/replay/.
+
+The easiest way to start testing your GitHub application is probably +to create a playground project on GitHub and to run the application locally through Smee.io, +as explained in Register a GitHub App.
+This will let you play around on your playground repository, +manually triggering events (by opening issues, pull requests, etc.), +then check in the application logs that these events were consumed by the application.
+That’s enough to get started, but once you start using the application on real repositories, +you will want to make sure that changes to your code won’t break existing features. +Doing that manually on every change will get exhausting very quickly.
+To automate tests, you will of course rely on JUnit as with any Quarkus application, +but there is an additional challenge: the application needs a GitHub repository to work on, +and needs to be fed GitHub events to react to.
+Fortunately, the GitHub App extension provides tools to help you simulate events and mock a GitHub repository.
+testing dependencyAdd the following dependency to your deployment module:
<dependency>
+ <groupId>io.quarkiverse.githubapp</groupId>
+ <artifactId>quarkus-github-app-testing</artifactId>
+ <version>2.3.2</version>
+ <scope>test</scope>
+</dependency>When you tested your application manually, +GitHub sent events (HTTP requests) to your application. +Those events can be inspected using the replay UI at http://localhost:8080/replay/.
+In order to simulate events in automated tests, +you need to copy the payload of those events to resource files.
+Let’s continue with the example from Create a GitHub App:
+open an issue in your playground repository,
+go to the replay UI to copy the event payload,
+then put that payload in a file in your project: src/test/resources/issue-opened.json.
Add the following class to src/test/java, in a package of your choosing:
@QuarkusTest
+@GitHubAppTest
+class CreateCommentTest {
+ @Test
+ void testIssueOpened() throws IOException {
+ GitHubAppTesting.when() (1)
+ .payloadFromClasspath("/issue-opened.json") (2)
+ .event(GHEvent.ISSUES) (3)
+ .then().github(mocks -> { (4)
+ Mockito.verify(mocks.issue(750705278)) (5)
+ .comment("Hello from my GitHub App"); (6)
+ });
+ }
+}| 1 | +Use GitHubAppTesting.when() to start simulating an event. |
+
| 2 | +Define the payload of the simulated event by pointing to a file in the classpath. | +
| 3 | +Define the type of the simulated event. | +
| 4 | +Use .then().github(mocks → …) to perform assertions on GitHub objects involved in the event handling. |
+
| 5 | +The given mocks object gives access to mocks of GitHub objects, indexed by their identifier.
+See the payload of your event for the identifiers of relevant objects (issue, repository, …).
+You can use .issue(long), .pullRequest(long), or even .ghObject(Class<? extends GHObject>, long).
+See the GitHubMockContext interface for a detailed list of methods. |
+
| 6 | +Assertions are performed as usual with Mockito. | +
You can use most Mockito features on the GitHub object mocks; +that includes defining their behavior before the event is simulated:
+@QuarkusTest
+@GitHubAppTest
+class CreateCommentTest {
+ @Test
+ void testIssueOpened() throws IOException {
+ GitHubAppTesting.given() (1)
+ .github(mocks -> { (2)
+ Mockito.doThrow(new RuntimeException("Simulated exception")) (3)
+ .when(mocks.issue(750705278))
+ .comment(Mockito.any());
+ })
+ .when().payloadFromClasspath("/issue-opened.json")
+ .event(GHEvent.ISSUES)
+ .then().github(mocks -> { (4)
+ Mockito.verify(mocks.issue(750705278)) (5)
+ .createReaction(ReactionContent.CONFUSED);
+ });
+ }
+}| 1 | +Use given().github(…) to configure mocks. | +
| 2 | +The given mocks object gives access to mocks of GitHub objects, indexed by their identifier,
+just like in .then().github(…).
+This can be used to configure the behavior of objects referenced in the event payload,
+such as (here) the GHIssue. |
+
| 3 | +Here we’re configuring the mock to throw an exception when the application tries to comment on the issue. | +
| 4 | +We can still use .then().github(mocks → …) to perform assertions on GitHub objects involved in the event handling. |
+
| 5 | +Here we’re verifying that the application caught the runtime exception and added a confused reaction to the GitHub issue. |
+
You can also use the class GitHubAppMockito to simplify mocking for some common scenarios:
@QuarkusTest
+@GitHubAppTest
+class CreateCommentTest {
+ @Test
+ void testIssueEdited() throws IOException {
+ var queryCommentsBuilder = GitHubAppMockito.mockBuilder(GHIssueCommentQueryBuilder.class); (1)
+ GitHubAppTesting.given()
+ .github(mocks -> {
+ Mockito.when(mocks.issue(750705278).queryComments())
+ .thenReturn(queryCommentsBuilder);
+ var previousCommentFromBotMock = mocks.ghObject(GHIssueComment.class, 2);
+ var commentsMock = GitHubAppMockito.mockPagedIterable(previousCommentFromBotMock); (2)
+ Mockito.when(queryCommentsBuilder.list()) (3)
+ .thenReturn(commentsMock);
+ })
+ .when().payloadFromClasspath("/issue-edited.json")
+ .event(GHEvent.ISSUES)
+ .then().github(mocks -> {
+ Mockito.verify(mocks.issue(750705278)).queryComments();
+ // The bot already commented , it should not comment again.
+ Mockito.verifyNoMoreInteractions(mocks.issue(750705278));
+ });
+ }
+}| 1 | +Use GitHubAppMockito.mockBuilder to easily mock builders from the GitHub API.
+It will mock the builder by setting its default answer to just return this;,
+which is convenient since most methods in builders do that.
+
+ Here we’re mocking the builder returned by |
+
| 2 | +Use GitHubAppMockito.mockPagedIterable to easily mock PagedIterable from the GitHub API,
+which is the return type from many query or listing methods.
+
+ Here we’re mocking the list of comments returned when querying issue comments, +so that it includes exactly one (mocked) comment. + |
+
| 3 | +When mocking builders, don’t forget to define the behavior of the "build method" (list()/create()/…),
+because the default answer set by GitHubAppMockito.mockBuilder (returning this)
+will not work for that method. |
+
If your event handler uses @ConfigFile to extract a configuration file from the GitHub repository,
+this file can be defined explicitly as a string:
@QuarkusTest
+@GitHubAppTest
+class CreateCommentTest {
+ @Test
+ void testIssueOpened() throws IOException {
+ GitHubAppTesting.given() (1)
+ .github(mocks -> { (2)
+ mocks.configFile("my-bot.yml") (3)
+ .fromString("greeting.message: \"some custom message\"");
+ })
+ .when()
+ .payloadFromClasspath("/issue-opened.json")
+ .event(GHEvent.ISSUES)
+ .then().github(mocks -> {
+ Mockito.verify(mocks.issue(750705278))
+ .comment("some custom message");
+ });
+ }
+}| 1 | +Use given().github(…) to configure mocks. | +
| 2 | +The given mocks object gives access to mocks of GitHub objects… including the configuration file. |
+
| 3 | +Here we’re setting the content of the configuration file to a given string.
+This string will be parsed and mapped to an object, then passed to the event handler
+as the @ConfigFile-annotated argument. |
+
Alternatively, the file can be extracted from a resource in the classpath:
+@QuarkusTest
+@GitHubAppTest
+class CreateCommentTest {
+ @Test
+ void testIssueOpened() throws IOException {
+ GitHubAppTesting.given() (1)
+ .github(mocks -> { (2)
+ mocks.configFile("my-bot.yml") (3)
+ .fromClasspath("/my-bot-some-custom-message.yml");
+ })
+ .when()
+ .payloadFromClasspath("/issue-opened.json")
+ .event(GHEvent.ISSUES)
+ .then().github(mocks -> {
+ Mockito.verify(mocks.issue(750705278))
+ .comment("some custom message");
+ });
+ }
+}| 1 | +Use given().github(…) to configure mocks. | +
| 2 | +The given mocks object gives access to mocks of GitHub objects… including the configuration file. |
+
| 3 | +Here we’re setting the content of the configuration file to a file extracted from the classpath (test resources).
+This file will be parsed and mapped to an object, then passed to the event handler
+as the @ConfigFile-annotated argument. |
+
This extension allows to inject a com.google.cloud.bigquery.BigQuery object or a com.google.cloud.bigquery.storage.v1.BigQueryWriteClient object inside your Quarkus application.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:${quarkusVersion}:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=bigquery-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-bigquery"
+cd bigquery-quickstartThis command generates a Maven project, importing the Google Cloud BigQuery extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-bigquery extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-bigquery"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-bigquery</artifactId>
+</dependency>This is an example usage of the extension: we create a REST resource with a single endpoint that queries the Stackoverflow +public dataset for questions tagged with 'google-bigquery' and returns the results.
+import java.util.UUID;
+import java.util.stream.Collectors;
+import java.util.stream.StreamSupport;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import com.google.cloud.bigquery.BigQuery;
+import com.google.cloud.bigquery.Job;
+import com.google.cloud.bigquery.JobId;
+import com.google.cloud.bigquery.JobInfo;
+import com.google.cloud.bigquery.QueryJobConfiguration;
+import com.google.cloud.bigquery.TableResult;
+
+@Path("/bigquery")
+public class BigQueryResource {
+ @Inject
+ BigQuery bigquery; // Inject BigQuery
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String bigquery() throws InterruptedException {
+ QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(// Define a new Job with the query
+ "SELECT "
+ + "CONCAT('https://stackoverflow.com/questions/', CAST(id as STRING)) as url, view_count "
+ + "FROM `bigquery-public-data.stackoverflow.posts_questions` "
+ + "WHERE tags like '%google-bigquery%' ORDER BY favorite_count DESC LIMIT 10")
+ .setUseLegacySql(false)
+ .build();
+
+ // Create a job ID so that we can safely retry.
+ JobId jobId = JobId.of(UUID.randomUUID().toString());
+ Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());
+
+ // Wait for the query to complete.
+ queryJob = queryJob.waitFor();
+
+ // Check for errors
+ if (queryJob == null) {
+ throw new RuntimeException("Job no longer exists");
+ } else if (queryJob.getStatus().getError() != null) {
+ throw new RuntimeException(queryJob.getStatus().getError().toString());
+ }
+
+ // Get the results and return them
+ TableResult result = queryJob.getQueryResults();
+ return StreamSupport.stream(result.iterateAll().spliterator(), false)
+ .map(row -> row.get("url").getStringValue() + " - " + row.get("view_count").getLongValue() + "\n")
+ .collect(Collectors.joining());
+ }
+}If you want to use the BigQuery Storage Write API you can inject a BigQueryWriteClient :
import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import com.google.cloud.bigquery.storage.v1.BigQueryWriteClient;
+
+@Path("/bigquery")
+public class BigQueryResource {
+ @Inject
+ BigQueryWriteClient bigQueryWriteClient;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String bigquery() {
+ // do whatever you want with the BigQueryWriteClient ...
+ }
+}This extension allows using Google Cloud Bigtable inside your Quarkus application.
+Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=pubsub-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-bigtable"
+cd pubsub-quickstartThis command generates a Maven project, importing the Google Cloud Bigtable extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-bigtable extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-bigtable"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-bigtable</artifactId>
+</dependency>To test Bigtable you first need to create a Bigtable instance named test-instane
You can create one with gcloud:
gcloud bigtable instances create test-instance \
+ --cluster=test-cluster \
+ --cluster-zone=europe-west1-b \
+ --display-name=TestBy default, Bigtable mandates the usage of the GOOGLE_APPLICATION_CREDENTIALS environment variable to define its credentials, so
+you need to set this one instead of relying on the quarkus.google.cloud.service-account-location property.
export GOOGLE_APPLICATION_CREDENTIALS=<your-service-account-file>Another solution, is to inject a CredentialsProvider provided by the extension, and to use the various BigTable*Settings classes
+to instantiate Bigtable components. This can be seen on the example that follows.
This is an example usage of the extension: we create a REST resource with a single endpoint that write a row inside the Bigtable test-column-family column family of the test-table table then retrieve it.
We also init the Bigtable table at @PostConstruct time if it didn’t exist.
import java.io.IOException;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import com.google.api.gax.core.CredentialsProvider;
+import com.google.cloud.bigtable.admin.v2.BigtableTableAdminClient;
+import com.google.cloud.bigtable.admin.v2.BigtableTableAdminSettings;
+import com.google.cloud.bigtable.admin.v2.models.CreateTableRequest;
+import com.google.cloud.bigtable.data.v2.BigtableDataClient;
+import com.google.cloud.bigtable.data.v2.BigtableDataSettings;
+import com.google.cloud.bigtable.data.v2.models.Row;
+import com.google.cloud.bigtable.data.v2.models.RowCell;
+import com.google.cloud.bigtable.data.v2.models.RowMutation;
+
+@Path("/bigtable")
+public class BigtableResource {
+ private static final String INSTANCE_ID = "test-instance";
+ private static final String TABLE_ID = "test-table";
+ private static final String COLUMN_FAMILY_ID = "test-column-family";
+
+ @ConfigProperty(name = "quarkus.google.cloud.project-id")
+ String projectId;
+
+ @Inject
+ CredentialsProvider credentialsProvider;
+
+ @PostConstruct
+ void initBigtable() throws IOException {
+ // init Bigtable settings using the injected CredentialsProvider
+ BigtableTableAdminSettings settings = BigtableTableAdminSettings.newBuilder()
+ .setCredentialsProvider(credentialsProvider)
+ .setProjectId(projectId)
+ .setInstanceId(INSTANCE_ID)
+ .build();
+ try (BigtableTableAdminClient adminClient = BigtableTableAdminClient.create(settings)) {
+ if (!adminClient.exists(TABLE_ID)) {
+ System.out.println("Creating table: " + TABLE_ID);
+ CreateTableRequest createTableRequest = CreateTableRequest.of(TABLE_ID).addFamily(COLUMN_FAMILY_ID);
+ adminClient.createTable(createTableRequest);
+ System.out.printf("Table %s created successfully%n", TABLE_ID);
+ }
+ }
+ }
+
+ @GET
+ public String bigtable() throws IOException {
+ // init Bigtable settings using the injected CredentialsProvider
+ BigtableTableAdminSettings settings = BigtableTableAdminSettings.newBuilder()
+ .setCredentialsProvider(credentialsProvider)
+ .setProjectId(projectId)
+ .setInstanceId(INSTANCE_ID)
+ .build();
+ try (BigtableDataClient dataClient = BigtableDataClient.create(settings)) {
+ // create a row
+ RowMutation rowMutation = RowMutation.create(tableId, "key1").setCell(columnFamily, "test", "value1");
+ dataClient.mutateRow(rowMutation);
+
+ Row row = dataClient.readRow(tableId, "key1");
+ System.out.println("Row: " + row.getKey().toStringUtf8());
+ StringBuilder cells = new StringBuilder();
+ for (RowCell cell : row.getCells()) {
+ cells.append(String.format(
+ "Family: %s Qualifier: %s Value: %s%n",
+ cell.getFamily(), cell.getQualifier().toStringUtf8(), cell.getValue().toStringUtf8()));
+ }
+ return cells.toString();
+ } finally {
+ dataClient.close();
+ }
+ }
+}This extension allows to inject both a com.google.firebase.FirebaseApp and a com.google.firebase.auth.FirebaseAuth object inside your Quarkus application.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:${quarkusVersion}:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=firebase-admin-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-firebase-admin"
+cd firebase-admin-quickstartThis command generates a Maven project, importing the Google Cloud Firebase Admin extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-firebase-admin extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-firebase-admin"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-firebase-admin</artifactId>
+</dependency>This is an example usage of the extension: we create a REST resource with a single endpoint that retrieves a user by UID.
+import com.google.firebase.auth.FirebaseAuth;
+import com.google.firebase.auth.FirebaseAuthException;
+import com.google.firebase.auth.UserRecord;
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+@Path("/auth")
+public class FirebaseAuthResourceTest {
+
+ @Inject
+ FirebaseAuth firebaseAuth;
+
+ @GET
+ @Path("/users/{uid}")
+ @Produces(MediaType.APPLICATION_JSON)
+ public UserRecord getUserById(@PathParam("uid") String uid) throws FirebaseAuthException {
+ return firebaseAuth.getUser(uid);
+ }
+
+}This extension also supports Firebase Authentication, allowing you to secure your endpoints using Firebase’s authentication mechanisms. +This section describes how to use Firebase Authentication in your Quarkus application.
+Remember that you need to enable the Firebase Authentication service in your Firebase project. quarkus.google.cloud.firebase-admin.auth.enable must be set to true in your application configuration.
quarkus.google.cloud.firebase-admin.auth.enabled - Enable Firebase Authentication.
+Default value is false.
If you want to access the user’s claims you can use SecurityIdentity:
+import io.quarkus.security.identity.SecurityIdentity;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import com.google.firebase.FirebaseApp;
+import com.google.firebase.FirebaseOptions;
+import org.eclipse.microprofile.jwt.JsonWebToken;
+
+@Path("/app")
+public class FirebaseAppResource {
+
+ @Inject
+ FirebaseApp firebaseApp;
+
+ @Inject
+ SecurityIdentity identity;
+
+ @GET
+ @Path("/options")
+ @Produces(MediaType.APPLICATION_JSON)
+ public FirebaseOptions getOptions() {
+ if(identity instanceof JsonWebToken) {
+ System.out.println("JWT: " + ((JsonWebToken) identity).getClaim("email"));
+ }
+
+ return firebaseApp.getOptions();
+ }
+
+}This extension allows to inject a com.google.cloud.firestore.Firestore object inside your Quarkus application.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project. +Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=firestore-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-firestore"
+cd firestore-quickstartThis command generates a Maven project, importing the Google Cloud Firestore extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-firestore extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-firestore"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-firestore</artifactId>
+</dependency>This is an example usage of the extension: we create a REST resource with a single endpoint that creates a 'persons' collection, inserts three persons in it, then search for persons with last name Doe and returns them.
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+import java.util.stream.Collectors;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import com.google.api.core.ApiFuture;
+import com.google.api.core.ApiFutures;
+import com.google.cloud.firestore.CollectionReference;
+import com.google.cloud.firestore.Firestore;
+import com.google.cloud.firestore.Query;
+import com.google.cloud.firestore.QuerySnapshot;
+import com.google.cloud.firestore.WriteResult;
+
+@Path("/firestore")
+public class FirestoreResource {
+ @Inject
+ Firestore firestore; // Inject Firestore
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String firestore() throws ExecutionException, InterruptedException {
+ // Insert 3 persons
+ CollectionReference persons = firestore.collection("persons");
+ List<ApiFuture<WriteResult>> futures = new ArrayList<>();
+ futures.add(persons.document("1").set(new Person(1L, "John", "Doe")));
+ futures.add(persons.document("2").set(new Person(2L, "Jane", "Doe")));
+ futures.add(persons.document("3").set(new Person(3L, "Charles", "Baudelaire")));
+ ApiFutures.allAsList(futures).get();
+
+ // Search for lastname=Doe
+ Query query = persons.whereEqualTo("lastname", "Doe");
+ ApiFuture<QuerySnapshot> querySnapshot = query.get();
+ return querySnapshot.get().getDocuments().stream()
+ .map(document -> document.getId() + " - " + document.getString("firstname") + " "
+ + document.getString("lastname") + "\n")
+ .collect(Collectors.joining());
+ }
+}| + + | +
+Here we let Firestore serialize the Person object, Firestore will use reflection for this.
+So if you deploy your application as a GraalVM native image you will need to register the Person class for reflection.
+This can be done by annotating it with @RegisterForReflection.
+ |
+
The extension provides a Dev Service that can be used to run a local Firestore emulator. +This is useful for testing purposes, so you don’t have to rely on a real Firestore instance. +By default, the Dev Service is disabled, but you can enable it by setting the
+quarkus.google.cloud.firestore.devservice.enabled property to true
You can also set the
+quarkus.google.cloud.firestore.devservice.port property to change the port on which the emulator will be started (by default there is no port set, so the emulator will use a random port)
The Google Cloud Services extension pack provides Quarkus extensions for the following services:
+They all share an optional common configuration property to set the project ID:
+quarkus.google.cloud.project-id=<your-project-id>If the project ID is not set, the extensions will default to using ServiceOptions.getDefaultProjectId()
+that will use the default project detected via Application Default Credentials.
All these extensions work with applications built as native image executables.
+These extensions work well within the various Google Cloud Functions extensions available inside Quarkus as they directly authenticate via the built-in credentials, see the deploying to google cloud platform guide.
+All Google Cloud services extensions are part of the Quarkus platform, if you’re using the platform BOM (io.quarkus.platform:quarkus-bom) there is no need to manage their version.
If you’re not using the platform BOM, you can use the Google Cloud services BOM to manage all versions:
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-services-bom</artifactId>
+ <version>${quarkus.google-cloud-services.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>There are several ways to authenticate to Google Cloud, +it depends on where your application runs (inside our outside Google Cloud Platform) and for which service.
+The current authentication flow is as follows:
+Check the quarkus.google.cloud.service-account-location property, if it exists, use the service account file from this location.
Check the quarkus.google.cloud.service-account-encoded-key property, if it exists, use the service account base64 encoded content.
Check the access token returned as part of OpenId Connect Authorization Code Grant response after a user has authenticated with
+Google OpenId Connect provider (see Quarkus OpenId Connect for Web Applications).
+This access token can be used to access Google Services on behalf of the currently authenticated user
+but will be ignored if the quarkus.google.cloud.access-token-enabled property is set to false.
Use GoogleCredentials.getApplicationDefault() that will search for credentials in multiple places:
Credentials file pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
Credentials provided by the Google Cloud SDK gcloud auth application-default login command.
Google Cloud managed environment (Google App Engine, Google Cloud Functions, GCE, …) built-in credentials.
+Google PubSub and Google Bigtable should be authenticated using the GOOGLE_APPLICATION_CREDENTIALS environment variable,
+or use the provided CredentialsProvider when instantiating their objects.
If you plan to use one of the Google Cloud services emulators (for running on localhost, or for testing purpose), on a non-authenticated environment,
+you’ll need to mock the Google Cloud authentication credentials, and optionally the CredentialsProvider if you’re using it (otherwise it will be removed by Quarkus CDI engine).
For testing, this can be done by creating a CDI producer that will produce a mocked bean (with Quarkus mock support and Mockito)
+to replace the Credentials and the CredentialsProvider beans.
import javax.enterprise.context.ApplicationScoped;
+import javax.enterprise.inject.Default;
+import javax.enterprise.inject.Produces;
+import javax.inject.Singleton;
+
+import com.google.api.gax.core.CredentialsProvider;
+import com.google.api.gax.core.NoCredentialsProvider;
+import com.google.auth.Credentials;
+import com.google.cloud.NoCredentials;
+
+import io.quarkus.test.Mock;
+
+@Mock
+@ApplicationScoped
+public class GoogleCredentialsMockProducer {
+
+ @Produces
+ @Singleton
+ @Default
+ public Credentials googleCredential() {
+ return NoCredentials.getInstance();
+ }
+
+ // only needed if you're injecting it inside one of your CDI beans
+ @Produces
+ @Singleton
+ @Default
+ public CredentialsProvider credentialsProvider() {
+ return NoCredentialsProvider.create();
+ }
+}Example applications can be found inside the integration-test folder of the GitHub repository:
+main: RESTEasy endpoints using all the Google Cloud Services extensions, to be deployed as a standalone JAR.
+google-cloud-functions: A Google Cloud HTTP function using Google Cloud Storage.
+app-engine: A RESTEasy endpoint using Google Cloud Storage, to be deployed inside Google App Engine.
+firebase-admin: RESTEasy endpoints using Firebase Admin SDK features, such as user management.
+This extension allows you to integrate your logs directly into Google Cloud Logging, including the ability to set +resource labels and log record labels, include trace ID and to use structured logging.
+You can integrate your logs into Cloud Logging via a standard logger of the com.google.cloud.logging.Logging object that you can inject in your code.
First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=firestore-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-logging"
+cd firestore-quickstartThis command generates a Maven project, importing the Google Cloud Logging extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-logging extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-logging"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-logging</artifactId>
+</dependency>When configured, all that is needed is to log data as you wish. You can use JUL, jboss-logging or Slf4j, or even Google Cloud Logging directly.
+You can also inject the logger to use, for example:
package mypackage;
+
+import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import org.jboss.logging.Logger;
+
+@Path("/logging")
+public class LoggingResource {
+
+ @Inject
+ Logger logger;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String tryLog() {
+ logger.info("Greeting the World");
+ return "Hello World!";
+ }
+}Currently, the logging system uses a single Google Cloud Operations log and this is a mandatory configuration parameter.
+quarkus.google.cloud.logging.default-log
quarkus.google.cloud.project-id
If you want to disable the logging to Google Cloud you can do so:
+quarkus.google.cloud.logging.enabled=false
This is useful for testing not to write to Google Operations during development:
+%test.quarkus.google.cloud.logging.enabled=false
This logging system can either use a standard text based format, Elastic Common Schema, or a completely custom schema.
+quarkus.google.cloud.logging.format=[TEXT|JSON]
By setting the logging format to JSON this library will use the ECS format. As local record parameters and MDC values are not
+official part of the ECS specification, these default to parameters and mdc respectively, but this can be configured (see below).
quarkus.google.cloud.logging.structured.stack-trace.included=[true|false] - Should stack traces be included? Default to true
quarkus.google.cloud.logging.structured.parameters.included=[true|false] - Should log record parameters be included? Defaults to true
quarkus.google.cloud.logging.structured.parameters.field-name - This is the field name to use in ESC for parameters, defaults to parameters
quarkus.google.cloud.logging.structured.mdc.included=[true|false] - Should the MDC values be included? Defaults to true
quarkus.google.cloud.logging.structured.mdc.field-name - This is the field name to use in ESC for MDC values, defaults to mdc
You can configure the resource type and the resource labels. This is used by Google Cloud Operations as dimensions +when analysing logs. Please refer to the [Google Cloud documentation](https://cloud.google.com/logging/docs/api/v2/resource-list#resource-types) +for the allowable resource types and their associated labels.
+quarkus.google.cloud.logging.resource.type - The type string, defaults to generic_node
quarkus.google.cloud.logging.resource.label.<string> - This is a string map with key/value pairs
You can configure default labels for each log record:
+quarkus.google.cloud.logging.default-label.<string> - This is a string map with key/value pairs
In order to include trace and span ID in the log, you must bind a TraceInfoExtractor to the CDI context, e.g.:
package mypackage;
+
+import javax.enterprise.context.ApplicationScoped;
+
+import org.jboss.logmanager.ExtLogRecord;
+
+import io.quarkiverse.googlecloudservices.logging.runtime.TraceInfo;
+import io.quarkiverse.googlecloudservices.logging.runtime.TraceInfoExtractor;
+
+@ApplicationScoped
+public class TestTraceInfoExtractor implements TraceInfoExtractor {
+
+ @Override
+ public TraceInfo extract(ExtLogRecord record) {
+ return new TraceInfo(/* something, something */);
+ }
+}This will include the trace and span ID in the ESC log if they are not null. +By default, this will also be set on the Google Cloud Operations log entry as a link to Google Cloud Operations tracing, but this is configurable:
+quarkus.google.cloud.logging.gcp-tracing.enabled=[true|false]
You can inject a com.google.cloud.logging.Logging instance directly. If you do so, the configuration for the project to use, still apply.
import java.time.Instant;
+import java.util.List;
+
+import com.google.cloud.logging.Logging;
+import com.google.cloud.logging.LogEntry;
+import com.google.cloud.logging.Payload;
+import com.google.cloud.logging.Severity;
+
+@Inject
+Logging gcpLogging;
+
+
+public void log(String s) {
+ gcpLogging.write(List.of(LogEntry.newBuilder(Payload.StringPayload.of(s))
+ .setSeverity(Severity.DEBUG)
+ .setTimestamp(Instant.now())
+ .build()));
+}This extension allows using Google Cloud PubSub inside your Quarkus application.
+Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=pubsub-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-pubsub"
+cd pubsub-quickstartThis command generates a Maven project, importing the Google Cloud PubSub extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-pubsub extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-pubsub"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-pubsub</artifactId>
+</dependency>To test PubSub you first need to create a topic named test-topic
You can create one with gcloud:
gcloud pubsub topics create test-topicThis extension provides a QuarkusPubSub CDI bean that can help to interact with Google PubSub.
+QuarkusPubSub is automatically authenticated, so you don’t have to do anything else to use it.
If you don’t want to use QuarkusPubSub, be sure to configure the authentication.
+By default, PubSub mandates the usage of the GOOGLE_APPLICATION_CREDENTIALS environment variable to define its credentials, so
+you need to set it instead of relying on the quarkus.google.cloud.service-account-location property.
+Another solution, is to inject a CredentialsProvider provided by the extension, and to use it inside the various PubSub
+builders and settings objects when, instantiating PubSub components.
This is an example usage of the extension: we create a REST resource with a single endpoint that sends a message to the test-topic topic when hit.
We also register a consumer to the same topic at @PostConstruct time that logs all received messages on the topic so we can check that it works.
import java.io.IOException;
+import java.util.concurrent.TimeUnit;
+
+import javax.annotation.PostConstruct;
+import javax.annotation.PreDestroy;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import org.jboss.logging.Logger;
+
+import com.google.api.core.ApiFuture;
+import com.google.api.core.ApiFutureCallback;
+import com.google.api.core.ApiFutures;
+import com.google.cloud.pubsub.v1.MessageReceiver;
+import com.google.cloud.pubsub.v1.Publisher;
+import com.google.cloud.pubsub.v1.Subscriber;
+import com.google.common.util.concurrent.MoreExecutors;
+import com.google.protobuf.ByteString;
+import com.google.pubsub.v1.PubsubMessage;
+import com.google.pubsub.v1.Subscription;
+import com.google.pubsub.v1.Topic;
+
+import io.quarkiverse.googlecloudservices.pubsub.QuarkusPubSub;
+
+@Path("/pubsub")
+public class PubSubResource {
+ private static final Logger LOG = Logger.getLogger(PubSubResource.class);
+
+ @Inject
+ QuarkusPubSub pubSub;
+
+ private Subscriber subscriber;
+
+ @PostConstruct
+ void init() throws IOException {
+ // init topic and subscription
+ pubSub.createTopic("test-topic");
+ pubSub.createSubscription("test-topic", "test-subscription");
+
+ // Subscribe to PubSub
+ MessageReceiver receiver = (message, consumer) -> {
+ LOG.infov("Got message {0}", message.getData().toStringUtf8());
+ consumer.ack();
+ };
+ subscriber = pubSub.subscriber("test-subscription", receiver);
+ subscriber.startAsync().awaitRunning();
+ }
+
+ @PreDestroy
+ void destroy() {
+ // Stop the subscription at destroy time
+ if (subscriber != null) {
+ subscriber.stopAsync();
+ }
+ }
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public void pubsub() throws IOException, InterruptedException {
+ // Init a publisher to the topic
+ Publisher publisher = pubSub.publisher("test-topic");
+
+ try {
+ ByteString data = ByteString.copyFromUtf8("my-message");// Create a new message
+ PubsubMessage pubsubMessage = PubsubMessage.newBuilder().setData(data).build();
+ ApiFuture<String> messageIdFuture = publisher.publish(pubsubMessage);// Publish the message
+ ApiFutures.addCallback(messageIdFuture, new ApiFutureCallback<String>() {// Wait for message submission and log the result
+ public void onSuccess(String messageId) {
+ LOG.infov("published with message id {0}", messageId);
+ }
+
+ public void onFailure(Throwable t) {
+ LOG.warnv("failed to publish: {0}", t);
+ }
+ }, MoreExecutors.directExecutor());
+ } finally {
+ publisher.shutdown();
+ publisher.awaitTermination(1, TimeUnit.MINUTES);
+ }
+ }
+}The extension provides a Dev Service that can be used to run a local PubSub emulator. This is useful for testing purposes, so you don’t have to rely on a real PubSub instance. By default, the Dev Service is disabled, but you can enable it by setting the
+quarkus.google.cloud.pubsub.devservice.enabled property to true
You can also set the
+quarkus.google.cloud.pubsub.devservice.port property to change the port on which the emulator will be started (by default there is no port set, so the emulator will use a random port)
If we want to connect to the Dev Service, we need to specify TransportChannelProvider when creating subscriptions and publishers.
We can just reuse the code from the previous example and add the TransportChannelProvider to the Subscriber and Publisher. So what do we need to change?
As a first thing, we should declare a variable which we can then reuse and also inject the quarkus.google.cloud.pubsub.emulator-host property:
@ConfigProperty(name = "quarkus.google.cloud.pubsub.emulator-host")
+String emulatorHost;
+
+private TransportChannelProvider channelProvider;Then, we can create a TransportChannelProvider that provides connection to devservice within the init method:
// Create a ChannelProvider that connects to the Dev Service
+ManagedChannel channel = ManagedChannelBuilder.forTarget(emulatorHost).usePlaintext().build();
+channelProvider = FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel));Also in the same method when creating the Subscriber we set the TransportChannelProvider:
// Create a subscriber and set the ChannelProvider
+subscriber = Subscriber.newBuilder(subscriptionName, receiver).setChannelProvider(channelProvider).build();
+subscriber.startAsync().awaitRunning();The same is done when creating the Publisher in the pubsub method:
// Init a publisher to the topic
+Publisher publisher = Publisher.newBuilder(topicName)
+.setCredentialsProvider(credentialsProvider)
+// Set the ChannelProvider
+.setChannelProvider(channelProvider)
+.build();And finally we also set the TransportChannelProvider when creating the SubscriptionAdminClient in the initSubscription method:
SubscriptionAdminSettings subscriptionAdminSettings = SubscriptionAdminSettings.newBuilder()
+.setCredentialsProvider(credentialsProvider)
+// Set the ChannelProvider
+.setTransportChannelProvider(channelProvider)
+.build();This extension allows to use the Google Cloud Platform Secret Manager client library inside your Quarkus application.The current implementation is focused on accessing the secrets, but extending the implementation into also allowing to create or edit a secret might be a natural next step.
+It also allows to use secrets from the secret manager directly inside your application.properties.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project.Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:${quarkusVersion}:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=secretmanager-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-secret-manager"
+cd secretmanager-quickstartThis command generates a Maven project, importing the Google Cloud Secret Manager extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-secret-manager extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-secret-manager"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-secret-manager</artifactId>
+</dependency>This is an example fetching a single secret from GCP Secret Manager.
+First, you’ll have to create the secret in the GCP Secret Manager, as described in Google’s documentation at https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets.
+The following gcloud commands will create a secret named test-secret with the value s3cr3t in it.
gcloud secrets create test-secret --replication-policy="automatic"
+printf "s3cr3t" | gcloud secrets versions add integration-test --data-file=-The secretName parameter in the examples below refer to the name you give your secret, whereas the injected secretManagerProjectId refers to the name of your project on GCP.
+import com.google.cloud.secretmanager.v1.AccessSecretVersionResponse;
+import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
+import com.google.cloud.secretmanager.v1.SecretVersionName;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+@RequestScoped
+public class GCPSecretManager {
+
+ @Inject
+ SecretManagerServiceClient client;
+
+ @ConfigProperty(name = "quarkus.google.cloud.project-id")
+ String projectId;
+
+ public String getSecretFromSecretManager(String secretName) throws IOException {
+ SecretVersionName secretVersionName = SecretVersionName.of(projectId, secretName, "latest");
+ AccessSecretVersionResponse response = client.accessSecretVersion(secretVersionName);
+ return response.getPayload().getData().toStringUtf8();
+ }
+}You can also load and reference secrets from GCP Secret Manager in your application.properties file by using the following syntax:
# 1. Long form - specify the project ID, secret ID, and version
+${sm//projects/<project-id>/secrets/<secret-id>/versions/<version-id>}
+
+# 2. Long form - specify project ID, secret ID, and use latest version
+${sm//projects/<project-id>/secrets/<secret-id>}
+
+# 3. Short form - specify project ID, secret ID, and version
+${sm//<project-id>/<secret-id>/<version-id>}
+
+# 4. Short form - default project; specify secret + version
+#
+# The default project is inferred from the "quarkus.google.cloud.project-id" property
+# in your application.properties, or from application-default credentials if
+# this is not set.
+${sm//<secret-id>/<version>}
+
+# 5. Shortest form - specify secret ID, use default project and latest version.
+${sm//<secret-id>}You can use this syntax to load secrets directly from application.properties:
quarkus.database.password=${sm//my-secret-id/latest}Alternatively, you can also reference the secret value as a @ConfigProperty without specifying it from application.properties.
@ConfigProperty(name = "${sm//my-secret-id}")
+String secret;| + + | +
+When using secrets directly on your application.properties, the Google Cloud authentication is made early so
+access token based authentication cannot be used.
+ |
+
This extension allows to inject a com.google.cloud.spanner.Spanner object inside your Quarkus application.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project.Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=spanner-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-spanner"
+cd spanner-quickstartThis command generates a Maven project, importing the Google Cloud Spanner extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-spanner extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-spanner"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-spanner</artifactId>
+</dependency>To test Spanner you first need to have a running Spanner cluster named test-instance.
You can create one with gcloud:
gcloud spanner instances create test-instance --config=regional-us-central1 \
+ --description="Test Instance" --nodes=1Then you need a database named test-database.
You can create one with gcloud:
gcloud spanner databases create test-database --instance test-instanceAnd finally you need to create a table named Singers.
You can do it with gcloud:
gcloud spanner databases ddl update test-database --instance test-instance \
+ --ddl='CREATE TABLE Singers ( SingerId INT64 NOT NULL, FirstName STRING(1024), LastName STRING(1024), SingerInfo BYTES(MAX) ) PRIMARY KEY (SingerId)'This is an example usage of the extension: we create a REST resource with a single endpoint that inserts four singers inside the Singers table,
+then reads the all table and returns its elements.
import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.jboss.logging.Logger;
+
+import com.google.cloud.spanner.*;
+
+@Path("/spanner")
+public class SpannerResource {
+ private static final Logger LOG = Logger.getLogger(SpannerResource.class);
+
+ @Inject
+ Spanner spanner;// Inject Spanner
+
+ @ConfigProperty(name = "quarkus.google.cloud.project-id")
+ String projectId;// Inject the project name
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String spanner() {
+ // Create a database client
+ DatabaseId id = DatabaseId.of(projectId, "test-instance", "test-database");
+ DatabaseClient dbClient = spanner.getDatabaseClient(id);
+
+ // Insert 4 singer records
+ dbClient.readWriteTransaction().run(transaction -> {
+ String sql = "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
+ + "(12, 'Melissa', 'Garcia'), "
+ + "(13, 'Russell', 'Morales'), "
+ + "(14, 'Jacqueline', 'Long'), "
+ + "(15, 'Dylan', 'Shaw')";
+ long rowCount = transaction.executeUpdate(Statement.of(sql));
+ LOG.infov("{0} records inserted.", rowCount);
+ return null;
+ });
+
+ // Read them
+ try (ResultSet resultSet = dbClient.singleUse() // Execute a single read or query against Cloud Spanner.
+ .executeQuery(Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"))) {
+ StringBuilder builder = new StringBuilder();
+ while (resultSet.next()) {
+ builder.append(resultSet.getLong(0)).append(' ').append(resultSet.getString(1)).append(' ')
+ .append(resultSet.getString(2)).append('\n');
+ }
+ return builder.toString();
+ }
+ }
+
+}This extension allows to inject a com.google.cloud.storage.Storage object inside your Quarkus application.
Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.
+First, we need a new project.Create a new project with the following command (replace the version placeholder with the correct one):
+mvn io.quarkus:quarkus-maven-plugin:<quarkusVersion>:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=bigquery-quickstart \
+ -Dextensions="resteasy-reactive-jackson,quarkus-google-cloud-storage"
+cd storage-quickstartThis command generates a Maven project, importing the Google Cloud Storage extension.
+If you already have your Quarkus project configured, you can add the quarkus-google-cloud-storage extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-storage"This will add the following to your pom.xml:
+<dependency>
+ <groupId>io.quarkiverse.googlecloudservices</groupId>
+ <artifactId>quarkus-google-cloud-storage</artifactId>
+</dependency>To test Storage you first need to create a bucket named quarkus-hello then upload a file hello.txt in it.
+This file will be read by the test and returned from the endpoint.
You can use gsutil:
gsutil mb gs://quarkus-hello
+echo "Hello World!" > hello.txt
+gsutil cp hello.txt gs://my-bucketThis is an example usage of the extension: we create a REST resource with a single endpoint that gets the hello.txt object
+from the quarkus-hello bucket and returns its content.
import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import com.google.cloud.storage.Blob;
+import com.google.cloud.storage.Bucket;
+import com.google.cloud.storage.Storage;
+
+@Path("/storage")
+public class StorageResource {
+
+ @Inject
+ Storage storage;// Inject Storage
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String storage() {
+ Bucket bucket = storage.get("quarkus-hello");// Get the bucket
+ Blob blob = bucket.get("hello.txt"); // Get the object
+ return new String(blob.getContent()); // Return its content
+ }
+
+}Quarkus Groovy is a Quarkus extension allowing to write Quarkus applications in Groovy. This extension allows developers to take advantage of the characteristics of both technologies, combining the agility and expressiveness of the Groovy language with the efficiency and ease of development of Quarkus.
+If you want to use this extension, you need to add the io.quarkiverse.groovy:quarkus-groovy extension first to your build file.
Add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.groovy</groupId>
+ <artifactId>quarkus-groovy</artifactId>
+ <version>${quarkusGroovyVersion}</version> (1)
+</dependency>| 1 | +Version of the Quarkus Groovy extension set in the properties of the project | +
To compile the main and test sources written in Groovy, the required plugins which are the Groovy and Quarkus plugins need to be configured.
+The Maven plugin gmavenplus-plugin is used to compile all the Groovy sources of the project.
The required plugins are configured as next:
+<build>
+ <sourceDirectory>src/main/groovy</sourceDirectory> (1)
+ <testSourceDirectory>src/test/groovy</testSourceDirectory> (2)
+ <plugins>
+ <plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <version>${quarkus.version}</version> (3)
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.gmavenplus</groupId>
+ <artifactId>gmavenplus-plugin</artifactId>
+ <version>${groovy-maven-plugin.version}</version> (4)
+ <executions>
+ <execution>
+ <goals>
+ <goal>compile</goal> (5)
+ <goal>compileTests</goal> (6)
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>| 1 | +Indicates the location of the main sources written in Groovy | +
| 2 | +Indicates the location of the test sources written in Groovy | +
| 3 | +The version of the Quarkus plugin set in the properties of the project | +
| 4 | +The version of the GMavenPlus plugin set in the properties of the project | +
| 5 | +Indicates the GMavenPlus plugin that main sources have to be compiled | +
| 6 | +Indicates the GMavenPlus plugin that test sources have to be compiled | +
For some specific extensions such as hibernate-orm-panache and hibernate-reactive-panache, the source code needs to be compiled using with the flag -parameters indicating that the parameter names must be added to the class files.
+To be able to do that some additional parameters are needed as you can see below:
<plugins>
+ <plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <version>${quarkus.version}</version>
+ <configuration>
+ <compilerOptions> (1)
+ <compiler>
+ <name>groovy</name>
+ <args>
+ <arg>groovy.parameters=true</arg>
+ </args>
+ </compiler>
+ </compilerOptions>
+ </configuration>
+ <!-- Rest of the Quarkus plugin's configuration -->
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.gmavenplus</groupId>
+ <artifactId>gmavenplus-plugin</artifactId>
+ <version>${groovy-maven-plugin.version}</version>
+ <configuration>
+ <parameters>true</parameters> (2)
+ </configuration>
+ <!-- Rest of the GMavenPlus plugin's configuration -->
+ </plugin>
+</plugins>| 1 | +Specific Quarkus plugin configuration to indicate the Quarkus Groovy extension to compile the code in dev mode with the flag -parameters. |
+
| 2 | +Indicates the GMavenPlus plugin to compile the code with the flag -parameters. |
+
The Gradle plugin Groovy Plugin is used to compile all the Groovy sources of the project.
The required plugins are configured as next in the build.gradle file:
plugins {
+ id 'io.quarkus'
+ id 'groovy'
+}The version of the Quarkus plugin can be set in a pluginManagement block as next:
pluginManagement {
+ plugins {
+ id 'io.quarkus' version "${quarkusPluginVersion}" (1)
+ }
+}| 1 | +Version of the Quarkus plugin set in gradle.properties |
+
For some specific extensions such as hibernate-orm-panache and hibernate-reactive-panache, the source code needs to be compiled using with the flag -parameters indicating that the parameter names must be added to the class files.
+To be able to do that some additional parameters are needed as you can see below:
quarkusDev {
+ compilerOptions { (2)
+ compiler("groovy").args(["groovy.parameters=true"])
+ }
+}
+
+tasks.withType(GroovyCompile).configureEach {
+ groovyOptions.parameters = true (1)
+}| 1 | +Specific Quarkus plugin configuration to indicate the Quarkus Groovy extension to compile the code in dev mode with the flag -parameters. |
+
| 2 | +Indicates the Groovy Plugin to compile the code with the flag -parameters. |
+
| Name | +Description | +
|---|---|
|
+The warning level |
+
|
+Indicates whether parameter metadata generation must be enabled |
+
|
+Whether the bytecode version has preview features enabled |
+
|
+Classpath for use during compilation |
+
|
+Whether verbose operation has been requested |
+
|
+Whether debugging operation has been requested |
+
|
+The requested error tolerance |
+
|
+Extension used to find a groovy file |
+
|
+The name of the base class for scripts. It must be a subclass of Script. |
+
|
+Whether the recompilation is enabled |
+
|
+The minimum of time after a script can be recompiled |
+
|
+The list of disabled global AST transformation class names |
+
Hibernate ORM is the de facto Jakarta Persistence (formerly known as JPA) implementation and offers you the full breadth of an Object Relational Mapper. It makes complex mappings possible, but it does not make simple and common mappings trivial. Hibernate ORM with Panache focuses on making your entities trivial and fun to write in Quarkus.
+If you want to use this extension, you need to add the io.quarkiverse.groovy:quarkus-groovy-hibernate-orm-panache extension first to your build file.
| + + | +
+The extensions io.quarkiverse.groovy:quarkus-groovy and io.quarkus:quarkus-hibernate-orm are part of the dependencies of this extension.
+ |
+
Add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.groovy</groupId>
+ <artifactId>quarkus-groovy-hibernate-orm-panache</artifactId>
+ <version>${quarkusGroovyVersion}</version> (1)
+</dependency>| 1 | +Version of the Quarkus Groovy extension set in the properties of the project | +
The extension is mostly the same as the original extension from the Quarkus project the main differences are:
+The package where the base classes of the entities and repositories are located.
+Indeed, instead of being io.quarkus.hibernate.orm.panache, it is io.quarkiverse.groovy.hibernate.orm.panache.
All static methods in PanacheEntityBase (such as find, findAll, list, listAll, count…) that depend on bytecode injection have been removed due to a side effect of the static compilation that by-pass the generated methods. As workaround, the methods in the corresponding repository must be used.
The methods delete to delete entities by query has been renamed to deleteByQuery to prevent method call clashing with delete(Entity) in dynamic compilation mode.
Hibernate Reactive is the only reactive Jakarta Persistence (formerly known as JPA) implementation and offers you the full breadth of an Object Relational Mapper allowing you to access your database over reactive drivers. It makes complex mappings possible, but it does not make simple and common mappings trivial. Hibernate Reactive with Panache focuses on making your entities trivial and fun to write in Quarkus.
+If you want to use this extension, you need to add the io.quarkiverse.groovy:quarkus-groovy-hibernate-reactive-panache extension first to your build file.
| + + | +
+The extensions io.quarkiverse.groovy:quarkus-groovy and io.quarkus:quarkus-hibernate-reactive are part of the dependencies of this extension.
+ |
+
Add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.groovy</groupId>
+ <artifactId>quarkus-groovy-hibernate-reactive-panache</artifactId>
+ <version>${quarkusGroovyVersion}</version> (1)
+</dependency>| 1 | +Version of the Quarkus Groovy extension set in the properties of the project | +
The extension is mostly the same as the original extension from the Quarkus project the main differences are:
+The package where the base classes of the entities and repositories are located.
+Indeed, instead of being io.quarkus.hibernate.reactive.panache, it is io.quarkiverse.groovy.hibernate.reactive.panache.
All static methods in PanacheEntityBase (such as find, findAll, list, listAll, count…) that depend on bytecode injection have been removed due to a side effect of the static compilation that by-pass the generated methods. As workaround, the methods in the corresponding repository must be used.
The methods delete to delete entities by query has been renamed to deleteByQuery to prevent method call clashing with delete(Entity) in dynamic compilation mode.
By default, some issues can be met when using JAXB to map Groovy classes, due to the addition of the method getMetaClass to the generated bytecode.
+This extension allows you to automatically make getMetaClass as transient to avoid natively the known issues.
If you want to use this extension, you need to add the io.quarkiverse.groovy:quarkus-groovy-jaxb extension first to your build file.
| + + | +
+The extension io.quarkiverse.groovy:quarkus-groovy and the artifact io.quarkus:quarkus-jaxb are part of the dependencies of this extension.
+ |
+
Add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.groovy</groupId>
+ <artifactId>quarkus-groovy-jaxb</artifactId>
+ <version>${quarkusGroovyVersion}</version> (1)
+</dependency>| 1 | +Version of the Quarkus Groovy extension set in the properties of the project | +
This extension is only meant for integration tests where the server side code is written using JUnit 5 in native mode. +This extension allows you to automatically configure JUnit 5 to be used in native mode.
+If you want to use this extension, you need to add the io.quarkiverse.groovy:quarkus-groovy-junit5 extension first to your build file.
| + + | +
+The extension io.quarkiverse.groovy:quarkus-groovy and the artifact io.quarkus:quarkus-junit5 are part of the dependencies of this extension.
+ |
+
Add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.groovy</groupId>
+ <artifactId>quarkus-groovy-junit5</artifactId>
+ <version>${quarkusGroovyVersion}</version> (1)
+</dependency>| 1 | +Version of the Quarkus Groovy extension set in the properties of the project | +
The Quarkus project was designed with performance in mind, using Groovy’s CompileStatic annotation can improve the performance of the project. This annotation enforces static compilation of the code, allowing verification of types and method resolution during compilation rather than at runtime as is common in Groovy.
+The static compilation is also very handy in native mode to avoid complex reflection configuration that is required when using the dynamic compilation.
+Code example
+package org.acme.groovy
+
+import jakarta.ws.rs.GET
+import jakarta.ws.rs.Path
+import jakarta.ws.rs.Produces
+import jakarta.ws.rs.core.MediaType
+import groovy.transform.CompileStatic
+
+@CompileStatic
+@Path("/hello")
+class GreetingResource {
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ String get() {
+ return 'Hello Word'
+ }
+
+}In this example, we’re going to use the REST CRUD application in Quarkus from this example. Then, we’re going to push the Helm chart resources into a GIT repository. Next, we’re going to use the ArgoCD user interface to add a new application and configure it to use the GIT repository where we pushed the generated Helm chart.
+Maven 3.8+
+Java 17+
+Have logged into an ArgoCD instance
+Have installed the GIT command line
+We’re going to continue with the same REST CRUD application that we created for this example, so if you haven’t seen this example yet, go for it.
+After configuring the Quarkus Helm extension, the generated Helm charts will be created at target/helm/kubernetes/demo folder and usually the target folder is ignored when pushing changes into GIT, so let’s configure the Quarkus Helm repository to create the Helm charts into another repository.
quarkus.helm.output-directory=../folderNow, the Quarkus Helm extension will create the charts into the upper level project folder and will create a folder directory name.
Next, assuming your project is already a GIT repository, you need to commit this directory and push it:
+git add folder
+git commit -m "Added folder that contains generated Helm charts"
+git pushFinally, let’s go to ArgoCD.
+Assuming that you’re configured the ArgoCD project and the destination clusters/namespaces, you need to go to the ArgoCD user interface and click on the "+ NEW APP":
+
+In the next form, set the application name as you wish, the sync policy to automatic and as source and the ArgoCD project.
+Next, configure the Source by selecting the URL of your GIT repository and the correct branch. When doing this, ArgoCD will automatically detect the Helm charts that were found. Select the right one in the Path field.
+Then, use the cluster URL you configured in the destination.
+Moreover, ArgoCD will automatically map the Helm values YAML file into form parameters, so you can easily provide or overwrite any property:
+
+Now, click on "Create" and ArgoCD will automatically display all the resources, the application health and sync status:
+In this example, we’re going to create a very simple REST CRUD application in Quarkus and configure Integer, String and boolean properties into our applications.
+Sometimes, this is a challenging use case because most of the Kubernetes resources and System properties only support String/text properties.
+Maven 3.8+
+Java 17+
+Have logged into a Kubernetes cluster
+Have installed the Helm command line
+Our application will print a hello message with the string, integer, and boolean config properties. We’ll only need the following extensions:
+RESTEASY Reactive: REST support
+Kubernetes Config Extension: Use a config map to inject properties into the application.
+Let’s create our application from scratch:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=example \
+ -Dextensions="resteasy-reactive,kubernetes-config"
+cd exampleThe generated application will contain the following Hello resource:
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/hello")
+public class GreetingResource {
+
+ @ConfigProperty(name = "hello.message")
+ String message;
+
+ @ConfigProperty(name = "hello.number")
+ int number;
+
+ @ConfigProperty(name = "hello.flag")
+ boolean flag;
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return message + ", number=" + number + ", flag=" + flag;
+ }
+}Next, we need to provide the actual properties via the application.properties file:
hello.message=Hello from application.properties
+hello.number=1
+hello.flag=trueNow, if we run our application and call our service via http://localhost:8080/hello, it will return Hello from application.properties, number=1, flag=true.
How can we configure Quarkus Helm to map the hello properties and update them when installing the generated Helm chart?
+One way is using System properties, however this only supports String. If we map the above properties using system properties as described in the Mapping System Properties section:
+hello.message=${helloMessage}
+hello.number=${helloNumber}
+hello.flag=${helloFlag}When installing the Helm chart, this would fail because the hello.number and hello.flag properties are Strings. This is because internally Quarkus Helm is mapping the helloMessage system property as container environment properties which only supports String types.
Then, how can we do it? Quarkus Kubernetes Config to the rescue!
+Let’s add a ConfigMap resource in src/main/kubernetes/kubernetes.yml:
apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: app-config
+data:
+ hello.message: Hello from configmap
+ hello.number: 2
+ hello.flag: falseThe Quarkus Kubernetes extension will incorporate this ConfigMap resource in the generated resources at target/kubernetes/kubernetes.yml.
Next, we need to configure Quarkus to read this ConfigMap resource when starting the application in Kubernetes:
+quarkus.kubernetes-config.enabled=true
+quarkus.kubernetes-config.config-maps=app-configAs it is, if we build our application and install the Helm chart in Kubernetes, when calling the Hello endpoint, it would return: Hello from configmap, number=2, flag=false.
So good so far! Next, we can map the ConfigMap values into the Helm Chart values, so we can update these properties when installing the Helm chart. We can do this by adding the following properties:
+# Map values in ConfigMap
+quarkus.helm.values.message.paths=(kind == ConfigMap).data.'hello.message'
+quarkus.helm.values.number.paths=(kind == ConfigMap).data.'hello.number'
+quarkus.helm.values.number.value-as-int=1 (1)
+quarkus.helm.values.flag.paths=(kind == ConfigMap).data.'hello.flag'
+quarkus.helm.values.flag.value-as-bool=true (2)| 1 | +Since the default value type for ConfigMap is still a string, we need to let the Quarkus Helm extension that the actual type is an integer using the value-as-int property. |
+
| 2 | +And the same with the flag property. We need to instruct the Quarkus Helm extension that the actual type for the flag field is a boolean using value-as-bool. |
+
Finally, after building our application, we can install the Helm chart and configure the Hello properties with the right types. For example, installing the chart as follows:
+helm install quarkus target/helm/kubernetes/example --set app.number=3 --set app.flag=true --set app.message="Hello from helm"And calling the service again, it would return Hello from helm, number=3, flag=true.
Happy coding!
+In this example, we’re going to create a very simple REST CRUD application in Quarkus. Then, we’ll configure it to build the application image, and push it to a container registry, so Kubernetes can pull this image from. Next, we’ll configure the Quarkus Kubernetes and Helm extensions to generate the Helm chart and push it into a Helm repository. Finally, we’ll see how to install the generated Helm chart into Kubernetes from the Helm repository.
+Maven 3.8+
+Java 17+
+Have logged into a Kubernetes cluster
+Have installed the Helm command line
+Our application will simply manage fruits. For doing this, we’ll use the following extensions:
+RESTEASY Reactive Jackson: REST and JSON support
+Hibernate ORM REST Data with Panache: Database support, plus auto generation of CRUD resources from entities
+JDBC Postgresql: JDBC driver for Postgresql
+Let’s create our application from scratch:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=example \
+ -Dextensions="resteasy-reactive,hibernate-orm-rest-data-panache,jdbc-postgresql"
+cd exampleThe generated application will contain the following Hello resource:
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/hello")
+public class GreetingResource {
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return "Hello from RESTEasy Reactive";
+ }
+}So, if we start our application, for example running the Maven command mvn quarkus:dev (Quarkus DEV mode), we could call it using http://localhost:8080/hello.
To continue with, let’s add our first Fruit entity:
+@Entity
+public class Fruit extends PanacheEntity {
+ public String name;
+}Note that by extending to the PanacheEntity class, we’re adding a id column to our Fruit entity as primary key of type Long. So, our Fruit entity will have two columns: id and name columns.
Because we want to generate the CRUD resources of the Fruit entity, let’s configure the Hibernate ORM REST Data with Panache extension by simply adding the following interface:
+public interface FruitResource extends PanacheEntityResource<Fruit, Long> {
+}And that’s all we would need to expose the CRUD (list, get, update, delete) endpoints. If we start our application again in DEV mode (mvn quarkus:dev), we could retrieve the list of fruits by calling http://localhost:8080/fruit. However, as we don’t have data yet, the list is empty. So, let’s add some initial data by adding the file import.sql into src/main/resources:
insert into Fruit(id, name) values (1, 'apple');
+insert into Fruit(id, name) values (2, 'banana');And if we try http://localhost:8080/fruit again, we should see these fruits now!
[{"id": 1, "name": "apple"}, {"id": 2, "name": "banana"}]But how could it work if we didn’t specify any database yet? That’s the magic of running the application in DEV mode. This mode will transparently start a database in your local machine and provide the configuration, so your application works with this database.
+How does DEV mode know which database engine to start?
+DEV mode will check the JDBC driver you have configured in your project. In this example, we used jdbc-postgresql, so it will start a Postgresql database.
What properties is DEV mode adding to our application?
+There are a few, but the most important properties are:
+quarkus.datasource.jdbc.url=<the JDBC url>
+quarkus.datasource.username=<the database username>
+quarkus.datasource.password=<the database password>Therefore, to execute our application, we would need to provide these properties to use a running Postgresql database. The problem is that we don’t know where is the Postgresql database that we’ll use in Kubernetes! Then, one approach to address this situation is to provide these properties using environment properties:
+quarkus.datasource.jdbc.url=${POSTGRESQL_URL}
+quarkus.datasource.username=${POSTGRESQL_USERNAME}
+quarkus.datasource.password=${POSTGRESQL_PASSWORD}We’ll see in the following sections, how to populate these environment properties when installing the application in Kubernetes.
+We need to package our application into a container image, so Kubernetes can pull this image and start the application. +Fortunately, Quarkus provides several container image extensions to create this container image either using Docker, JIB or Buildpack.
+In this example, we’ll use the container image Docker extension, let’s add it:
+mvn quarkus:add-extension -Dextensions='container-image-docker'Note that if you’re using or going to use the Quarkus OpenShift extension, this automatically brings the container image s2i extension, and hence Quarkus will fail to build because you’re now using two container image extensions: docker and s2i. To solve this, you need to explicitly specify that you want to use the container image docker extension by adding:
+quarkus.container-image.builder=dockerNext, we need to enable the container image build and also the push property:
+quarkus.container-image.build=true
+quarkus.container-image.push=true
+quarkus.container-image.image=<CONTAINER REGISTRY>/<USERNAME>/<APP NAME>:<APP TAG>Note that you need to provide the right quarkus.container-image.image using a container registry you have logged in, for example: quarkus.container-image.image=quay.io/myuser/demo:0.0.1 (here, the container registry is quay.io, but you could use Docker Hub as well).
When building your application using maven mvn clean package, now you will see that the container image is built and pushed into the container registry we have configured.
Next, let’s generate the Kubernetes resources and the Helm chart.
+Quarkus Helm needs either Quarkus Kubernetes or OpenShift to be present because it uses the manifests generated by any of these extensions as source. Let’s use the Quarkus Kubernetes extension here, along to the Quarkus Helm extension:
+mvn quarkus:add-extension -Dextensions='kubernetes,helm'The Quarkus Helm extension will automatically map the system properties that are used in the application properties as pod container environment properties. So, if you go to the generated Helm chart at the target/helm/kubernetes/demo folder, you will see that the file values.yaml is also mapping these variables:
app:
+ serviceType: ClusterIP
+ image: quay.io/jcarvaja/quarkus-example:latest
+ envs:
+ POSTGRESQL_URL: ""
+ POSTGRESQL_USERNAME: ""
+ POSTGRESQL_PASSWORD: ""And that these values will be used in the deployment template at templates/deployment.yaml:
apiVersion: apps/v1
+kind: Deployment
+metadata:
+ labels:
+ app.kubernetes.io/version: 1.0.0-SNAPSHOT
+ app.kubernetes.io/name: helm-quickstart
+ name: demo
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app.kubernetes.io/version: 1.0.0-SNAPSHOT
+ app.kubernetes.io/name: demo
+ template:
+ metadata:
+ labels:
+ app.kubernetes.io/version: 1.0.0-SNAPSHOT
+ app.kubernetes.io/name: demo
+ spec:
+ containers:
+ - env:
+ - name: KUBERNETES_NAMESPACE
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.namespace
+ - name: POSTGRESQL_URL
+ value: {{ .Values.app.envs.POSTGRESQL_URL }}
+ - name: POSTGRESQL_PASSWORD
+ value: {{ .Values.app.envs.POSTGRESQL_PASSWORD }}
+ - name: POSTGRESQL_USERNAME
+ value: {{ .Values.app.envs.POSTGRESQL_USERNAME }}
+ image: {{ .Values.app.image }}
+ imagePullPolicy: Always
+ name: demo
+ ports:
+ - containerPort: 8080
+ name: http
+ protocol: TCPThanks to these replacements that the Quarkus Helm does, we can overwrite the default values when installing the Helm chart into Kubernetes!
+Let’s now define a Helm dependency to start a Postgresql database when we install the Helm chart:
+quarkus.helm.dependencies.postgresql.version=11.9.1
+quarkus.helm.dependencies.postgresql.repository=https://charts.bitnami.com/bitnami
+quarkus.helm.dependencies.postgresql.wait-for-service=demo-db:5432Note that we’ll add the property quarkus.helm.dependencies.postgresql.wait-for-service=demo-db:5432, so our application waits for this service before starting (you can go here to know more about this feature).
This Helm dependency will start the Postgresql database provided by Bitnami. According to the Bitnami documentation, to configure the database name, user and password we need to provide the following properties:
+postgresql.auth.database
+postgresql.auth.username
+postgresql.auth.password
+Therefore, we need to configure Quarkus Helm to map these properties into the generated values.yaml file by adding:
quarkus.helm.values."postgresql.auth.database".value=demo_database
+quarkus.helm.values."postgresql.auth.username".value=user
+quarkus.helm.values."postgresql.auth.password".value=supersecretNote that Bitnami images require root access to work which is incompatible with how OpenShift works, so if you want to install the Helm chart into OpenShift, you would also need to disable the root access by providing the following properties to the Postgresql dependency:
+quarkus.helm.values."postgresql.volumePermissions.enabled".value-as-bool=false
+quarkus.helm.values."postgresql.volumePermissions.securityContext.runAsUser".value=auto
+quarkus.helm.values."postgresql.securityContext.enabled".value-as-bool=false
+quarkus.helm.values."postgresql.shmVolume.chmod.enabled".value-as-bool=false
+quarkus.helm.values."postgresql.primary.containerSecurityContext.enabled".value-as-bool=false
+quarkus.helm.values."postgresql.primary.containerSecurityContext.runAsUser".value=auto
+quarkus.helm.values."postgresql.primary.podSecurityContext.enabled".value-as-bool=false
+quarkus.helm.values."postgresql.primary.podSecurityContext.fsGroup".value=autoAnd finally, we also need to overwrite the correct values of the environment properties:
+quarkus.helm.values."app.envs.POSTGRESQL_URL".value=jdbc:postgresql://demo-db:5432/demo_database
+quarkus.helm.values."app.envs.POSTGRESQL_USERNAME".value=user
+quarkus.helm.values."app.envs.POSTGRESQL_PASSWORD".value=supersecretNow, if we build again our project and check the generated Helm chart folder, we’ll see that the Chart.yaml file will have the expected Postgresql dependency:
+name: demo
+version: 1.0.0-SNAPSHOT
+apiVersion: v2
+dependencies:
+ - name: postgresql
+ version: 11.9.1
+ repository: https://charts.bitnami.com/bitnami
+ alias: postgresqlAnd it will be properly configured because the values.yml file will have the expected configuration:
app:
+ serviceType: ClusterIP
+ image: quay.io/jcarvaja/quarkus-example:latest
+ envs:
+ POSTGRESQL_URL: jdbc:postgresql://demo-db:5432/demo_database
+ POSTGRESQL_USERNAME: user
+ POSTGRESQL_PASSWORD: supersecret
+postgresql:
+ auth:
+ password: supersecret
+ database: demo_database
+ username: userWe can several ways to install the generated Helm chart:
+helm install --dependency-update demo ./target/helm/kubernetes/demoNote that the flag --dependency-update is necessary to download the Postgresql dependency before installing the Helm chart.
For this method, you need to push the generated Helm chart into a Helm repository. To know more about this feature, please go to this section.
+For example, to use the ChartMuseum Helm repository and perform the push of the generated Helm chart when building your application:
+quarkus.helm.repository.type=CHARTMUSEUM
+quarkus.helm.repository.url=<URL OF CHARTMUSEUM>/api/charts
+quarkus.helm.repository.push=trueNote that if you’re using the OpenShift extension, multiple deployment targets will be automatically generated: one for Kubernetes and another one for OpenShift (with the OpenShift specific resources). In this case, two Helm charts will be also generated: one for Kubernetes and another one for OpenShift, so when pushing the Helm chart into a Helm repository, you need to select only one by using the property quarkus.helm.repository.deployment-target. For example:
quarkus.helm.repository.deployment-target=openshiftAfter building your application and pushing the Helm chart into the Helm repository, you can now install the Helm chart from the Helm repository:
+# registering the chartmuseum repository into your local machine
+helm repo add chartmuseum <URL OF CHARTMUSEUM>
+
+# and install it
+helm install demo chartmuseum/demoA continuous delivery platform will automatically watch for changes in either a GIT or Helm repository and deploy the application or synchronize a running application in Kubernetes.
+You can know more about this method in this example which uses ArgoCD as Continuous Delivery platform which is really well integrated with Helm.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enabled the generation of Helm files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name of the Helm chart. If not set, it will use the application name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project’s home page of the Helm chart. It must be a URL. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm chart list of URLs to source code for this project. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Version of the Helm chart. If not set, it will use the application version. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm chart single-sentence description. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+List of keywords to add to the chart. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Icon of the Helm chart. It must be a URL to an SVG or PNG image. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Chart API version. The default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The condition to enable this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Tags of this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The version of the application enclosed of this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this chart is deprecated. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+KubeVersion is a SemVer constraint specifying the version of Kubernetes required. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the chart type: application or library. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Alias of the root element in the generated values file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Notes template to be generated. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Extension of the Helm tarball file. Default is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Classifier to be appended into the generated Helm tarball file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If Helm tar file is generated. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to generate the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to generate the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The input folder in which to place the user-defined Helm files. These files will be used as inputs to populate the generated Helm files. At the moment, the supported Helm files are: README.md, LICENSE, values.schema.json, app-readme.md or app-README.md, questions.yml or questions.yaml, the "crds" directory, and requirements.yml or requirements.yaml. Moreover, you can provide a custom
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The output folder in which to place the Helm generated folder. The folder is relative to the target output directory in Quarkus that is also configurable using the property
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If true, it will perform the upload to a Helm repository. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The deployment target to push. Options are:
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The Helm repository type. Options are:
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The Helm repository URL. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm repository username. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm repository password. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If enabled, the extension will check whether there are properties using system properties in the form of
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If true, the naming validation will be disabled. The naming validation rejects property names that contain "-" characters. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration for the separator string in the filename of profile specific values files i.e. values.profile.yaml, defaults to "." +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Title of the values schema json file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Email of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+URL profile of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Annotations are additional mappings uninterpreted by Helm, made available for inspection by other applications. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Name of the dependency. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Version of the dependency. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Repository of the dependency. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Dependency condition. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Dependency tags. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether this dependency should be loaded. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Alias of the dependency. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instruct the application to wait for the service that should be installed as part of this Helm dependency. You can set only a service name or a combination of a service name plus the service port (service:port). +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If wait for service is set, it will use this image to configure the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If wait for service is set, it will use this command to run the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If wait for service is set, it will use this command to run the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The name of the property that will be present in the Helm values file. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of YAMLPath expressions to map the Dekorate auto-generated properties to the final Helm values file. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The profile where this value reference will be mapped to. For example, if the profile is
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The integer value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The boolean value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The map value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+A list separated by comma that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If not provided, it will use
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Description of the property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Minimum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Maximum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Pattern to validate the value of this property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, then this property is mandatory. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The YAMLPath path where to include the template within the resource. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The expression template to include. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The property to use in the if statement. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The resource kind where to include the if statement. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The resource kind where to include the if statement. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The default value of the property +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Provide custom description of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the property to add or update. Example:
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Description of the property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Type of the property. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Minimum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Maximum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Pattern to validate the value of this property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, then this property is mandatory. +
+
+Environment variable: |
+boolean |
+
|
+
Helm is a package and install manager that standardizes and simplifies packaging and deployment of containerized applications with Kubernetes.
+Under the hood, the Quarkus Helm extension uses Dekorate to generate the Helm chart manifests at build time.
+Before getting started, make sure you’re using the right Quarkus Helm version that is compatible with the Quarkus version you’re using in your project. See the following table to see the compatibility among versions:
+| Quarkus Helm Version | +Quarkus Version | +
|---|---|
1.2.1 |
+Quarkus 3.5.0+ |
+
1.2.0 |
+Quarkus 3.5.0+ |
+
1.1.0 |
+Quarkus 3.3.0+ |
+
1.0.9 |
+Quarkus 3.2.0+ |
+
1.0.8 |
+Quarkus 3.1.0+ |
+
1.0.7 |
+Quarkus 3.1.0+ |
+
1.0.6 |
+Quarkus 3.0.0+ |
+
1.0.5 |
+Quarkus 3.0.0+ |
+
1.0.4 |
+Quarkus 3.0.0+ |
+
1.0.3 |
+Quarkus 3.0.0+ |
+
1.0.1 |
+Quarkus 3.0.0+ |
+
1.0.0 |
+Quarkus 3.0.0.Alpha - Quarkus 3.0.0.Beta |
+
0.2.9 |
+Quarkus 2.16+ |
+
0.2.8 |
+Quarkus 2.16+ |
+
0.2.7 |
+Quarkus 2.16+ |
+
0.2.6 |
+Quarkus 2.16+ |
+
0.2.5 |
+Quarkus 2.16+ |
+
0.2.4 |
+Quarkus 2.16+ |
+
0.2.3 |
+Quarkus 2.16+ |
+
0.2.2 |
+Quarkus 2.16+ |
+
0.2.1 |
+Quarkus 2.14.2 - 2.14.3 - 2.15+ |
+
0.2.0 |
+Quarkus 2.14.0 - 2.14.1 |
+
0.1.2 |
+Quarkus 2.13 |
+
0.1.1 |
+Quarkus 2.13 |
+
0.1.0 |
+Quarkus 2.13 |
+
0.0.7 |
+Quarkus 2.13 |
+
0.0.6 |
+Quarkus 2.12 |
+
Apart from all the features supported by the Quarkus Helm extension, in this documentation you will also find several examples about how to use this extension in:
+To complete this guide, you need:
+roughly 10 minutes
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+Helm command line installed
+Have connected/logged to a Kubernetes cluster
+The Quarkus Helm extension will generate the Helm Chart of a Quarkus application.
+In this example, we’ll create a Quarkus application with the Quarkus Helm extension by running the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=helm-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy-reactive,helm"
+cd helm-quickstartIf you already have your Quarkus project configured, you can add the helm extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="helm"This command will add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.helm</groupId>
+ <artifactId>quarkus-helm</artifactId>
+ <version>1.2.3</version>
+</dependency>After you add the Quarkus Helm extension to your project, you can now generate the Helm resources by running the following Maven command:
+./mvnw clean packageWhen using the Quarkus Helm extension, the Quarkus Kubernetes extension will be transitively loaded as well. So, the helm resources will include the following templates at target/helm/kubernetes/<chart name>/:
Chart.yaml
+values.yaml
+/charts
+/templates
+/templates/deployment.yaml
+/templates/ingress.yaml
+/templates/service.yaml
+/templates/NOTES.txt
+| + + | +
+
+
+The |
+
Let’s now see how to install the previously generated Helm resources on a Kubernetes cluster.
+First, you need to build the application container image and push it into a container registry. For doing this, Quarkus provides some container image extensions to ease up this step. Let’s add the Quarkus container image docker extension in this example:
+./mvnw quarkus:add-extension -Dextensions="container-image-docker"Now, we can generate the Helm resources and build/push the application container image at once by running the following Maven command:
+./mvnw clean package -Dquarkus.container-image.build=true -Dquarkus.container-image.push=true -Dquarkus.container-image.registry=<your container registry> -Dquarkus.container-image.group=<your container registry namespace>| + + | +
+
+
+Make sure the application container image is public and available to be used by your Kubernetes cluster. + |
+
Finally, let’s use Helm to deploy it into the cluster:
+helm install helm-example ./target/helm/kubernetes/<chart name>The above command will use the default values, which are located in ./target/helm/kubernetes/<chart name>/values.yaml.
+To override the default values, pass as parameter you own value file --values /path/to/another.values.yaml or set them using --set key1=val1 --set key2=val2.
Either via the upgrade option of Helm command line:
After making changes to your project and regenerating the Helm resources and the application container image, then you need to upgrade your deployment:
+helm upgrade helm-example ./target/helm/kubernetes/<chart name>Or via the set option of Helm command line:
helm upgrade helm-example ./target/helm/kubernetes/<chart name> --set app.replicas=1To complete this guide, you need:
+roughly 10 minutes
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+Helm command line installed
+Have connected/logged to a OpenShift cluster
+The Quarkus Helm extension will generate the Helm Chart of a Quarkus application.
+In this example, we’ll create a Quarkus application with the Quarkus Helm and the Quarkus OpenShift extensions by running the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=helm-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy-reactive,openshift,helm"
+cd helm-quickstartIf you already have your Quarkus project configured, you can add the helm extension to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="helm"This command will add the following dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.helm</groupId>
+ <artifactId>quarkus-helm</artifactId>
+ <version>1.2.3</version>
+</dependency>If you want to expose your application in OpenShift, you also need to enable the Route resource by adding the following configuration in your application properties:
+quarkus.openshift.route.expose=trueAnd since the Quarkus OpenShift extension will also generate the Kubernetes manifests, you need to explicitly specify the deployment target you want to use:
+quarkus.helm.repository.deployment-target=openshiftOnce we add the Quarkus Helm extension to your project, you can now generate the Helm resources by running the following Maven command:
+./mvnw clean packageThen the helm resources will include the following templates at target/helm/openshift/<chart name>/:
Chart.yaml
+values.yaml
+/charts
+/templates
+/templates/deployment.yaml
+/templates/route.yaml
+/templates/service.yaml
+/templates/NOTES.txt
+| + + | +
+
+
+The |
+
Let’s now see how to install the previously generated Helm resources on a OpenShift cluster.
+First, you need to build the application container image and push it into a container registry. For doing this, Quarkus provides some container image extensions to ease up this step. Let’s add the Quarkus container image docker extension in this example:
+./mvnw quarkus:add-extension -Dextensions="container-image-docker"Now, we can generate the Helm resources and build/push the application container image at once by running the following Maven command:
+./mvnw clean package -Dquarkus.container-image.builder=docker -Dquarkus.container-image.build=true -Dquarkus.container-image.push=true -Dquarkus.container-image.registry=<your container registry> -Dquarkus.container-image.group=<your container registry namespace>| + + | +
+
+
+Make sure the application container image is public and available to be used by your Kubernetes cluster. + |
+
Finally, let’s use Helm to deploy it into the cluster:
+helm install helm-example ./target/helm/openshift/<chart name>The above command will use the default values, which are located in ./target/helm/openshift/<chart name>/values.yaml.
+To override the default values, pass as parameter you own value file --values /path/to/another.values.yaml or set them using --set key1=val1 --set key2=val2.
Either via the upgrade option of Helm command line:
After making changes to your project and regenerating the Helm resources and the application container image, then you need to upgrade your deployment:
+helm upgrade helm-example ./target/helm/openshift/<chart name>Or via the set option of Helm command line:
helm upgrade helm-example ./target/helm/openshift/<chart name> --set app.replicas=1By default, the Quarkus Helm extension will generate the Helm values file (values.yaml) by mapping the following pre-configured properties:
The Kubernetes/Openshift replicas
+The Kubernetes/Openshift image
+The Kubernetes/Openshift Env Var values (only for plain values - secrets or configmaps are not supported yet)
+The Kubernetes ingress host
+The Openshift S2i builder image
+| + + | +
+
+
+If you would like to automatically map any other pre-configured properties, please submit a feature request at this repository, and we’ll work on it. + |
+
For example, if you set 3 replicas for your deployment:
+quarkus.helm.name=my-chart
+quarkus.helm.description=Description of my Chart
+
+# Set replicas to 3
+quarkus.kubernetes.replicas=3The extension will generate the next Helm values file at target/helm/<deployment target>/<chart name>/values.yaml:
app:
+ replicas: 3And the Deployment file at target/helm/<deployment target>/<chart name>/templates/deployment.yaml will have a reference to this value:
apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: helm-on-kubernetes-example
+spec:
+ replicas: '{{ .Values.app.replicas }}'This is done transparently to users.
+As we have introduced in the previous section, the Quarkus Helm extension will automatically map some properties like the replicas or the images to the Values helm file. Still, some users might need to map more properties. For example, let’s see the following YAML resource:
apiVersion: v1
+kind: Service
+metadata:
+ name: helm-on-kubernetes-exampleThe property at metadata.name, with value helm-on-kubernetes-example, will not be replaced with {{ .Values.app.name }} in the Helm templates.
+However, the extension allows users to define YAMLPath expressions to map these properties into the Helm values file. Let’s see how to do it using the above example to map the property metadata.name with {{ .Values.app.name }}. You only need to add the following properties to your configuration:
quarkus.helm.name=my-chart
+quarkus.helm.description=Description of my Chart
+
+# Map all the metadata name resources
+quarkus.helm.values.name.paths=metadata.nameThe resulting values.yaml file will look like as:
app:
+ name: helm-on-kubernetes-exampleThe app.name value is set automatically by the Quarkus Helm extension. However, users can provide other values using the value property:
quarkus.helm.name=my-chart
+quarkus.helm.description=Description of my Chart
+
+# Map all the metadata name resources
+quarkus.helm.values.name.paths=metadata.name
+## Overwrite value:
+quarkus.helm.values.name.value=this-is-another-nameAnd the values.yaml file will now contain:
app:
+ name: this-is-another-nameWe can directly use the configuration from the generated Values yaml file in the application.properties file. For example, if the generated values.yaml contains:
app:
+ greetings: HelloWe can map this value into the application.properties as this property was a system property:
greetings.message=${app.greetings}Now, when installing the Helm chart, we can configure the greetings message by doing:
+helm install helm-example ./target/helm/kubernetes/<chart name> --set app.greetings=Hola| + + | +
+
+
+Mapping system properties only works with string/text properties. For mapping other types, you would need to use the Kubernetes Config extension. See example here. + |
+
It’s a very common use case to expose some properties to be configurable when installing the Helm chart. For example, the data source JDBC url:
+quarkus.datasource.jdbc.url=jdbc:postgresql://host:1111/database
+quarkus.datasource.username=user
+quarkus.datasource.password=passIf we add the above properties into the application.properties file, the connection to the datasource is hardcoded to use a Postgresql instance at jdbc:postgresql://host:1111/database, and you won’t be able to change it when installing the Helm chart.
To allow some properties to be configurable at installing the Helm chart, you have several options:
+Using the Quarkus Kubernetes Config extension.
+This extension allows mounting ConfigMap and/or Secret resources where to take the application properties from. You can find more information about how to use it, in the official guide.
+Using system properties:
+You can map the actual configuration you would like to change at installing the Helm chart using system properties, for example:
+quarkus.datasource.jdbc.url=${POSTGRESQL_URL:jdbc:postgresql://host:1111/database}
+quarkus.datasource.username=${POSTGRESQL_USERNAME:user}
+quarkus.datasource.password=${POSTGRESQL_PASSWORD:pass}| + + | +
+
+
+In Quarkus, you can specify system properties using the pattern |
+
Next, the Quarkus Helm extension will detect that you’re using system properties in your application properties file and will configure the env var resources at the generated Deployment resource, and also map these properties into the generated Helm Chart values file:
+app:
+ envs:
+ POSTGRESQL_URL: jdbc:postgresql://host:1111/database
+ POSTGRESQL_USERNAME: user
+ POSTGRESQL_PASSWORD: pass| + + | +
+
+
+The Quarkus Helm extension does not force you to use a specific naming convention and by consequence, you can declare the system property using one the following: +
+
+
+
+The extension will use the property names declared as such under the
+
+
+
+ |
+
Therefore, you can now change these values when installing or updating the Helm chart by using:
+helm install helm-example ./target/helm/kubernetes/<chart name> --set app.envs.POSTGRESQL_URL=foo --set app.envs.POSTGRESQL_USERNAME=bar --set app.envs.POSTGRESQL_PASSWORD=tar| + + | +
+
+
+The mapping of system properties is enabled by default. If you want to disable it, you need to add this property |
+
What about if the properties are located in different places, for example:
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+ name: helm-on-kubernetes-example ## (1)
+spec:
+ rules:
+ - host: my-host
+ http:
+ paths:
+ - backend:
+ service:
+ name: helm-on-kubernetes-example ## (2)
+ port:
+ name: http
+ path: /
+ pathType: PrefixFrom this example, we need to map the value helm-on-kubernetes-example which is used in two places: (1) metadata.name and (2) spec.rules..http.paths..backend.service.name to the same property name. For doing this, we need to provide a comma-separated list of YAMLPath expressions to be mapped to app.name:
quarkus.helm.name=my-chart
+quarkus.helm.description=Description of my Chart
+
+# Map all the metadata name resources
+## Comma separated list of YAMLPath expressions:
+quarkus.helm.values.name.paths=metadata.name,(kind == Ingress).spec.rules.http.paths.backend.service.nameNow, the extension will first map the expression metadata.name and then the expression (kind == Ingress).spec.rules.http.paths.backend.service.name (this expression only applies to Ingress resources).
The alias name is the name used to keep all the properties linked as:
+app:
+ replicas: 3The alias name in the above example is "app" which is the default value. You can modify it using the property "quarkus.helm.values-root-alias=myAppName" and then the generated Helm resources will look like:
+myAppName:
+ replicas: 3Sometimes, your application requires of some other services to work. The typical scenario is when your application needs of a database to store the application data in. In this scenario, you need to declare the database service as a Helm dependency. For example, let’s declare the Postgres Bitnami Helm dependency as database instance:
+Chart.yaml:
dependencies:
+ - name: postgresql
+ version: 11.6.22
+ repository: https://charts.bitnami.com/bitnami
+ alias: database # this is optional. The default value is the `name`.| + + | +
+
+
+Before installing or packaging your Helm chart, you need to download the dependencies (you can use the Helm command |
+
Next, you can configure the dependencies adding the dependency configuration into the values.yaml file. For example, following the previous Postgres Bitnami dependency:
values.yaml:
database: # the value in the `alias` property, or the `name` if unset.
+ global:
+ postgresql:
+ auth:
+ database: my_db_name
+ postgresPassword: secretLet’s now see how you can add this configuration using the Quarkus Helm extension, so the chart.yaml and the values.yaml files are properly populated using a Helm dependency. You simply need to add the following properties:
application.properties:
quarkus.helm.dependencies.postgresql.alias=database
+quarkus.helm.dependencies.postgresql.version=11.6.22
+quarkus.helm.dependencies.postgresql.repository=https://charts.bitnami.com/bitnami
+
+quarkus.helm.values.0.property=database.global.postgresql.auth.postgresPassword
+quarkus.helm.values.0.value=secret
+quarkus.helm.values.1.property=postgresql.global.postgresql.auth.database
+quarkus.helm.values.1.value=my_db_nameThe Quarkus Helm extension will check whether the property set in quarkus.helm.values.xxx.property starts with a dependency alias or name. If so, it will use directly the value set. Otherwise, it will interpret that the property is an application property and will add the prefix set in the property quarkus.helm.values-root-alias (default value is app).
Alternatively, you can provide the properties of your dependency by providing the file values.yaml or the file Chart.yaml at src/main/helm (the path is configurable using the property quarkus.helm.input-directory). Let’s see an example:
src/main/helm/values.yaml:
database: # the value in the `alias` property, or the `name` if unset.
+ global:
+ postgresql:
+ auth:
+ database: my_db_name
+ postgresPassword: secretThis configuration will be aggregated in the autogenerated values file at target/helm/<deployment target>/<chart name>/values.yaml.
By default, Helm will start the Helm dependencies and the application at the same time. This might cause issues when running your application (as one of the dependencies might not have been started yet, for example, the database).
+The good news is that you can force the dependency installation order using the Quarkus Helm extension by adding the property quarkus.helm.dependencies.XX.wait-for-service=<service name>:
quarkus.helm.dependencies.postgresql.alias=database
+quarkus.helm.dependencies.postgresql.version=11.6.22
+quarkus.helm.dependencies.postgresql.repository=https://charts.bitnami.com/bitnami
+quarkus.helm.dependencies.postgresql.wait-for-service=chart-database:5432| + + | +
+
+
+The service name strongly depends on the Helm dependency to be installed, so you need to know the service name that the chart will expose beforehand. + |
+
This configuration will add the following init-containers in the Deployment resource of your Quarkus application:
+src/main/helm/kubernetes/templates/deployment.yaml:
initContainers:
+- image: alpine:3.16.2
+ args:
+ - -c
+ - for i in $(seq 1 200); do nc -z -w3 chart-database && exit 0 || sleep 3; done; exit 1
+ command:
+ - shYou can configure the image and the argument template to use with the properties quarkus.helm.dependencies.XX.wait-for-service-image, quarkus.helm.dependencies.0.wait-for-service-port-command-template and quarkus.helm.dependencies.0.wait-for-service-only-command-template.
Helm allows validating the input provided by the user when installing/updating the Helm charts. For example, we might want that the minimum value of the replicas is 3, so if users set a lesser value, Helm rejects it.
+These validation rules are specified in the values.schema.json file which this extension will automatically generate with:
+- A description of the automatically mapped properties.
+- The structure of the properties.
Therefore, to implement your validation rule, all you would need is to set the minimum value for app.replicas to 3 as follows:
quarkus.helm.values-schema.properties.replicas.minimum=3Apart from minimum, you can also specify a maximum value, or a pattern that the value has to follow or use the required flag.
+The Quarkus Helm extension partially supports Helm extensions via Helm templates and functions. You can make use of the templates and more complex functions using Helm expressions:
+# Example of expressions
+quarkus.helm.expressions.0.path=(kind == Service).metadata.annotations.'app.quarkus.io/commit-id'
+quarkus.helm.expressions.0.expression={{ .Values.app.favorite.drink | default "tea" | quote }}
+
+# Example of multiline expression
+quarkus.helm.expressions.1.path=(kind == ConfigMap && metadata.name == my-configmap).data
+quarkus.helm.expressions.1.expression={{- range $key, $val := .Values.app.favorite }}\n\
+{{ indent 2 $key }}: {{ $val | quote }}\n\
+{{- end }}The Quarkus Helm extension will replace the specified path with the provided expression.
+To provide your custom templates, you can add them into the folder src/main/helm/templates/_helpers.tpl, for example:
{{/*
+Expand the name of the chart.
+*/}}
+{{- define "foo.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 5 }}
+{{- end }}And next, you can use this function using the Helm include primitive:
+quarkus.helm.expressions.0.path=(kind == Service).metadata.annotations.'app.quarkus.io/build-timestamp'
+quarkus.helm.expressions.0.expression={{ include "foo.name" . }}Moreover, you can specify your Helm templates to only a concrete kind resource, for example, only for Service resources. To do this, you need to add the resource src/main/helm/templates/<kind>.yaml (following the example src/main/helm/templates/service.yaml). For example, the following resource will add two template functions called "mychart.labels" and "mychart.not-used":
{{- define "mychart.labels" }}
+ generator: helm
+{{- end }}
+{{- define "mychart.not-used" }}
+not:
+ used: !
+{{- end }}And let’s use the template "mychart.labels":
+quarkus.helm.expressions.0.path=(kind == Service && metadata.name == quarkus-helm-integration-tests-kubernetes-with-templates).metadata.labels
+quarkus.helm.expressions.0.expression={{- template "mychart.labels" }}A Helm chart repository is a location where packaged charts can be used and shared across the community.
+We can configure the Quarkus Helm extension to automatically push the generated Helm charts into Helm repositories using the following configuration:
+# To enable pushing to a Helm repository
+quarkus.helm.repository.push=true
+# The Helm repository type. Options are: `CHARTMUSEUM`, `ARTIFACTORY`, and `NEXUS`.
+quarkus.helm.repository.type=CHARTMUSEUM
+quarkus.helm.repository.url=<chart museum url>
+# Optional
+quarkus.helm.repository.username=...
+# Optional
+quarkus.helm.repository.password=...| + + | +
+
+
+All the previous properties can be set via system properties at build time. + |
+
Let’s see a practical example. First, we need to deploy a Helm repository. The easiest way to set up one, it’s installing ChartMuseum via docker:
+docker run --rm -u 0 -it -d -p 8080:8080 -e DEBUG=1 -e STORAGE=local -e STORAGE_LOCAL_ROOTDIR=/charts -v $(pwd)/charts:/charts chartmuseum/chartmuseum:latestThe ChartMuseum data will be stored in the "./charts" folder.
+Next, we’re going to build the Helm chart with the push to a repository enabled and using the just created helm repository:
+mvn clean install -Dquarkus.helm.repository.push=true -Dquarkus.helm.repository.url=http://localhost:8080/api/charts -Dquarkus.helm.repository.type=CHARTMUSEUMFor the local ChartMuseum, we don’t need to provide either the username or the password.
+Finally, let’s install the Helm chart from the Helm repository:
+helm repo add local http://localhost:8080
+helm install --devel my-quarkus local/quarkus-hello-worldBy default, all the properties are mapped to the same Helm values file values.yaml. However, the Quarkus Helm extension also supports the generation of Helm values by profiles.
+For example, let’s say we have two environments: one for testing and another one for production; each environment has a different ingress host where your Kubernetes applications will be exposed.
+We can configure our application as:
quarkus.kubernetes.ingress.expose=true
+# Mapped to `values.yaml` by the preconfigured Ingress decorator
+quarkus.kubernetes.ingress.host=my-host
+
+# Helm Chart
+quarkus.helm.name=my-chart
+## Overwrite the value of `quarkus.kubernetes.host` to `values.<profile-name>.yaml`:
+quarkus.helm.values.host.paths=(kind == Ingress).spec.rules.host
+quarkus.helm.values.host.value=my-test-host
+quarkus.helm.values.host.profile=testThis configuration will generate the values.yaml using the value set at the property quarkus.kubernetes.ingress.host:
app:
+ host: my-hostBut as you are now using a profile named test (see quarkus.helm.values.host.profile) in one of your mapped properties, it will also generate a values.test.yaml file with the content:
app:
+ host: my-test-host| + + | +
+
+
+By default, Quarkus Helm uses the "." character in the filename of profile specific values files i.e. |
+
Based on a boolean property that is available part of the values.yaml, you can specify whether you want to install or not any resource. For example, we want to install the generated Ingress resource only if I pass the following property app.ingress.enabled=true when installing the chart. Let’s see how to do this using the quarkus.helm.add-if-statement properties:
quarkus.helm.add-if-statement."ingress.enabled".on-resource-kind=Ingress
+quarkus.helm.add-if-statement."ingress.enabled".with-default-value=falseThis configuration will add the app.ingress.enabled property in the values.yaml file:
app:
+ ingress:
+ enabled: falseSo, when installing the chart, the Ingress resource won’t be installed by default.
+Now, to install it, you need to explicitly set the app.ingress.enabled=true property as helm install quarkus local/chart --set app.ingress.enabled=false and then the Ingress resource would be installed.
Using the helm binary requires the user to specify things like name and path for each chart, which is a repetitive process.
+Moreover, on multi-module projects it requires the command to be run for each of the modules providing a chart.
This extension provides a CLI utility that can be used along with the official Quarkus CLI. To use the Quarkus CLI, install the latest version of the Quarkus CLI. Use quarkus -v to verify the version number.
The plugin is enabled automatically when the Quarkus CLI is running from within a module that is using the helm extension.
+Note: If the plugin is not added automatically, it is possible that the extension catalog has not yet been updated with a quarkus-helm version that contains the CLI plugin. Until, then please use the manual installation steps.
To manually enable the CLI plugin for quarkus-helm:
quarkus plug add io.quarkiverse.helm:quarkus-helm-cli:{quarkus-helm-version} -d "Helm CLI"To list the available charts of the current projects or its sub-modules:
+quarkus helm listTo select a specific platform (e.g. kubernetes or openshift):
+quarkus helm list --platform kubernetesTo install all the available charts of the current project or its sub-modules;
+quarkus helm installThe command supports the --platform option too.
+The command also supports the --set option from the original helm cli:
quarkus helm install --set app.replicas=3In case you want to select a single chart among multiple modules for installation (e.g. user-service):
quarkus helm install user-serviceConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enabled the generation of Helm files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name of the Helm chart. If not set, it will use the application name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project’s home page of the Helm chart. It must be a URL. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm chart list of URLs to source code for this project. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Version of the Helm chart. If not set, it will use the application version. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm chart single-sentence description. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+List of keywords to add to the chart. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Icon of the Helm chart. It must be a URL to an SVG or PNG image. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Chart API version. The default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The condition to enable this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Tags of this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The version of the application enclosed of this chart. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether this chart is deprecated. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+KubeVersion is a SemVer constraint specifying the version of Kubernetes required. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the chart type: application or library. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Alias of the root element in the generated values file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Notes template to be generated. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Extension of the Helm tarball file. Default is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Classifier to be appended into the generated Helm tarball file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If Helm tar file is generated. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to generate the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to generate the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The input folder in which to place the user-defined Helm files. These files will be used as inputs to populate the generated Helm files. At the moment, the supported Helm files are: README.md, LICENSE, values.schema.json, app-readme.md or app-README.md, questions.yml or questions.yaml, the "crds" directory, and requirements.yml or requirements.yaml. Moreover, you can provide a custom
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The output folder in which to place the Helm generated folder. The folder is relative to the target output directory in Quarkus that is also configurable using the property
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If true, it will perform the upload to a Helm repository. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The deployment target to push. Options are:
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The Helm repository type. Options are:
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The Helm repository URL. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm repository username. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The Helm repository password. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If enabled, the extension will check whether there are properties using system properties in the form of
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If true, the naming validation will be disabled. The naming validation rejects property names that contain "-" characters. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration for the separator string in the filename of profile specific values files i.e. values.profile.yaml, defaults to "." +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Title of the values schema json file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Email of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+URL profile of the maintainer. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Annotations are additional mappings uninterpreted by Helm, made available for inspection by other applications. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Name of the dependency. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Version of the dependency. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Repository of the dependency. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Dependency condition. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Dependency tags. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether this dependency should be loaded. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Alias of the dependency. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instruct the application to wait for the service that should be installed as part of this Helm dependency. You can set only a service name or a combination of a service name plus the service port (service:port). +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If wait for service is set, it will use this image to configure the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If wait for service is set, it will use this command to run the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If wait for service is set, it will use this command to run the init-containers within the deployment resource. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The name of the property that will be present in the Helm values file. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma-separated list of YAMLPath expressions to map the Dekorate auto-generated properties to the final Helm values file. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The profile where this value reference will be mapped to. For example, if the profile is
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The integer value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The boolean value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The map value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+A list separated by comma that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+If not provided, it will use
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Description of the property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Minimum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Maximum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Pattern to validate the value of this property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, then this property is mandatory. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The YAMLPath path where to include the template within the resource. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The expression template to include. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The property to use in the if statement. If the property starts with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The resource kind where to include the if statement. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The resource kind where to include the if statement. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The default value of the property +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Provide custom description of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the property to add or update. Example:
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Description of the property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Type of the property. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Minimum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Maximum value allowed for this property. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Pattern to validate the value of this property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true, then this property is mandatory. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
This set of extensions provides various extra features for the Quarkus Hibernate Search integration.
+Quarkus Hibernate Search Extras provides different version streams for different versions of Quarkus.
+Refer to the README on the main branch
+to pick the appropriate version for your application.
If you need to use Amazon’s managed Elasticsearch service, +you will find it requires a proprietary authentication method involving request signing.
+To enable AWS request signing in Hibernate Search, an additional extension is required:
+./mvnw quarkus:add-extension -Dextensions="hibernate-search-orm-elasticsearch-aws"Once the extension is there, you will need some more configuration:
+Configure the AWS region with
+quarkus.hibernate-search-orm.elasticsearch.aws.region.
Enable request signing with
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled.
Optionally, configure how credentials are retrieved with
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type.
+The default gets the credentials from the application environment (AWS instance role, …),
+but several more options are available.
For example:
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=trueOr, if credentials are not available in the application environment (AWS instance role, …):
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=true
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type=static
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.access-key-id=AKIDEXAMPLE
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.secret-access-key=wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEYConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
This set of extensions provides various extra features for the Quarkus Hibernate Search integration.
+Quarkus Hibernate Search Extras provides different version streams for different versions of Quarkus.
+Refer to the README on the main branch
+to pick the appropriate version for your application.
If you need to use Amazon’s managed Elasticsearch service, +you will find it requires a proprietary authentication method involving request signing.
+To enable AWS request signing in Hibernate Search, an additional extension is required:
+./mvnw quarkus:add-extension -Dextensions="hibernate-search-orm-elasticsearch-aws"Once the extension is there, you will need some more configuration:
+Configure the AWS region with
+quarkus.hibernate-search-orm.elasticsearch.aws.region.
Enable request signing with
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled.
Optionally, configure how credentials are retrieved with
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type.
+The default gets the credentials from the application environment (AWS instance role, …),
+but several more options are available.
For example:
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=trueOr, if credentials are not available in the application environment (AWS instance role, …):
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=true
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type=static
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.access-key-id=AKIDEXAMPLE
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.secret-access-key=wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEYConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background.
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider.
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
This set of extensions provides various extra features for the Quarkus Hibernate Search integration.
+Quarkus Hibernate Search Extras provides different version streams for different versions of Quarkus.
+Refer to the README on the main branch
+to pick the appropriate version for your application.
If you need to use Amazon’s managed Elasticsearch service, +you will find it requires a proprietary authentication method involving request signing.
+To enable AWS request signing in Hibernate Search, an additional extension is required:
+./mvnw quarkus:add-extension -Dextensions="hibernate-search-orm-elasticsearch-aws"Once the extension is there, you will need some more configuration:
+Configure the AWS region with
+quarkus.hibernate-search-orm.elasticsearch.aws.region.
Enable request signing with
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled.
Optionally, configure how credentials are retrieved with
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type.
+The default gets the credentials from the application environment (AWS instance role, …),
+but several more options are available.
For example:
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=trueOr, if credentials are not available in the application environment (AWS instance role, …):
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=true
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type=static
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.access-key-id=AKIDEXAMPLE
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.secret-access-key=wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEYConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
This set of extensions provides various extra features for the Quarkus Hibernate Search integration.
+Quarkus Hibernate Search Extras provides different version streams for different versions of Quarkus.
+Refer to the README on the main branch
+to pick the appropriate version for your application.
If you need to use Amazon’s managed Elasticsearch service, +you will find it requires a proprietary authentication method involving request signing.
+To enable AWS request signing in Hibernate Search, an additional extension is required:
+./mvnw quarkus:add-extension -Dextensions="hibernate-search-orm-elasticsearch-aws"Once the extension is there, you will need some more configuration:
+Configure the AWS region with
+quarkus.hibernate-search-orm.elasticsearch.aws.region.
Enable request signing with
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled.
Optionally, configure how credentials are retrieved with
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type.
+The default gets the credentials from the application environment (AWS instance role, …),
+but several more options are available.
For example:
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=trueOr, if credentials are not available in the application environment (AWS instance role, …):
+quarkus.hibernate-search-orm.elasticsearch.aws.region=us-east-1
+quarkus.hibernate-search-orm.elasticsearch.aws.signing.enabled=true
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.type=static
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.access-key-id=AKIDEXAMPLE
+quarkus.hibernate-search-orm.elasticsearch.aws.credentials.static-provider.secret-access-key=wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEYConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+
+Whether requests should be signed using the AWS credentials. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+An Amazon Web Services region that hosts the Elasticsearch service. +
+
+Must be provided if signing is enabled; the region won’t be automatically detected. +
+
+See
+
+Environment variable: |
+Region |
++ |
+
+
+
+
+
+
+
+
+Configure the credentials provider that should be used to authenticate with AWS. +
+
+Available values: +
+
+
+
+Environment variable: |
+
+
|
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether this provider should fetch credentials asynchronously in the background. +
+
+If this is
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+Whether the provider should reuse the last successful credentials provider in the chain. +
+
+Reusing the last successful credentials provider will typically return credentials faster than searching through the chain. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+AWS Access key id +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Secret access key +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+
+
+AWS Session token +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of the profile that should be used by this credentials provider. +
+
+If not specified, the value in
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+
+Whether the provider should fetch credentials asynchronously in the background. +
+
+If this is true, threads are less likely to block when credentials are loaded, but additional resources are used to maintain the provider. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+
+
+
+The amount of time between when the credentials expire and when the credentials should start to be refreshed. +
+
+This allows the credentials to be refreshed *before* they are reported to expire. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+
+
+The maximum size of the output that can be returned by the external process before an exception is raised. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+
+
+
+
+The command that should be executed to retrieve credentials. +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+
+
+The name of custom AwsCredentialsProvider bean. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
| + + | +
+ About the MemorySize format
+
+
+A size configuration option recognises string in this format (shown as a regular expression): |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+Quarkus Hibernate types extension is based on the https://github.com/vladmihalcea/hibernate-types.
+If you want to use this extension, you need to add the quarkiverse-hibernate-types extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.hibernate</groupId>
+ <artifactId>quarkus-hibernate-types</artifactId>
+ <version>0.1.0</version>
+</dependency>Configuration property |
+Type |
+Default |
+Direction |
+
|---|---|---|---|
+
+
+
+
+
+
+Set the max reconnect attempts. + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the reconnect interval in seconds. + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Enable check for liveness/readiness. + |
+boolean |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Topic Used to check liveness/readiness. + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Timeout to declare the MQTT Client not ready (in ms). + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Timeout to declare the MQTT Client not alive. + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the keystore type + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the keystore location. In case of pem type this is the cert path + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+"Set the keystore password. In case of pem type this is not necessary + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the truststore type + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the truststore location. In case of pem type this is the cert path + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+"Set the truststore password. In case of pem type this is not necessary + |
+string |
++ | INCOMING_AND_OUTGOING |
+
Configuration property |
+Type |
+Default |
+Direction |
+
|---|---|---|---|
+
+
+
+
+
+
+Set the max reconnect attempts. + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the reconnect interval in seconds. + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Enable check for liveness/readiness. + |
+boolean |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Topic Used to check liveness/readiness. + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Timeout to declare the MQTT Client not ready (in ms). + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Timeout to declare the MQTT Client not alive. + |
+int |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the keystore type + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the keystore location. In case of pem type this is the cert path + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+"Set the keystore password. In case of pem type this is not necessary + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the truststore type + |
+string |
+
|
+INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+Set the truststore location. In case of pem type this is the cert path + |
+string |
++ | INCOMING_AND_OUTGOING |
+
+
+
+
+
+
+
+"Set the truststore password. In case of pem type this is not necessary + |
+string |
++ | INCOMING_AND_OUTGOING |
+
This extension allows usage of the HiveMQ MQTT Client inside a Quarkus App, in JVM and Native mode.
+Together with the "SmallRye Reactive Messaging MQTT" extension allows usage of a new connector type smallrye-mqtt-hivemq that will use HiveMQ Client instead of Vertx MQTT client.
+This adds some benefits to the original SmallRye MQTT:
+Battle tested MQTT Client outside Vertx landscape
+Management of external CA file for secure connections with self-signed certificates
+Backpressure support integrated with MQTT QOS
+Native mode support
+DevServices support
+Automatic and configurable reconnection handling and message redelivery
+Real Health Check against a configurable topic (defaults to the standard MQTT $SYS/broker/uptime) integrated in Quarkus HealthReport
+Many others you can read in official documentation here.
+Quarkus-hivemq-client version |
+Quarkus version |
+HiveMQ client version |
+
2.1.0 |
+3.7.3 |
+1.3.3 |
+
2.0.0 |
+3.6.5 |
+1.3.3 |
+
1.1.0 |
+2.16.12.Final |
+1.3.3 |
+
1.0.0 |
+2.16.10.Final |
+1.3.2 |
+
Requirements:
+Maven 3.8.1+
+JDK 17+ installed with JAVA_HOME configured appropriately
+If you want to use this extension, you need to add the io.quarkiverse.hivemqclient:quarkus-hivemq-client extension first to your build file.
<dependency>
+ <groupId>io.quarkiverse.hivemqclient</groupId>
+ <artifactId>quarkus-hivemq-client</artifactId>
+</dependency>You can do that by running the following command:
+./mvnw quarkus:add-extension -Dextensions="hivemq"| + + | +
+Keep in mind that you will also need io.quarkus:quarkus-smallrye-reactive-messaging-mqtt as a dependency on your build file as others smallrye reactive messaging APIs
+ |
+
You can create a Quarkus application with the HiveMQ-SmallRye extension from scratch by running the following command:
+mvn io.quarkus:quarkus-maven-plugin:3.7.3:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=hivemq-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dextensions="resteasy-reactive,hivemq,smallrye-reactive-messaging-mqtt"
+
+cd hivemq-quickstartAdd your channels configuration in src/main/resources/application.properties
Then configure your application by adding the HiveMQ connector type:
+# Configure the MQTT sink (we write to it)
+mp.messaging.outgoing.topic-price.connector=smallrye-mqtt-hivemq
+mp.messaging.outgoing.topic-price.topic=prices
+mp.messaging.outgoing.topic-price.auto-generated-client-id=true
+
+# Configure the MQTT source (we read from it)
+mp.messaging.incoming.prices.connector=smallrye-mqtt-hivemq
+mp.messaging.incoming.prices.topic=prices
+mp.messaging.incoming.prices.auto-generated-client-id=true| + + | ++change topic and channels names according to your needs + | +
And then implement your business logic
+package incoming;
+
+import org.eclipse.microprofile.reactive.messaging.Incoming;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class MqttPriceConsumer {
+
+ @Incoming("prices")
+ public void consume(byte[] raw) {
+ double price = Double.parseDouble(new String(raw));
+
+ // process your price.
+ }
+
+}package outgoing;
+
+import org.eclipse.microprofile.reactive.messaging.Outgoing;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class PriceGenerator {
+
+ private static final Logger LOG = Logger.getLogger(PriceGenerator.class);
+
+ private Random random = new Random();
+
+ @Outgoing("topic-price")
+ public Multi<Integer> generate() {
+ return Multi.createFrom().ticks().every(Duration.ofSeconds(1))
+ .onOverflow().drop()
+ .map(tick -> {
+ int price = random.nextInt(100);
+ LOG.infof("Sending price: %d", price);
+ return price;
+ });
+ }
+
+}| + + | ++On the above example, we are pushing events into the channel topic-price (which, based on the application.properties, is pointing to the topic prices). On the other hand, we are consuming these events through the channel prices, which is also pointing to the same topic. + | +
There is nothing special on HiveMQ extension that require any additional information than the official one.
+Currently, we are using the following images on CI:
+ubi-quarkus-native-image
+ubi-quarkus-mandrel
+ubi-quarkus-graalvmce-builder-imagefor example, you can run mvn -V -B -am clean verify -Dnative -Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel:22.3-java17
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether IronJacamar (pool) metrics are published in case a metrics extension is present. +
+
+This is a global setting and is not specific to a resource adapter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The kind of resource adapter. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Enable pool metrics collection. If unspecified, collecting metrics will be enabled by default if a metrics extension is active. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The configuration for this resource adapter +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+
+The transaction support level for the Connection Manager +
+
+See the TransactionSupportLevel Javadoc for more information +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+The number of times to retry the allocation of a connection +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+The time to wait between retries of the allocation of a connection +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The transaction timeout for the XAResource +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The flush strategy for the Connection Manager +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether the connection manager is sharable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should enlist connections +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should be connectable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should track connections +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Whether the connection manager should use CCM +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should use interleaving +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should use same RM override +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Whether the connection manager should wrap the XAResource +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should pad the XID +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The recovery username for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The recovery password for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The recovery security domain for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The pool strategy +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Minimum size of the pool +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Initial size of the pool +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+Maximum size of the pool +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Blocking timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+Idle timeout period. Default 30 mins +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+Validate on match validation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Background validation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Background validation - millis +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+
+Prefill pool +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Strict minimum, default false +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Do we want to immediately break when a connection cannot be matched and not evaluate the rest of the pool? +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Fairness of semaphore permits, default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the pool is sharable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Should the pool be created without a separate pool for non-transactional connections? +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The configuration for this resource adapter +
+
+Environment variable: |
+
|
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
This extension allows you to deploy JCA Resource Adapters in Quarkus. +IronJacamar is a Jakarta Connector Architecture (JCA) implementation.
+If you want to use this extension, you need to add the io.quarkiverse.ironjacamar:quarkus-ironjacamar extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.ironjacamar</groupId>
+ <artifactId>quarkus-ironjacamar</artifactId>
+ <version>1.1.2</version>
+</dependency>We recommend you to create a Quarkus extension dedicated for your Resource Adapter.
+This will allow you to build your Resource Adapter to native and perform the optimizations needed to run in Quarkus.
+If you don’t want to create a Quarkus extension for your Resource Adapter, just implement the ResourceAdapterFactory in your application code and you’ll be fine.
ResourceAdapterFactoryA ResourceAdapterFactory is an SPI that the IronJacamar extension introduces to create ResourceAdapter, ManagedConnectionFactory and ActivationSpec instances.
+You must use the @ResourceAdapterKind annotation on it to specify the resource adapter kind that will be used to identify the factory in the application code.
@ResourceAdapterKind(value = "artemis") (1)
+@ResourceAdapterTypes(connectionFactoryTypes = { jakarta.jms.ConnectionFactory.class }) (2)
+public class ArtemisResourceAdapterFactory implements ResourceAdapterFactory {...} (3)| 1 | +The value is the name of the resource adapter kind. +Because a Quarkus application can manage multiple resource adapters, this is used in the configuration to select the proper resource adapter to be configured and started. | +
| 2 | +The connection factory types that this resource adapter supports.
+This must be the types that the object returned in the jakarta.resource.spi.ManagedConnectionFactory.createConnectionFactory(jakarta.resource.spi.ConnectionManager) has.
+That will allow you to @Inject this object in your application code (eg. @Inject ConnectionFactory in this example). |
+
| 3 | +The implementation of the ResourceAdapterFactory interface.
+This is the class that will be instantiated by the IronJacamar extension to create the resource adapter instance. |
+
ResourceEndpointResource endpoints are activated in the ResourceAdapter (think EJB’s @MessageDriven annotation) and are declared using the @ResourceEndpoint annotation.
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+
+@ResourceEndpoint(activationSpecConfigKey = "myqueue") (1)
+public class MyResourceEndpoint implements jakarta.jms.MessageListener {...} (2)| 1 | +An optional activation spec configuration key.
+The activationSpecConfigKey is the key that will be consumed from the configuration (see the application.properties example below) |
+
| 2 | +The resource endpoint implementation.
+Because the Artemis ResourceAdapter implementation expects a jakarta.jms.MessageListener instance, you must implement this interface. |
+
The configuration may vary according to what the chosen ResourceAdapterFactory implementation expects.
The required interface may vary according to the resource adapter used. +If you are unsure of what to use, look at your resource adapter documentation.
+quarkus.ironjacamar.ra.kind=artemis (1)
+
+quarkus.ironjacamar.ra.config.connection-parameters=host=localhost;port=5445;protocols=HORNETQ (2)
+quarkus.ironjacamar.ra.config.protocol-manager-factory=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
+quarkus.ironjacamar.ra.config.user=guest
+quarkus.ironjacamar.ra.config.password=guest
+
+quarkus.ironjacamar.activation-spec.myqueue.config.destination-type=jakarta.jms.Queue (3)
+quarkus.ironjacamar.activation-spec.myqueue.config.destination=jms.queue.MyQueue
+quarkus.ironjacamar.activation-spec.myqueue.config.max-session=2
+quarkus.ironjacamar.activation-spec.myqueue.config.rebalance-connections=true| 1 | +This is the resource adapter kind.
+It must match the value of the @ResourceAdapterKind annotation in the ResourceAdapterFactory implementation. |
+
| 2 | +(Optional) You can specify the resource adapter configuration that will be passed to your ResourceAdapterFactory#createResourceAdapter implementation method. |
+
| 3 | +(Optional) You can specify optional activation spec configuration ResourceAdapterFactory#createActivationSpec implementation method. |
+
You can configure more than one ResourceAdapter instance in your application.
+Just name the resource adapter in the configuration:
quarkus.ironjacamar.main.ra.kind=artemis (1)
+quarkus.ironjacamar.other.ra.kind=artemisTo reference in the code, you must use the @io.smallrye.common.annotation.Identifier annotation:
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+import io.smallrye.common.annotation.Identifier;
+
+import jakarta.inject.Inject;
+
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.Message;
+import jakarta.jms.MessageListener;
+
+@ResourceEndpoint
+@Identifier("other") (1)
+public class MyResourceEndpoint implements MessageListener {
+
+ @Inject
+ @Identifier("main")
+ ConnectionFactory connectionFactory; (2)
+
+ @Override
+ public void onMessage(Message message) {
+ //...
+ }
+}| 1 | +This MessageListener will be activated by the other resource adapter configured above. |
+
| 2 | +This ConnectionFactory will be the one configured in the main resource adapter. |
+
Quarkus IronJacamar supports the @Transactional annotation on ResourceEndpoint implementations to automatically enlist the connection in the current transaction:
import io.quarkiverse.ironjacamar.ResourceEndpoint;
+
+import jakarta.inject.Inject;
+import jakarta.jms.ConnectionFactory;
+import jakarta.jms.Message;
+import jakarta.jms.MessageListener;
+import javax.transaction.Transactional;
+
+@ResourceEndpoint
+public class MyResourceEndpoint implements MessageListener {
+
+ @Inject
+ ConnectionFactory connectionFactory;
+
+ @Override
+ @Transactional
+ public void onMessage(Message message) {
+ //...
+ }
+}It also supports the @Transactional annotation on methods consuming the managed connection factories produced by the ResourceAdapterFactory implementation:
@Path("/jca")
+@ApplicationScoped
+public class JcaResource {
+
+ @Inject
+ ConnectionFactory connectionFactory;
+
+ @GET
+ @Path("/send")
+ @Transactional
+ public void send() {
+ try (Connection connection = connectionFactory.createConnection()) {
+ //...
+ }
+ }
+}Some adapter implementations may require additional configuration to enable transaction support. Check the adapter documentation for more details.
+if running in a XA transaction, it is recommended to enable recovery by using quarkus.transaction-manager.enable-recovery=true. Check the guide on Using Transactions in Quarkus for more details.
If you are using the quarkus-micrometer or quarkus-smallrye-metrics extension, quarkus-ironjacamar can contribute some connection pool-related metrics to the metric registry.
This can be activated by setting the quarkus.ironjacamar.metrics.enabled property to true.
Alternatively, you can disable the pool metrics for a specific resource adapter by setting the quarkus.ironjacamar."resource-adapter-name".ra.cm.pool.enable-metrics property to false.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether IronJacamar (pool) metrics are published in case a metrics extension is present. +
+
+This is a global setting and is not specific to a resource adapter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The kind of resource adapter. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Enable pool metrics collection. If unspecified, collecting metrics will be enabled by default if a metrics extension is active. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+The configuration for this resource adapter +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+
+The transaction support level for the Connection Manager +
+
+See the TransactionSupportLevel Javadoc for more information +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+The number of times to retry the allocation of a connection +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+The time to wait between retries of the allocation of a connection +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The transaction timeout for the XAResource +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+The flush strategy for the Connection Manager +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Whether the connection manager is sharable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should enlist connections +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should be connectable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should track connections +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Whether the connection manager should use CCM +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should use interleaving +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should use same RM override +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+
+Whether the connection manager should wrap the XAResource +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the connection manager should pad the XID +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The recovery username for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The recovery password for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The recovery security domain for the Connection Manager +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+The pool strategy +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Minimum size of the pool +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Initial size of the pool +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+
+Maximum size of the pool +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Blocking timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+Idle timeout period. Default 30 mins +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+
+Validate on match validation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Background validation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Background validation - millis +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+
+Prefill pool +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Strict minimum, default false +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Do we want to immediately break when a connection cannot be matched and not evaluate the rest of the pool? +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Fairness of semaphore permits, default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Whether the pool is sharable +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Should the pool be created without a separate pool for non-transactional connections? +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+The configuration for this resource adapter +
+
+Environment variable: |
+
|
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
A Quarkus extension that lets you utilize iText Library to create and manipulate PDFs on the fly.
+| + + | ++This is a fork of iText 2.1.7 version, the last version under MPL/LGPL. + | +
If you want to use this extension, you need to add the io.quarkiverse.itext:quarkus-itext extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.itext</groupId>
+ <artifactId>quarkus-itext</artifactId>
+ <version>3.0.4</version>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way. + |
+list of string |
+
|
+
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located + |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. + |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. + |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. + |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. + |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. + |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. + |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname + |
+
|
++ |
Describe what the extension does here.
+If you want to use this extension, you need to add the io.quarkiverse.jackson-jq:quarkus-jackson-jq extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.jackson-jq</groupId>
+ <artifactId>quarkus-jackson-jq</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way. + |
+list of string |
+
|
+
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located + |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. + |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. + |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. + |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. + |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. + |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. + |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Defines if the Jaeger extension is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether metrics are published in case a metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The traces endpoint, in case the client should connect directly to the Collector, like http://jaeger-collector:14268/api/traces +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+Authentication Token to send as "Bearer" to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username to send as part of "Basic" authentication to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to send as part of "Basic" authentication to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The hostname and port for communicating with agent via UDP +
+
+Environment variable: |
+host:port |
++ |
+
+
+
+
+
+Whether the reporter should also log the spans +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The reporter’s maximum queue size +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The reporter’s flush interval +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The sampler type (const, probabilistic, ratelimiting or remote) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sampler parameter (number) +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The host name and port when using the remote controlled sampler +
+
+Environment variable: |
+host:port |
++ |
+
+
+
+
+
+The service name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of formats to use for propagating the trace context. Defaults to the standard Jaeger format. Valid values are jaeger and b3 +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sender factory class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the trace context should be logged. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the registration of tracer as the global tracer should be disabled. This setting should only be turned on in tests that need to install a mock tracer. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether jaeger should run in zipkin compatibility mode +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
This extension is consumed by the Quarkus SmallRye OpenTracing extension.
+| + + | +
+
+
+OpenTelemetry is the recommended approach to tracing and telemetry for Quarkus. +
+
+The SmallRye OpenTracing support is discontinued and this extension is not actively maintained. +If you are interested in maintaining this extension, please reach out to us in the GitHub issues of this extension. + |
+
If you want to use this extension, you need to add the io.quarkiverse.jaeger:quarkus-jaeger extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.jaeger</groupId>
+ <artifactId>quarkus-jaeger</artifactId>
+ <version>1.0.0</version>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Defines if the Jaeger extension is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether metrics are published in case a metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The traces endpoint, in case the client should connect directly to the Collector, like http://jaeger-collector:14268/api/traces +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+Authentication Token to send as "Bearer" to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Username to send as part of "Basic" authentication to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password to send as part of "Basic" authentication to the endpoint +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The hostname and port for communicating with agent via UDP +
+
+Environment variable: |
+host:port |
++ |
+
+
+
+
+
+Whether the reporter should also log the spans +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The reporter’s maximum queue size +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The reporter’s flush interval +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The sampler type (const, probabilistic, ratelimiting or remote) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sampler parameter (number) +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The host name and port when using the remote controlled sampler +
+
+Environment variable: |
+host:port |
++ |
+
+
+
+
+
+The service name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of formats to use for propagating the trace context. Defaults to the standard Jaeger format. Valid values are jaeger and b3 +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sender factory class name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the trace context should be logged. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the registration of tracer as the global tracer should be disabled. This setting should only be turned on in tests that need to install a mock tracer. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether jaeger should run in zipkin compatibility mode +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
TBD
+Before you start development you need to prepare your embedded environment
+sudo apt update -y
+sudo apt upgrade -y
+apt -y install \
+ build-essential \
+ libz-dev \
+ git \
+ zlib1g-dev \
+ apt-transport-https \
+ ca-certificates \
+ curl \
+ wget \
+ linux-generic| + + | +
+
+
+Please update GRAAL_VERSION and GRAAL_JDK_VERSION values +to the latest if needed + |
+
sudo su
+export GRAAL_VERSION="22.1.0"
+export GRAAL_JDK_VERSION="17"
+export ARCH_LINUX_AARCH64="linux-aarch64"
+export GRAAL_ARCHITECTURE=${ARCH_LINUX_AARCH64}
+export GRAAL_DOWNLOAD_PATH="https://github.com/graalvm/graalvm-ce-builds/releases/download/vm-${GRAAL_VERSION}/graalvm-ce-java${GRAAL_JDK_VERSION}-${GRAAL_ARCHITECTURE}-${GRAAL_VERSION}.tar.gz"
+export GRAAL_FILE="graalvm-ce-java${GRAAL_JDK_VERSION}-${GRAAL_ARCHITECTURE}-${GRAAL_VERSION}"
+export GRAAL_GZIP_FILE="${GRAAL_FILE}.tar.gz"
+wget ${GRAAL_DOWNLOAD_PATH} -P /tmp
+tar -xvzf "/tmp/${GRAAL_GZIP_FILE}" -C /tmp
+mkdir /usr/lib/jvm
+export TMP_PATH="/tmp/graalvm-ce-java${GRAAL_JDK_VERSION}-${GRAAL_VERSION}/"
+export JVM_PATH="/usr/lib/jvm/graalvm-ce-java${GRAAL_JDK_VERSION}-${GRAAL_VERSION}"
+mv ${TMP_PATH} /usr/lib/jvm/
+rm "/tmp/${GRAAL_GZIP_FILE}"
+ln -s ${JVM_PATH} /usr/lib/jvm/graalvm
+update-alternatives --install /usr/bin/java java /usr/lib/jvm/graalvm/bin/java 20
+update-alternatives --set java /usr/lib/jvm/graalvm/bin/java
+export GRAALVM_HOME=/usr/lib/jvm/graalvm/
+export JAVA_HOME=/usr/lib/jvm/graalvm/
+export PATH=$PATH:$GRAALVM_HOME
+export PATH=$PATH:$GRAALVM_HOME/bin
+echo "export JAVA_HOME=/usr/lib/jvm/graalvm/" >>/etc/profile
+echo "export GRAALVM_HOME=/usr/lib/jvm/graalvm/" >>/etc/profile
+echo "export PATH=$PATH:$GRAALVM_HOME" >>/etc/profile
+echo "export PATH=$PATH:$GRAALVM_HOME/bin" >>/etc/profile
+export NATIVE_IMAGE_JAR="native-image-installable-svm-java${GRAAL_JDK_VERSION}-${GRAAL_ARCHITECTURE}-${GRAAL_VERSION}.jar"
+wget "https://github.com/graalvm/graalvm-ce-builds/releases/download/vm-${GRAAL_VERSION}/${NATIVE_IMAGE_JAR}" -P /tmp
+${GRAALVM_HOME}/bin/gu -L install "/tmp/${NATIVE_IMAGE_JAR}"
+rm "/tmp/${NATIVE_IMAGE_JAR}"| + + | +
+
+
+Please update MAVEN_VERSION value +to the latest if needed + |
+
export MAVEN_VERSION="3.8.6"
+wget "https://dlcdn.apache.org/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz" -P /tmp
+tar -xvzf "/tmp/apache-maven-${MAVEN_VERSION}-bin.tar.gz" -C /tmp
+rm -d -r "/usr/lib/maven/apache-maven-${MAVEN_VERSION}"
+mv "/tmp/apache-maven-${MAVEN_VERSION}/" /usr/lib/maven/
+update-alternatives --install /usr/bin/mvn mvn /usr/lib/maven/apache-maven-${MAVEN_VERSION}/bin/mvn 20
+update-alternatives --set mvn /usr/lib/maven/apache-maven-${MAVEN_VERSION}/bin/mvn
+export M2_HOME=/usr/lib/maven
+export PATH=$PATH:$M2_HOME
+export PATH=$PATH:$M2_HOME/bin
+echo "export M2_HOME=/usr/lib/maven" >>/etc/profile
+echo "export PATH=$PATH:$M2_HOME" >>/etc/profile
+echo "export PATH=$PATH:$M2_HOME/bin" >>/etc/profileFor the remote development you need to share board folders to your PC
+sudo apt -y install samba samba-common-binEdit samba configuration file and save over Ctrl+X
+sudo nano /etc/samba/smb.conf
+[board]
+comment = My Board
+path = /home/pi
+browseable = yes
+writeable = yes
+force create mode = 0777
+force directory mode = 0777
+public = yesand reboot
+sudo systemctl restart smbdCongratulations! Your environment is ready.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable serial bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to serial or USB bus like |
+string |
++ |
+
+
+
+
+
+Set serial bus speed to one of values described in |
+enum |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable SPI bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to SPI bus like |
+string |
++ |
+
+
+
+
+
+SPI bus speed. Please check your vendor CPU documentation for acceptable values + |
+integer |
+
|
+
+
+
+
+
+
+SPI bus mode. + |
+
|
+
|
+
+
+
+
+
+
+Word length for byte in bus + |
+enum |
+
|
+
+
+
+
+
+
+Bits ordering for bus + |
+
|
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable I2C bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to I2C bus like |
+string |
++ |
+
+
+
+
+
+Describe is I2C 7 bits or 10 bits bus. Please check with CPU vendor documentation. + |
+boolean |
+
|
+
+
+
+
+
+
+Amount of retries in bus. Default is not set and using default vendor value + |
+integer |
+
|
+
+
+
+
+
+
+Timeout in bus. Default is not set and using default vendor value. + |
+integer |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable GPIOs + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable One Wire bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable GPIOs + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable I2C bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to I2C bus like |
+string |
++ |
+
+
+
+
+
+Describe is I2C 7 bits or 10 bits bus. Please check with CPU vendor documentation. + |
+boolean |
+
|
+
+
+
+
+
+
+Amount of retries in bus. Default is not set and using default vendor value + |
+integer |
+
|
+
+
+
+
+
+
+Timeout in bus. Default is not set and using default vendor value. + |
+integer |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable One Wire bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable serial bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to serial or USB bus like |
+string |
++ |
+
+
+
+
+
+Set serial bus speed to one of values described in |
+enum |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable SPI bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to SPI bus like |
+string |
++ |
+
+
+
+
+
+SPI bus speed. Please check your vendor CPU documentation for acceptable values + |
+integer |
+
|
+
+
+
+
+
+
+SPI bus mode. + |
+
|
+
|
+
+
+
+
+
+
+Word length for byte in bus + |
+enum |
+
|
+
+
+
+
+
+
+Bits ordering for bus + |
+
|
+
|
+
TBD
+TBD
+Describe what the extension does here.
+Before installation of Quarkus extension you need to prepare your Raspberry Pi.
+If you not expert in embedded development theory can be helpful
+If you want to use this extension in your projects, you need to add the io.quarkiverse.jef:quarkus-java-embedded-framework extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.jef</groupId>
+ <artifactId>quarkus-java-embedded-framework</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable serial bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to serial or USB bus like |
+string |
++ |
+
+
+
+
+
+Set serial bus speed to one of values described in |
+enum |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable SPI bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to SPI bus like |
+string |
++ |
+
+
+
+
+
+SPI bus speed. Please check your vendor CPU documentation for acceptable values + |
+integer |
+
|
+
+
+
+
+
+
+SPI bus mode. + |
+
|
+
|
+
+
+
+
+
+
+Word length for byte in bus + |
+enum |
+
|
+
+
+
+
+
+
+Bits ordering for bus + |
+
|
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable I2C bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to I2C bus like |
+string |
++ |
+
+
+
+
+
+Describe is I2C 7 bits or 10 bits bus. Please check with CPU vendor documentation. + |
+boolean |
+
|
+
+
+
+
+
+
+Amount of retries in bus. Default is not set and using default vendor value + |
+integer |
+
|
+
+
+
+
+
+
+Timeout in bus. Default is not set and using default vendor value. + |
+integer |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable GPIOs + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enable or disable One Wire bus + |
+boolean |
+
|
+
+
+
+
+
+
+Path to GPIO like |
+string |
++ |
TBD
+To track what commands or data send to buses or from buses you need to enable linux tracing debugfs
+sudo su
+echo 'i2c:*' > /sys/kernel/debug/tracing/set_event
+echo 'smbus:*' > /sys/kernel/debug/tracing/set_event| + + | +
+
+
+All events will be available in |
+
sudo su
+echo 'spi:*' > /sys/kernel/debug/tracing/set_event| + + | +
+
+
+All events will be available in |
+
sudo su
+echo 'gpio:*' > /sys/kernel/debug/tracing/set_event| + + | +
+
+
+All events will be available in |
+
These commands will enable logging only for current linux session and will be disabled after reboot.
+If you want to add tracing logging permanently please add commands to cmdline boot options.
+For example in RaspberryPi need to update /boot/cmdline.txt and add tracing in the format below:
trace_evace_event=i2c:*,smbus:*,spi:*,gpio:*When you compile your application with quarkus:dev Quarkus will enable Dev Services for JEF Extension
| + + | +
+
+
+For the remote debugging from your development machine you need to run Quarkus via +
+
+
+
+
+
+In this case |
+
JEF DevServices widget will look like:
+
+Some additional information about interfaces will be available if you click to the links.
+| + + | ++Describe what the extension does here. + | +
If you want to use this extension, you need to add the io.quarkiverse.quarkus-jdbc-clickhouse:quarkus-jdbc-clickhouse extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.jdbc</groupId>
+ <artifactId>quarkus-jdbc-clickhouse</artifactId>
+ <version>3.0.1</version>
+</dependency>You can find all the information about how to configure a datasource in Quarkus in the official Quarkus documentation.
+The db-kind used by this extension is sqlite so a configuration defining a default SQLite datasource looks like:
quarkus.datasource.db-kind=sqlite
+quarkus.datasource.jdbc.url=... (1)| 1 | +See below for SQLite JDBC URLs. | +
SQLite only runs as an embedded database.
+You can specify connection details using the JDBC URL, or use the defaults.
+An SQLite JDBC URL looks like the following:
+jdbc:sqlite:[path]/[name][?key=value…]
jdbc:sqlite:/home/user/mydatabase.db
SQLite also supports in-memory database management, which does not create any database files. +To use an in-memory database, specify the following JDBC URL:
+jdbc:sqlite::memory:
The official documentation and URI Examples go into more details and list optional parameters as well.
+Quarkus JDBC SQLite is a Quarkus extention for the SQLite database.
+If you want to use this extension, you need to add the io.quarkiverse.jdbc:quarkus-jdbc-sqlite extension first.
For instance, in your pom.xml file, add the following dependency:
<dependency>
+ <groupId>io.quarkiverse.jdbc</groupId>
+ <artifactId>quarkus-jdbc-sqlite</artifactId>
+</dependency>You can find more information about how to configure the datasource here.
+Jdbi provides convenient, idiomatic access to relational data in Java +It is using reflection quite a bit, so you need this extension will allow native image processing.
+If you want to use this extension, you need to add the io.quarkiverse.jdbi:quarkus-jdbi extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.jdbi</groupId>
+ <artifactId>quarkus-jdbi</artifactId>
+ <version>1.3.1</version>
+</dependency>The Quarkus JGit extension enables the use of Eclipse JGit +in a native executable.
+Once you have your Quarkus project configured you can add the jgit extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="jgit"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jgit</groupId>
+ <artifactId>quarkus-jgit</artifactId>
+ <version>3.0.7</version>
+</dependency>The JGit dependency is resolved transitively when the extension is added to your project. +Here is an example using it in a JAX-RS endpoint:
+ @GET
+ @Path("/clone")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String cloneRepository(@QueryParam("url") String url) throws Exception {
+ File tmpDir = Files.createTempDirectory("tmpgit").toFile();
+ try (Git git = Git.cloneRepository().setDirectory(tmpDir).setURI(url).call()) {
+ return tmpDir.toString();
+ }
+ }| + + | +
+
+
+When building a native executable, make sure that the SSL support is configured appropriately. + |
+
Describe what the extension does here.
+The Quarkus NoSQL Extension facilitates seamless interaction between Quarkus and Eclipse JNoSQL, enabling easy integration with various NoSQL databases in Quarkus applications. By following the steps outlined in this documentation, Quarkus developers can effortlessly incorporate Eclipse JNoSQL into their projects, simplifying NoSQL database interactions and empowering the development of efficient and scalable applications. Eclipse JNoSQL adheres to two essential Jakarta EE specifications: Jakarta Data and Jakarta NoSQL.
+Jakarta NoSQL is a Java framework designed to streamline the integration of Java applications with various NoSQL databases. It offers a consistent and easy-to-use API, allowing developers to interact with different NoSQL databases seamlessly.
+On the other hand, the Jakarta Data specification provides an API for simplified data access to various database types, including relational and NoSQL databases. Java developers can access these repositories through multiple methods, such as composing custom queries on a Repository interface.
+Integrating Eclipse JNoSQL into Quarkus projects ensures adherence to these Jakarta EE standards and leverages the benefits of standardized APIs for enhanced productivity and maintainability.
+The Quarkus NoSQL Extension offers several advantages for developers:
+Simplified NoSQL Integration: Abstracts the complexity of working with different NoSQL databases, providing a consistent API regardless of the underlying technology. Facilitates easy switching between databases or using multiple databases in a single application.
+Type-Safe Queries: Empowers developers to write database queries using Java code rather than raw query strings, improving code readability and catching errors at compile-time.
+Seamless Quarkus Integration: Utilizes Quarkus' fast startup times and efficient resource utilization while working with NoSQL databases, ensuring lightweight and responsive applications.
+Database Agnosticism: Supports a wide range of NoSQL databases, including key-value stores, document databases, and column-family stores. Offers flexibility to choose the most suitable database for specific use cases without major code changes.
+Rich Documentation and Ecosystem: Eclipse JNoSQL boasts a thriving community and comprehensive documentation, making it easy for developers to find support, tutorials, and examples. Integration with Quarkus allows tapping into the vibrant Quarkus ecosystem as well.
+To use this extension, add the io.quarkiverse.jnosql:quarkus-jnosql extension to your build file. For instance, with Maven, include the following dependency in your POM file:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql</artifactId>
+ <version>3.2.2.1</version>
+</dependency>Getting started with Quarkus JNoSQL is straightforward:
+Add the Quarkus JNoSQL Extension to your project’s dependencies. You can find the latest version on Maven Central.
+Define your entities using JNoSQL annotations. For example:
+import jakarta.nosql.Column;
+import jakarta.nosql.Entity;
+import jakarta.nosql.Id;
+
+@Entity
+public class TestEntity {
+
+ @Id
+ private String id;
+
+ @Column
+ private String testField;
+}Configure the JNoSql KeyValue Quarkus extension by specifying the name of the database that will be utilized within the Eclipse JNoSQL framework in your application.properties:
jnosql.keyvalue.database=my-database-nameInject the KeyValueTemplate into your class and use it to interact with the KeyValue database:
import jakarta.inject.Inject;
+import org.jnosql.artemis.key.KeyValueTemplate;
+
+@Inject
+private KeyValueTemplate template;
+
+public void insert(TestEntity entity) {
+ template.insert(entity);
+}When configuring databases for use with Quarkus and Eclipse JNoSQL, it’s important to note that instead of using the traditional Eclipse JNoSQL properties and configuration, Quarkus provides its properties and configuration for seamless integration. Below are sections detailing the configuration specifics for different NoSQL databases within the Quarkus environment.
+| + + | ++The forthcoming sections will delve into the configuration details for ArangoDB, DynamoDB, Hazelcast, and Redis databases, providing comprehensive guidance for each. + | +
Add the ArangoDB dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-keyvalue-arangodb</artifactId>
+</dependency>For specific configuration details, please refer to the ArangoDB JNoSQL driver.
+Add the DynamoDB dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-keyvalue-dynamodb</artifactId>
+</dependency>Please refer to the DynamoDB Quarkiverse extension for specific configuration details.
+Add the Hazelcast dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-keyvalue-hazelcast</artifactId>
+</dependency>Please refer to the Quarkus Hazelcast extension for specific configuration details.
+Add the Redis dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-keyvalue-redis</artifactId>
+</dependency>For specific configuration details, please refer to the Redis Quarkus extension.
+Configure the JNoSql Document Quarkus extension by specifying the database’s name in your application.properties:
jnosql.document.database=my-database-nameInject the DocumentTemplate into your class and use it to interact with the Document database:
import jakarta.inject.Inject;
+import org.jnosql.artemis.document.DocumentTemplate;
+
+@Inject
+private DocumentTemplate template;
+
+public void insert(TestDocumentEntity entity) {
+ template.insert(entity);
+}When configuring databases for use with Quarkus and Eclipse JNoSQL, it’s important to note that instead of using the traditional Eclipse JNoSQL properties and configuration, Quarkus provides its properties and configuration for seamless integration. Below are sections detailing the configuration specifics for different NoSQL databases within the Quarkus environment.
+| + + | ++The forthcoming sections will delve into the configuration details for ArangoDB, CouchDB, Elasticsearch, MongoDB, and Solr databases, providing comprehensive guidance for each. + | +
Add the ArangoDB dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-document-arangodb</artifactId>
+</dependency>For specific configuration details, please refer to the ArangoDB JNoSQL driver.
+Add the CouchDB dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-document-couchdb</artifactId>
+</dependency>For specific configuration details, please refer to the CouchDB JNoSQL driver.
+Add the Elasticsearch dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-document-elasticsearch</artifactId>
+</dependency>For specific configuration details, please refer to the ElasticSearch driver.
+Add the MongoDB dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-document-mongodb</artifactId>
+</dependency>For specific configuration details, please refer to the MongoDB configuration.
+Add the Solr dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-document-solr</artifactId>
+</dependency>For specific configuration details, please refer to the Solr JNoSQL driver.
+Configure the JNoSql Column Quarkus extension by specifying the database’s name in your application.properties:
jnosql.column.database=my-database-nameInject the ColumnTemplate into your class and use it to interact with the Column database:
import jakarta.inject.Inject;
+import org.jnosql.artemis.column.ColumnTemplate;
+
+@Inject
+private ColumnTemplate template;
+
+public void insert(TestColumnEntity entity) {
+ template.insert(entity);
+}Add the Cassandra dependency to your project’s pom.xml:
<dependency>
+ <groupId>io.quarkiverse.jnosql</groupId>
+ <artifactId>quarkus-jnosql-column-cassandra</artifactId>
+</dependency>Please refer to the Cassandra Quarkus extension for specific configuration details.
+| + + | ++This is an excerpt of the full JPAStreamer docs. For the full documentation, see +JPAStreamer User Guide. + | +
JPAStreamer is an extension for JPA applications developed by Speedment Inc. It allows JPA queries to be expressed as standard Java Streams, which means queries are type-safe and intuitive to read and write. The library is designed to augment the API of the underlying JPA provider, .e.g Hibernate, without the need for replacing existing software components, thus JPAStreamer can be integrated without effecting the current codebase.
+Here is an example of a typical Stream query, highlighting the similarities between the Stream and CRUD operations.
+ jpaStreamer.stream(Film.class) (1)
+ .filter(Film$.title.startsWith("A")) (2)
+ .sorted(Film$.length.reversed()) (3)
+ .limit(limit); (4)| 1 | +FROM | +
| 2 | +SELECT | +
| 3 | +ORDER BY | +
| 4 | +LIMIT | +
| + + | ++It is important to notice that JPAStreamer does not materialize the Stream, but inspects the Stream pipeline and merge the operations to a standard HQL query which is executed in the database. + | +
JPASteamer requires that the following criteria are fulfilled:
+JDK 11+ installed and correctly mapped to JAVA_HOME
+A Quarkus database application that relies on a JPA provider and has a JPA meta model. A common example is a standard Hibernate application with JPA Entities that maps to database objects.
+To use JPAStreamer in your Quarkus application, simply add the JPAStreamer Quarkus extension to your build file. With Maven, this is done by adding the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.jpastreamer</groupId>
+ <artifactId>quarkus-jpastreamer</artifactId>
+ <version>1.0.1</version>
+</dependency>You can also add the JPAStreamer dependency automatically with the command:
+quarkus extension add 'io.quarkiverse.jpastreamer:quarkus-jpastreamer'Using the JPAStreamer Quarkus extension is no different from using the standard JPAStreamer library. Thus the JPAStreamer User Guide is the most complete reference during development.
+There are however a few things to consider if running JPAStreamer alongside Panache in a Quarkus Hibernate application. The most recent version of JPAStreamer does not have support for Panache’s Active Record Pattern. This means the resulting JPAStreamer metamodel will most likely be erroneous. Therefore, we currently recommend Panache’s Repository Pattern.
+JPAStreamer can be initialized in a Panache Repository as follows:
+@ApplicationScoped
+public class FilmRepository implements PanacheRepository<Film> {
+
+ private final JPAStreamer jpaStreamer = JPAStreamer.of(this::getEntityManager); (1)
+
+ public String startsWitASortedByLength(short limit) {
+ return jpaStreamer.stream(Film.class) (2)
+ .filter(Film$.title.startsWith("A")) (3)
+ .sorted(Film$.length.reversed()) (4)
+ .limit(limit); (5)
+ }
+}| 1 | +Instantiate JPAStreamer with a Supplier<EntityManager> |
+
| 2 | +Selects the Film entity as the stream source | +
| 3 | +Only selects films with a title that starts with "A" | +
| 4 | +Sort the films by descending length (longest first) | +
| 5 | +Limit the results to a given number of films | +
The JPAStreamer Quarkus extension is released under the LGPL 2.1 License.
+| + + | ++This is an excerpt of the full JPAStreamer docs. For the full documentation, see +JPAStreamer User Guide. + | +
JPAStreamer is an extension for JPA applications developed by Speedment Inc. It allows JPA queries to be expressed as standard Java Streams, making queries type-safe and intuitive to read and write. The library is designed to enhance the API of the underlying JPA provider (e.g., Hibernate) without replacing existing software components. This allows for seamless integration of JPAStreamer into the current codebase.
+Here is an example of a typical Stream query, highlighting the similarities between Stream and CRUD operations:
+ jpaStreamer.stream(Film.class) (1)
+ .filter(Film$.title.startsWith("A")) (2)
+ .sorted(Film$.length.reversed()) (3)
+ .limit(limit); (4)| 1 | +FROM | +
| 2 | +SELECT | +
| 3 | +ORDER BY | +
| 4 | +LIMIT | +
| + + | ++JPAStreamer does not materialize the Stream. Instead, it inspects the Stream pipeline and merges the operations into a standard HQL query that is executed in the database. + | +
To use JPAStreamer, make sure the following criteria are fulfilled:
+JDK 11+ installed and correctly mapped to JAVA_HOME.
+A Quarkus database application that relies on a JPA provider and has a JPA metamodel. A common example is a standard Hibernate application with JPA Entities that map to database objects.
+To use JPAStreamer in your Quarkus application, add the JPAStreamer Quarkus extension to your build file. With Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.jpastreamer</groupId>
+ <artifactId>quarkus-jpastreamer</artifactId>
+ <version>3.0.3.Final</version>
+</dependency>You can also add the JPAStreamer dependency automatically with the following command:
+quarkus extension add 'io.quarkiverse.jpastreamer:quarkus-jpastreamer'Using the JPAStreamer Quarkus extension is no different from using the standard JPAStreamer library. Thus, the JPAStreamer User Guide is the most complete reference during development.
+Here is an example of how JPAStreamer can be instantiated with CDI Injection in a Hibernate application:
+@ApplicationScoped
+public class FilmRepository {
+
+ @Inject
+ JPAStreamer jpaStreamer; (1)
+
+ public String startsWitASortedByLength(short limit) {
+ return jpaStreamer.stream(Film.class) (2)
+ .filter(Film$.title.startsWith("A")) (3)
+ .sorted(Film$.length.reversed()) (4)
+ .limit(limit); (5)
+ }
+}
+| 1 | +Inject an instance of JPAStreamer | +
| 2 | +Selects the Film entity as the stream source | +
| 3 | +Only selects films with a title that starts with "A" | +
| 4 | +Sort the films by descending length (longest first) | +
| 5 | +Limit the results to a given number of films | +
When running JPAStreamer alongside Panache in a Quarkus Hibernate application, there are a few things to consider. The most recent version of JPAStreamer does not have support for Panache’s Active Record Pattern. This means the resulting JPAStreamer metamodel will most likely be erroneous. Therefore, we currently recommend Panache’s Repository Pattern.
+JPAStreamer can be injected in a Panache Repository as follows:
+@ApplicationScoped
+public class FilmRepository implements PanacheRepository<Film> {
+
+ @Inject
+ JPAStreamer jpaStreamer; (1)
+
+ public String startsWitASortedByLength(short limit) {
+ return jpaStreamer.stream(Film.class) (2)
+ .filter(Film$.title.startsWith("A")) (3)
+ .sorted(Film$.length.reversed()) (4)
+ .limit(limit); (5)
+ }
+}| 1 | +Inject an instance of JPAStreamer | +
| 2 | +Selects the Film entity as the stream source | +
| 3 | +Only selects films with a title that starts with "A" | +
| 4 | +Sort the films by descending length (longest first) | +
| 5 | +Limit the results to a given number of films | +
If you want to see JPAStreamer in a more complete context, check out the JPAStreamer demo repository here.
+The JPAStreamer Quarkus extension is released under the LGPL 2.1 License.
+The Quarkus JSch extensions brings native support for the JSch library.
+If you want to use this extension, you need to add the io.quarkiverse.jsch:quarkus-jsch extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.jsch</groupId>
+ <artifactId>quarkus-jsch</artifactId>
+ <version>3.0.7</version>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Kafka topics for incoming messages (comma separated if multiple topics). +
+
+Environment variable: |
+
+ string + |
++ |
+
+
+
+
+
+The Kafka topics for outgoing messages. +
+
+Environment variable: |
+
+ string + |
++ |
+
+
+
+
+
+The Kafka topic for outgoing messages for the given sink name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Dead letter Queue name +
+
+Environment variable: |
+String |
++ |
+
+
+
+
+
+Global Dead letter Queue to produce error messages note manage by the application +
+
+Environment variable: |
+String |
++ |
+
+
+
+
+
+Global Dead letter Queue maximum request size +
+
+Environment variable: |
+int |
+java.lang.Integer.MAX_VALUE |
+
+
+
+
+
+
+Enable the production of the error message in the global DLQ when the application can not manage the error. +
+
+Environment variable: |
+boolean |
+false |
+
+
+
+
+
+
+Kafka Streams Processor error strategy +
+
+Environment variable: |
+String |
+continue |
+
+
+
+
+
+
+Max number of retries. See microprofile doc. +
+
+Environment variable: |
+String |
+-1 |
+
+
+
+
+
+
+The delay between retries. See microprofile doc. +
+
+Environment variable: |
+long |
+0 |
+
+
+
+
+
+
+The unit for delay. Default milliseconds. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+The max duration. See microprofile doc. +
+
+Environment variable: |
+long |
+180000 |
+
+
+
+
+
+
+The unit for max duration. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+Jitter value to randomly vary retry delays for. See microprofile doc. +
+
+Environment variable: |
+long |
+200 |
+
+
+
+
+
+
+The delay unit for jitter. Default is milliseconds. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+The list of exception types that should trigger a retry. +Default is the provided io.quarkiverse.kafkastreamsprocessor.api.exception.RetryableException. +See microprofile doc. +
+
+Environment variable: |
+Exception class names |
+
|
+
+
+
+
+
+
+The list of exception types that should <i>not</i> trigger a retry. +Default is empty list +See microprofile doc. +
+
+Environment variable: |
+Exception class names |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+Configuration property |
+Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+A comma-separated list of topic names. +
+
+The micro-service will only be ready once all these topics are present in the Kafka cluster. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A unique identifier for this Kafka Streams application. +
+
+It is used as Kafka consumer group id, so multiple replicas of micro-service balance their partition workload. +
+
+Environment variable: |
+string |
+${quarkus.application.name} |
+
+
+
+
+
+
+It is the number of milliseconds a producer is willing to wait before sending a batch out. +
+
+Environment variable: |
+int |
+0 |
+
+
+
+
+
+
+The compression type for all data generated by the producer. +
+
+Environment variable: |
+Possible values: +none +gzip +snappy +lz4 +zstd |
+none |
+
This extension eases the implementation of event-driven architecture streaming microservices based on Kafka Streams’ Processor API. +It avoids Kafka Streams' users a lot of boilerplate code to have a dedicated topology and a proper production readiness (health, observability, error handling). +All that is left to develop is a simple Processor class. +The extension takes care of the rest.
+A streaming microservice has some requirements:
+Kafka Streams processors are not thread-safe, so a processor scope is @jakarta.enterprise.context.Dependent by default.
An incoming message, from an input topic, can be acknowledged only when it has been processed and its result message has been produced and stored in a Kafka output topic.
+If an incoming message could not be acknowledged (e.g: a microservice crash) then the incoming message will be redelivered (at-least-once guarantee).
+Incoming messages are processed in the order of arrival (ordering guarantee)
+There are currently several bootstraps or libraries that support writing stream processor-based applications on different broker technologies. +This extension’s processor solution is based on Kafka Streams' Processor API.
+Kafka Streams is an opensource client library that allows to write streaming applications.
+It is enabled by the quarkus-kafka-streams extension:
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-kafka-streams</artifactId>
+ <scope>runtime</scope>
+</dependency>Only one threading model is supported: 1 thread per topic-partition (see details)
+The number of partitions on the source topic determines up to how many threads can consume in parallel.
+Synchronous/blocking programing must be used to ensure guarantee of execution and ordering.
+| + + | ++There is a proposal under discussion for adding asynchronous processing to Kafka Streams. + | +
On top of Kafka Streams, the quarkus-kafka-streams-processor extension adds features to help you to write streaming microservices.
+The following dependency needs to be added:
+<project>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.kafkastreamsprocessor</groupId>
+ <artifactId>quarkus-kafka-streams-processor-bom</artifactId>
+ <version>${quarkus.kafkastreamsprocessor.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.kafkastreamsprocessor</groupId>
+ <artifactId>quarkus-kafka-streams-processor-api</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkiverse.kafkastreamsprocessor</groupId>
+ <artifactId>quarkus-kafka-streams-processor</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+</project>With the extension, it is expected to define an annotated Kafka Streams' Processor. +It is discovered as a CDI bean and instrumented by the Quarkus runtime. +The difference here with the fully fledged Kafka Streams Processor API is that there is no need to build a custom Topology for each new microservice. +It is built by the Quarkus runtime.
+Example:
+@Slf4j
+@Processor (1)
+public class PingProcessor extends ContextualProcessor<String, Ping, String, Ping> { (2)
+
+ @Override
+ public void process(Record<String, Ping> record) { (3)
+ resultMessage = countChars(record.value().getMessage());
+ Ping pong = Ping.newBuilder().setMessage(resultMessage).build();
+ context().forward(record.withValue(pong)); (4)
+ }
+
+ /**
+ * Counts the nb of characters and returns it as string.
+ */
+ private String countChars(String input) {
+ return String.valueOf(input.length());
+ }
+}| 1 | +Processors are beans managed by CDI, and as such need to be annotated with
+@io.quarkiverse.kafkastreamsprocessor.api.Processor so that any other CDI dependency may be injected.
+Kafka Streams' processors are not thread-safe, so a processor scope is @jakarta.enterprise.context.Dependent by default. |
+
| 2 | +Directly extend org.apache.kafka.streams.processor.api.ContextualProcessor, specifying the type of keys and values.
+For keys, only type String is supported.
+For values, see supported types. |
+
| 3 | +The process method is called for each incoming message.
+Any processing must be done synchronously. |
+
| 4 | +The forward method allows to produce an outgoing message.
+Internally Kafka Streams links the acknowledgment on the outgoing message with the commit of the associated incoming message. |
+
In short (see core concepts), in Kafka Streams a Topology is made of:
+Sources: 1 or more input topics
+Processors: a graph of 1 or more record handlers
+Stores (optional): for stateful use cases, the processor must be assigned one or multiple stores to keep the state.
+Sinks: 1 or more output topics
+The extension will automatically build the following topology:
+Scan for a CDI bean of type org.apache.kafka.streams.processor.api.Processor<KIn, VIn, KOut, VOut> (single processor).
+The deprecated type org.apache.kafka.streams.processor.Processor<K, V> is also supported for backward-compatibility.
Register a source for topics in kafkastreamsprocessor.input.topic, String key serializer and Protobuf value deserializer based on the declared type <V> of the processor.
Register as many sinks as topics listed in properties matching kafkastreamsprocessor.output.sinks.<sink>.topic, String key serializer and Protobuf value serializer.
+Sink name is taken from the properties name.
+If no kafkastreamsprocessor.output.sinks.<sink>.topic properties are defined and a single topic is defined in kafkastreamsprocessor.output.topic, a default sink is used.
Please consider two kind of properties:
+First class citizen properties are a set of properties prefixed with quarkus.kafka-streams.
+They are consumed by the Quarkus kafka-streams extension itself (used at build time and overridable, for some of them, at runtime).
In Kafka Streams Processor the following configuration keys are required:
+Refer to Kafka Streams extension’s configuration reference for a full list.
+All the properties used in the extension are recapped
+here
Due to the important number of properties that can be set to configure a Kafka Streams application, it’s impossible for Quarkus extension to know them all.
+But it’s possible to use pass-through properties in the configuration of your application, using the name of property but prefixed with kafka-streams.
# First citizen property
+quarkus.kafka-streams.bootstrap-servers=localhost:9092
+
+# Pass-through properties
+kafka-streams.producer.linger.ms=0
+kafka-streams.compression.type=gzipOverriding pass-through properties at runtime is a little bit hacky because you need to prefix the property with quarkus.
+Then, you can pass it as a Java system property.
| + + | ++Passing the property as an environment variable with Microprofile Config convention IS NOT working. + | +
Fo example, the possible way to override a pass-through property in a Kafka Streams Processor microservice would be to use the corresponding system property in the JVM commandline:
+-Dquarkus.kafka-streams.producer.linger.ms=50Data serialization refers to the process of converting complex data structures or objects into a format that can be easily transmitted over a network. +The extension’s processors support different serialization formats. +By analyzing the types of declared input and output payloads of the processor, it’s possible to infer the type of data to serialize and set up the correct serializer and deserializer.
+As of today, the extension’s processors support three first-class citizen formats and one customization feature:
+Other data format can be supported through the Serializer/Deserializer customization
+| + + | ++JSON is the default serialization format. +If the payload cannot be serialized to JSON, an error is thrown. +Depending on the Global DLQ Error management the message will be produced in the DLQ, and the incoming message will be acknowledged in the input topic. + | +
JSON is a first class citizen serialization format, the SDK will use JSON as default serialization format.
+In this example, we implement a processor working with a POJO as value type. +The POJO is read from kafka, or written to kafka, with the POJO’s JSON textual representation.
+@Slf4j
+@Processor (1)
+public class PojoProcessor extends ContextualProcessor<String, SamplePojo, String, SamplePojo> { (2)
+ @Override
+ public void process(Record<String, SamplePojo> record) { (3)
+ String reversedMsg = new StringBuilder(record.value().getStringField()).reverse().toString();
+ log.info("Received value {} sending back {} in response", record.value().getStringField(), reversedMsg);
+ SamplePojo pojo = new SamplePojo(reversedMsg, record.value().getNumericalField() + 37,
+ !record.value().getBooleanField());
+ context().forward(record.withValue(pojo)); (4)
+ }
+}| 1 | +Your Processor is declared with the annotation as for a regular processor. | +
| 2 | +The handled value type, is a class that can be serialized in JSON. | +
| 3 | +Same POJO value in the process() method. | +
| 4 | +Similarly, a POJO value can be sent down to the output topic. | +
In order to customize the JSON serialization, the SDK relies on the ObjectMapper customization from Quarkus
Protobuf values and String are the first class citizen data types in Kafka Streams Processor messaging.
+To ease development with Protobuf, various libraries support code generation from .proto files or
+OpenAPI descriptors, for instance openapi-generator.
The main problem with this approach is that certain details of the serialization logic are implementation-dependent and may have impacts on the usability of the generated APIs.
+One such case in the handling of optional elements, i.e. how to detect in business code if an element was absent, or present but with an empty value.
+There are multiple solutions to this problem, e.g.:
+Use built-in primitive types
+Use custom Nullable types instead of primitives
+Use built-in wrapper types instead of primitives
+Use optional in proto3
+The SDK provides the interface io.quarkiverse.kafkastreamsprocessor.api.configuration.ConfigurationCustomizer which allows you to specify the serializer and deserializer you need.
+You need to declare a bean implementing that interface.
It is available through the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.kafkastreamsprocessor</groupId>
+ <artifactId>quarkus-kafka-streams-processor-api</artifactId>
+</dependency>| + + | +
+Multiple customizers can be defined, and their execution order controlled through @Priority annotations.
+ |
+
In this example, we implement a processor working with a POJO as value type. +The POJO is read from kafka, or written to kafka, with a custom serialization format provided by sink and source serializer/deserializer that need to be known at build time.
+@Slf4j
+@Processor (1)
+public class PojoProcessor extends ContextualProcessor<String, SamplePojo, String, SamplePojo> { (2)
+ @Override
+ public void process(Record<String, SamplePojo> record) { (3)
+ String reversedMsg = new StringBuilder(record.value().getStringField()).reverse().toString();
+ log.info("Received value {} sending back {} in response", record.value().getStringField(), reversedMsg);
+ SamplePojo pojo = new SamplePojo(reversedMsg, record.value().getNumericalField() + 37,
+ !record.value().getBooleanField());
+ context().forward(record.withValue(pojo)); (4)
+ }
+}| 1 | +Your Processor is declared with the annotation as for a regular processor. | +
| 2 | +The handled value type, in this example, is a simple POJO, nothing fancy. | +
| 3 | +Same POJO value in the process() method. | +
| 4 | +Similarly, a POJO value can be sent down to the output topic. | +
@Dependent
+public class SampleConfigurationCustomizer implements ConfigurationCustomizer {
+ @Override
+ public void fillConfiguration(Configuration configuration) {
+ configuration.setSinkValueSerializer(new MyCustomSerializer<SamplePojo>());
+ configuration.setSourceValueSerde(new MyCustomSerde(SamplePojo));
+ }
+}The io.quarkiverse.kafkastreamsprocessor.api.configuration.ConfigurationCustomizer implementation provided sets the required Serializer and Deserializer into the method’s io.quarkiverse.kafkastreamsprocessor.api.configuration.Configuration object.
+In this example, we set a custom serialization through the usage of Kafka Serdes.
When an exception occurs while processing a record, different strategies have been defined:
+"continue" (default) : drop the message and continue processing
+"fail" (not implemented yet) : fail and stop processing more message
+"dead-letter-queue" : send the message to the DLQ and continue processing
+Such exception occurs are counted by a custom metric of this extension.
+If the dead-letter-queue strategy is chosen, the messages produced to the DLQ topics are counted.
In the case of a dead-letter-queue strategy, the DLQ topic is added to the readiness probe to ensure the ability to produce the poisonous message to this topic.
| + + | ++This local DLQ is meant only to store the poisonous message that the application could not consume successfully. +For error happening at production time, one can use a global DLQ defined for this purpose. + | +
When a microservice cannot produce to a downstream Kafka broker and that the error cannot be managed by the application, the message will be produced in a global DLQ.
The following value must be set in the application.properties file
+kafkastreamsprocessor.global-dlq.topic=<global-dlq-topic>By default, the maximum size for the message is java.lang.Integer.MAX_VALUE for the global DLQ.
+It can be modified with:
kafkastreamsprocessor.global-dlq.max-message-size=3000All the properties used in the extension are recapped
+here
For tracking purpose following headers are added to the record:
+dead-letter-reason: The reason of the failure if any (Exception message)
dead-letter-cause: The cause of the failure if any (Exception cause)
dead-letter-topic: The original topic of the record, in this case the output topic where production failed
dead-letter-partition: The original partition of the record
In order to improve resiliency and to avoid losing messages due to the temporary unavailability of an external system (database, HTTP endpoint, …), the Kafka Streams Processor SDK has a retry logic for the exceptions raised during the process of the message.
+| + + | ++The retry relies on the at-least-once guarantees of messaging: the processing must already support being called multiple times with the same message, and must make sure any external interaction is idempotent. + | +
A RetryDecorator has been introduced inside the topology definition.
+Its responsibility is to retry indefinitely the @io.quarkiverse.kafkastreamsprocessor.api.Processor retryableProcess method when a io.quarkiverse.kafkastreamsprocessor.api.exception.RetryableException is raised.
The default behavior can be overriden via the following configuration, ie:
+kafkastreamsprocessor.retry.max-retries=-1
+kafkastreamsprocessor.retry.retry-on=io.quarkiverse.kafkastreamsprocessor.api.exception.RetryableExceptionAs this implementation is based on Eclipse Microprofile Fault Tolerance it’s also possible to override some default policy (ie: maxDuration, jitter…) under the prefix kafkastreamsprocessor.retry..
You can also use the Fault Tolerance @org.eclipse.microprofile.faulttolerance.Retry annotation for some other logic in your code.
public class PingerService {
+ @Retry (1)
+ @Override
+ public Response ping(String message) {
+ }
+}| 1 | +Define the method to retry with org.eclipse.microprofile.faulttolerance.Retry annotation |
+
# Override max retry default value +io.quarkiverse.kafkastreamsprocessor.example.PingerService/Retry/maxRetries=3+
Users have to pay attention to some specificities of Kafka Streams metrics: some metrics have labels whose values are dynamic. +There’s a possible impact on Prometheus because this could drastically increase the amount of data needed to store the time series. +To understand how IDs label are computed, one can read the following documentation on KafkaStreams runtime information
+To mitigate the impact, it is a good practice to fix arbitrary prefix to dynamic labels but still, the dynamicity cannot be removed entirely.
+As an example, all Kafka metrics have in common the label client_id, the resulting computation of the label by the SDK is:
kafka_consumer_fetch_manager_records_consumed_total{client_id="application-name-StreamThread-1-consumer",kafka_version="3.6.3",topic="ping-events",} 1.0
+The metric client_id value is formed of :
quarkus-kafka-streams-processor-simple-sample which is the client id defined in kafka-streams.client.id config property
StreamThread-1-consumer which is computed by KafkaStreams and depends on the number of threads.
So it is a good practice to set kafka-streams.client.id with the name of the microservice.
This list includes the additional metrics, on top of the Kafka Streams and the general Kafka ones, that this extension instruments:
+| Micrometer metric name | +Type | +Description | +
|---|---|---|
kafkastreamsprocessor.processor.errors |
+Counter |
+Total number of errors encountered during Kafka Streams message processing |
+
| Micrometer metric name | +Type | +Description | +
|---|---|---|
kafkastreamsprocessor.punctuation.errors |
+Counter |
+The number of times a Punctuator’s execution failed with an exception since the start of the microservice. |
+
| Micrometer metric name | +Type | +Description | +
|---|---|---|
kafkastreamsprocessor.dlq.sent |
+Counter |
+The number of messages sent to DLQ. This metrics differs from the kafkastreamsprocessor.processor.errors in that the deserialization errors are taken into account. If no DLQ strategy is chosen, then this metric will be 0. Messages too large for the DLQ will be counted both in this metrics and in kafkastreamsprocessor.global.dlq.sent. |
+
kafkastreamsprocessor.global.dlq.sent |
+Counter |
+The number of messages sent to global DLQ. |
+
These two technologies can be used to create streaming microservices to be used in Event-Driven architecture applications.
+As explained in the Streaming processor introduction, a streaming microservice has some requirements:
+An incoming message, from an input topic, can be acknowledged only when it has been processed and its result message has been produced and stored in a Kafka output topic.
+If an incoming message could not be acknowledged (e.g: a microservice crash) then the incoming message will be redelivered (at-least-once guarantee).
+Incoming messages are processed in the order of arrival (ordering guarantee)
+In the Kafka Streams bootstrap, the guarantee of ordering from the source topic has a direct impact on the message consumption and the scalability model. +As explained in the Kafka Streams, the number of partitions of the source topic determines how many threads can consume in parallel.
+In other terms, for an input topic, it’s not possible to process more that x messages in parallel where x is the number of partitions of the source topic.
| + + | ++Starting asynchronous processing in a Kafka Streams microservice would lead to loss of messages: acknowledgement of the incoming messages will be de-synchronized from the production of messages once outgoing messages have been processed. + | +
Reactive messaging has a different architecture and threading model compared to Kafka Streams. +But by default, when processing messages it comes with the same guarantees seen above.
+However, it’s possible to alter the behaviour of the message processing with annotations to improve, in a drastic manner, the concurrency of a microservice. +The purpose of increasing concurrency is to be able to cope with streaming microservice that need to call slow remote APIs, this is the bridging from event-driven to service-oriented architecture.
+ @Incoming("ping-events") (1)
+ @Outgoing("pong-events") (2)
+ @Blocking(ordered = false) (3)
+ public Ping process(Ping ping) {
+ return api.remoteCall();
+ }| 1 | +@Incoming is declaring this method as a subscriber for the channel named ping-events |
+
| 2 | +@Outgoing is declaring this method as a producer for the channel named pong-events |
+
| 3 | +@io.smallrye.reactive.messaging.annotations.Blocking Indicates that this method is running out of the processing thread, inside a worker thread and the order of the messages is not important.
+Note that once the execution is finished the result is handled back to the processing thread. |
+
In Kafka Streams, performing asynchronous calls would lead to the possibility of messages not being redelivered. +What about the guarantee of delivery when processing concurrent messages in Reactive Messaging?
+It’s up to the acknowledgement policy to commit incoming messages when it has been processed concurrently. +The default strategy is throttled and guarantees at-least-once delivery
+| + + | +
+throttled keeps track of received messages and commits to the next offset after the latest acked message in sequence.
+This strategy guarantees at-least-once delivery even if the channel performs asynchronous processing.
+ |
+
When using the throttled strategy, the commit of the sequence of messages will happen only when all messages have been processed (ordered or not).
If the processing method does not return before reaching the throttled.unprocessed-record-max-age.ms timeout, the microservice will be considered as unhealthy and the liveness probe will fail and the microservice will be restarted.
+It means that, for example, if a remote API takes too long to respond for some queries, and its timeout is configured with a value above throttled.unprocessed-record-max-age.ms, then messages will be received again after the restart, acting like a poison pill.
Here’s a recap of the guarantees offered by the different way of processing messages.
+| Processor | +Guarantee of order | +At-least-once delivery | +Max concurrency | +
|---|---|---|---|
Default Kafka Streams |
+Yes |
+Yes |
+number of partitions |
+
Kafka Streams asynchronous |
+No |
+No |
+number of threads |
+
Default Reactive Messaging |
+Yes |
+Yes |
+number of partitions |
+
Reactive Messaging with @Blocking |
+Yes |
+Yes |
+number of partitions |
+
Reactive Messaging with @Blocking(order=false) |
+No |
+Yes |
+number of threads |
+
To support stateful requirements, Kafka Streams' Processor need to implement a State-Store.
+By default, no State-Store are linked to the io.quarkiverse.kafkastreamsprocessor.api.Processor but the application can override this configuration.
The SDK provides the interface io.quarkiverse.kafkastreamsprocessor.api.configuration.ConfigurationCustomizer which allows you to specify the State-Store you need.
+You need to declare a bean implementing that interface.
It is available through the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.kafkastreamsprocessor</groupId>
+ <artifactId>quarkus-kafka-streams-processor-api</artifactId>
+</dependency>| + + | +
+Multiple customizers can be defined, and their execution order controlled through @Priority annotations.
+ |
+
In this example, we implement a processor which is using a State-Store.
+@Slf4j
+@Processor (1)
+public class PingProcessor extends ContextualProcessor<String, Ping, String, Ping> {
+ private KeyValueStore<String, String> pingData;
+
+ @Override
+ public void init(ProcessorContext<String, Ping> context) {
+ super.init(context);
+ pingData = context.getStateStore("ping-data"); (2)
+ context.schedule(Duration.ofMillis(1L), PunctuationType.STREAM_TIME, new DuplicateValuePunctuator(pingData));
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public void process(Record<String, Ping> record) {
+ log.info("Process the message: {}", record.value().getMessage());
+
+ String previousValue = pingData.get(record.key());
+ pingData.put(record.key(), record.value().getMessage());
+
+ if (previousValue == null) {
+ context().forward(
+ record.withValue(Ping.newBuilder().setMessage("Store initialization OK for " + record.key()).build()));
+ } else {
+ context().forward(record.withValue(
+ Ping.newBuilder().setMessage("Previous value for " + record.key() + " is " + previousValue).build()));
+ }
+ }
+}| 1 | +Your Processor is declared with the annotation as for a regular processor. | +
| 2 | +The definition and initialization of your state store. | +
@Dependent
+public class SampleConfigurationCustomizer implements ConfigurationCustomizer {
+ @Override
+ public void fillConfiguration(Configuration configuration) {
+ List<StoreConfiguration> storeConfigurations = new ArrayList<>();
+ // Add a key value store for indexes
+ StoreBuilder<KeyValueStore<String, String>> storeBuilder = Stores.keyValueStoreBuilder(
+ Stores.persistentKeyValueStore("ping-data"),
+ Serdes.String(),
+ Serdes.String());
+ storeConfigurations.add(new StoreConfiguration(storeBuilder));
+ configuration.setStoreConfigurations(storeConfigurations);
+ }
+}The io.quarkiverse.kafkastreamsprocessor.api.configuration.ConfigurationCustomizer implementation provided sets the required State-Store configurations into the method’s
+io.quarkiverse.kafkastreamsprocessor.api.configuration.Configuration object.
+In this example a ping-data key/value store has been created.
Kafka Streams allows you to define Punctuator that are sort of scheduled tasks that Kafka Streams triggers (Kafka Streams documentation). +One key issue with Punctuators is that they do not support Exceptions:
+a checked Exception cannot be thrown as the method signature does not allow it
+a RuntimeException because Kafka Streams does not catch it. +It basically crashes your whole microservice.
+To work around the latter point and increase stability, the quarkus-kafka-streams-processor extension wraps a Punctuator before it is added in Kafka Streams to catch the RuntimeException and log an error instead.
+Exceptions are also counted with a dedicated metric.
The extension proposes some capabilities to customize more finely the behaviour of the different layers of decoration in addition to the ones that this extension brings to the table.
+The following decoration layer is already extensively used in this extension’s source code and allows to use composition around the main processor class you have to define. +Example of a new decorator:
+@Decorator (1)
+@Priority(150) (2)
+public class ProcessorDecorator<KIn, VIn, KOut, VOut> implements Processor<KIn, VIn, KOut, VOut> { (3)
+ @lombok.experimental.Delegate(excludes = Excludes.class)
+ private final Processor<KIn, VIn, KOut, VOut> delegate; (4)
+
+ private final MyBean bean;
+
+ @Inject
+ public TracingDecorator(@Delegate Processor<KIn, VIn, KOut, VOut> delegate, MyBean bean) { (5)
+ this.delegate = delegate;
+ this.bean = bean;
+ }
+
+ @Override
+ public void process(Record<KIn, VIn> record) { (6)
+ // use bean before
+ delegate.process(record);
+ // use bean after
+ }
+
+ private interface Excludes {
+ <KIn, VIn> void process(Record<KIn, VIn> record);
+ }
+}| 1 | +Decorator annotation to profit from the decorator feature of CDI | +
| 2 | +Force the instantiation of the decorator with the Priority annotation.
+Indeed, otherwise the decorator is not taken into account by Quarkus.
+The priority is to be set based on the priorities of the existing decorators which are:
+
+ ProcessorDecoratorPriorities.java
+
+
+ |
+
| 3 | +The decorator should have the same generics declaration <KIn, VIn, KOut, VOut> as the Processor<KIn, VIn, KOut, VOut> interface that it implements |
+
| 4 | +Delegate reference to use when decorating methods.
+It is annotated with lombok’s Delegate annotation to generate
+passthrough decorated methods that this Decorator class won’t decorate.
+The selection is done through a blacklist of method signatures gathered in a private Excludes interface declared at the end of the class. |
+
| 5 | +Injection constructor which must have a delegate argument annotated with the Delegate annotation from CDI.
+You can also, as a regular CDI bean, inject any another CDI bean reference to be used in this decorator. |
+
| 6 | +Example of decorated method, here the main process method of Processor API of Kafka Streams. |
+
Such a decorator will automatically been taken into account by CDI through the combination of Decorator and Priority annotations.
+The priority will control at which point your decorator will be called among all other decorators.
Kafka Streams already has the notion of a ProducerInterceptor. +But as the rest of Kafka Streams SPI, it is based on a class name and a default constructor for instantiation. +It does not support CDI resolution.
+This is why this extension’s API defines a ProducerOnSendInterceptor interface that is instrumentated through CDI.
+Example of usage:
@ApplicationScoped (1)
+public class HeaderAddingProducerInterceptor implements ProducerOnSendInterceptor { (2)
+ @Override
+ public int priority() { (3)
+ return 200;
+ }
+
+ @Override
+ public ProducerRecord<byte[], byte[]> onSend(ProducerRecord<byte[], byte[]> producerRecord) { (4)
+ producerRecord.headers().remove("header");
+ producerRecord.headers().add("header", "headervalue".getBytes(StandardCharsets.UTF_8));
+ return producerRecord;
+ }
+}| 1 | +Producer interceptors are discovered by CDI by the ApplicationScoped annotation |
+
| 2 | +The interceptor class should extend ProducerOnSendInterceptor.
+ProducerOnSendInterceptor extends ProducerInterceptor<byte[], byte[]> and overrides some of its methods with default implementations to exempt their forced implementations further down the line. |
+
| 3 | +This is not mandatory.
+But it allows to control in which order multiple interceptor that would defined are called.
+The default priority is 100. |
+
| 4 | +The intercepted method call which allow to modify the ProducerRecord before it is finally sent to Kafka.
+In this example, we replace a header named header with another value headervalue. |
+
A Kafka Streams Punctuator is a callback to use with +ProcessorContext#schedule(…). +It allows to schedule a periodic operation, depending on batch of incoming messages or on a timely manner.
+We propose in the extension a way to decorate any Punctuator a microservice would create.
| + + | +
+The extension does not give the capability to narrow the decoration on only a given instance or class of Punctuator.
+ |
+
The decoration happens through the implementation of a DecoratedPunctuator interface with a bit the same idea as for the Processor decorator: usage of the CDI Decorator feature.
+Example of decoration:
@Decorator (1)
+@Priority(150) (2)
+public class CdiRequestContextPunctuatorDecorator implements DecoratedPunctuator { (3)
+ @lombok.experimental.Delegate(excludes = Excludes.class)
+ private final DecoratedPunctuator delegate; (4)
+
+ private final MyBean myBean;
+
+ @Inject
+ public CdiRequestContextPunctuatorDecorator(@Delegate DecoratedPunctuator delegate, MyBean myBean) { (5)
+ this.delegate = delegate;
+ this.myBean = myBean;
+ }
+
+ @Override
+ public void punctuate(long timestamp) { (6)
+ // use before punctuate the myBean reference
+ delegate.punctuate(timestamp);
+ // use after punctuate the myBean reference
+ }
+
+ private interface Excludes {
+ void punctuate(long timestamp);
+ }
+}| 1 | +Decorator annotation to profit from the decorator feature of CDI | +
| 2 | +Force the instantiation of the decorator with the Priority annotation.
+Indeed, otherwise the decorator is not taken into account by Quarkus.
+The priority is to be set based on the priorities of the existing decorators which are:
+
+ PunctuatorDecoratorPriorities.java
+
+
+ |
+
| 3 | +The decorator should extend the DecoratedPunctuator interface defined by this extension.
+It won’t be considered otherwise. |
+
| 4 | +Delegate reference to use when decorating methods.
+It is annotated with lombok’s Delegate
+annotation to generate passthrough decorated methods that this Decorator class won’t decorate.
+The selection is done through a blacklist of method signatures gathered in a private Excludes interface declared at the end of the class. |
+
| 5 | +Injection constructor which must have a delegate argument annotated with the Delegate annotation from CDI.
+Is showcased here also the injection of another bean to be used in this decorator. |
+
| 6 | +Example of decorated method, here the main punctuate method of the Punctuator interface. |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The Kafka topics for incoming messages (comma separated if multiple topics). +
+
+Environment variable: |
+
+ string + |
++ |
+
+
+
+
+
+The Kafka topics for outgoing messages. +
+
+Environment variable: |
+
+ string + |
++ |
+
+
+
+
+
+The Kafka topic for outgoing messages for the given sink name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Dead letter Queue name +
+
+Environment variable: |
+String |
++ |
+
+
+
+
+
+Global Dead letter Queue to produce error messages note manage by the application +
+
+Environment variable: |
+String |
++ |
+
+
+
+
+
+Global Dead letter Queue maximum request size +
+
+Environment variable: |
+int |
+java.lang.Integer.MAX_VALUE |
+
+
+
+
+
+
+Enable the production of the error message in the global DLQ when the application can not manage the error. +
+
+Environment variable: |
+boolean |
+false |
+
+
+
+
+
+
+Kafka Streams Processor error strategy +
+
+Environment variable: |
+String |
+continue |
+
+
+
+
+
+
+Max number of retries. See microprofile doc. +
+
+Environment variable: |
+String |
+-1 |
+
+
+
+
+
+
+The delay between retries. See microprofile doc. +
+
+Environment variable: |
+long |
+0 |
+
+
+
+
+
+
+The unit for delay. Default milliseconds. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+The max duration. See microprofile doc. +
+
+Environment variable: |
+long |
+180000 |
+
+
+
+
+
+
+The unit for max duration. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+Jitter value to randomly vary retry delays for. See microprofile doc. +
+
+Environment variable: |
+long |
+200 |
+
+
+
+
+
+
+The delay unit for jitter. Default is milliseconds. See microprofile doc. +
+
+Environment variable: |
+ChronoUnit |
+MILLIS |
+
+
+
+
+
+
+The list of exception types that should trigger a retry. +Default is the provided io.quarkiverse.kafkastreamsprocessor.api.exception.RetryableException. +See microprofile doc. +
+
+Environment variable: |
+Exception class names |
+
|
+
+
+
+
+
+
+The list of exception types that should <i>not</i> trigger a retry. +Default is empty list +See microprofile doc. +
+
+Environment variable: |
+Exception class names |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+Configuration property |
+Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+A comma-separated list of topic names. +
+
+The micro-service will only be ready once all these topics are present in the Kafka cluster. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+A unique identifier for this Kafka Streams application. +
+
+It is used as Kafka consumer group id, so multiple replicas of micro-service balance their partition workload. +
+
+Environment variable: |
+string |
+${quarkus.application.name} |
+
+
+
+
+
+
+It is the number of milliseconds a producer is willing to wait before sending a batch out. +
+
+Environment variable: |
+int |
+0 |
+
+
+
+
+
+
+The compression type for all data generated by the producer. +
+
+Environment variable: |
+Possible values: +none +gzip +snappy +lz4 +zstd |
+none |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+JAAS Login context name. If it is not set then the JAAS configuration will be created automatically otherwise a JAAS configuration file must be available and contain an entry matching its value - in this case use |
+string |
++ |
+
+
+
+
+
+Specifies if a JAAS configuration |
+boolean |
+
|
+
+
+
+
+
+
+User principal keytab file path which will be used to set a JAAS configuration |
+string |
++ |
+
+
+
+
+
+Specifies if an |
+boolean |
+
|
+
+
+
+
+
+
+Kerberos Service Principal Name. + |
+string |
+
|
+
+
+
+
+
+
+Kerberos User Principal Name. It is a required property. + |
+string |
++ |
+
+
+
+
+
+Kerberos User Principal Realm Name. If this property is set then it will be added to the user principal name, for example, |
+string |
++ |
+
+
+
+
+
+Kerberos User Principal Password. Set this property only if using the |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine if the Kerberos extension is enabled + |
+boolean |
+
|
+
+
+
+
+
+
+JAAS Login context name. If it is not set then the JAAS configuration will be created automatically otherwise a JAAS configuration file must be available and contain an entry matching its value - in this case use |
+string |
++ |
+
+
+
+
+
+Specifies if a JAAS configuration |
+boolean |
+
|
+
+
+
+
+
+
+Service principal keytab file path which will be used to set a JAAS configuration |
+string |
++ |
+
+
+
+
+
+Specifies if an |
+boolean |
+
|
+
+
+
+
+
+
+Kerberos Service Principal Name. If this property is not set then the service principal name will be calculated by concatenating |
+string |
++ |
+
+
+
+
+
+Kerberos Service Principal Realm Name. If this property is set then it will be added to the service principal name, for example, |
+string |
++ |
+
+
+
+
+
+Kerberos Service Principal Password. Set this property only if using the |
+string |
++ |
Kerberos is a network authentication protocol.
+Client acquires a service ticket from Kerberos Key Distribution Center (KDC) and submits it to an application which will verify it with its service principal against KDC and grant an access if the verification has been successful.
This extension supports Kerberos version 5 with the HTTP Negotiate authentication scheme which is based on the Simple And Protected Negotiate Mechanism (SPNEGO) and the Generic Security Services Application Program Interface (GSSAPI).
If you want to use this extension, you need to add the io.quarkiverse.kerberos:quarkus-kerberos extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.kerberos</groupId>
+ <artifactId>quarkus-kerberos</artifactId>
+</dependency>First you have to prepare your Kerberos environment. The description of how it should be done securely is out of scope of this document, please follow the deployment specfic policies.
+However, here is a sequence of steps you can try for a quick test:
+Install Kerberos:
+Fedora: [root@server ~]# yum install krb5-server krb5-libs krb5-workstation.
+If you do not use Fedora then follow the OS specific instructions.
Edit /etc/krb5.conf - either uncomment the configuration related to EXAMPLE.COM or add a new realm, example, QUARKUS.COM. Make sure the realm’s kdc and admin_server properties point to localhost.
Create the database: kdb5_util create -s.
Start kadmin.local and add principals and keytabs in its command line:
User principal:
+addprinc bob
+(use password bob or whatever you prefer)
Service principal:
+addprinc HTTP/localhost
+(use password service or whatever you prefer)
Add a keytab for the service principal:
+ktadd -k /etc/service.keytab HTTP/localhost
and press q to exit.
To make it easier to test you may need to do chmod og+r /etc/*.keytab since you are creating them as a root but you’ll run Quarkus App without the root permissions.
start KDC: systemctl start krb5kdc.service and systemctl start kadmin.service
Prepare a service ticket for bob: kinit bob
Create your Quarkus application which will use this extension. Lets assume it has a JAX-RS method with a /api/users/me path and which returns a user name. Update its application.properties to point to the service principal key tab: quarkus.kerberos.keytab-path=/etc/service.keytab.
Build and start the application and test it:
+curl --negotiate -u bob@EXAMPLE.COM -v http://localhost:8080/api/users/me
It should return bob.
In many cases all you will need is to ensure the service principal password or its keytab is accessible. If you have created a keytab file then use quarkus.kerberos.keytab-path to point to it - using the keytab is recommended.
If you haven’t created a keytab just yet then you can register a custom callback handler, for example:
+import jakarta.enterprise.context.ApplicationScoped;
+
+import javax.security.auth.callback.Callback;
+import javax.security.auth.callback.CallbackHandler;
+import javax.security.auth.callback.NameCallback;
+import javax.security.auth.callback.PasswordCallback;
+import javax.security.auth.callback.UnsupportedCallbackException;
+
+import io.quarkiverse.kerberos.KerberosCallbackHandler;
+
+@ApplicationScoped
+public class UsernamePasswordCallbackHandler implements KerberosCallbackHandler {
+ private final String username;
+ private final char[] password;
+
+ private UsernamePasswordCallbackHandler(final String username, final char[] password) {
+ this.username = username;
+ this.password = password;
+ }
+
+ @Override
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ for (Callback current : callbacks) {
+ if (current instanceof NameCallback) {
+ NameCallback ncb = (NameCallback) current;
+ ncb.setName(username);
+ } else if (current instanceof PasswordCallback) {
+ PasswordCallback pcb = (PasswordCallback) current;
+ pcb.setPassword(password);
+ } else {
+ throw new UnsupportedCallbackException(current);
+ }
+ }
+ }
+ }
+}Note io.quarkiverse.kerberos.KerberosCallbackHandler extends javax.security.auth.callback.Callback - it only acts as a marker interface for this extension to avoid having unrelated CallbackHandlers injected.
The service principal name itself is calculated from the current HTTP Host header, for example, given Host: localhost:8080 the name will be calculated as HTTP/localhost.
+If necessay it can be customized with quarkus.kerberos.service-principal-name.
If the KDC configuration has no default realm configured then a service principal realm can be set with quarkus.kerberos.service-principal-realm.
You can access a user principal in the service code once the authentication has been completed, for example:
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+
+import io.quarkiverse.kerberos.KerberosPrincipal;
+
+import io.quarkus.security.Authenticated;
+import io.quarkus.security.identity.SecurityIdentity;
+
+@Path("/api/users")
+@Authenticated
+public class UsersResource {
+
+ @Inject
+ SecurityIdentity identity;
+ @Inject
+ KerberosPrincipal kerberosPrincipal;
+
+ @GET
+ @Path("/me")
+ @Produces("text/plain")
+ public String me() {
+ return identity.getPrincipal().getName();
+ }
+}For example, given bob@EXAMPLE.COM, a simple bob name will be returned.
+You can cast Principal to io.quarkiverse.kerberos.KerberosPrincipal or inject it directly and get a full bob@EXAMPLE.COM (or bob/admin@EXAMPLE.COM) name and the realm part of the name, EXAMPLE.COM. If the principal name contains an instance qualifier such as bob/admin then KerberosPrincipal will return admin as the role name.
The extension will generate a JAAS Login Configuration by default.
+However, if you have an existing JAAS Login Configuration then set quarkus.kerberos.login-context-name to point to a JAAS Configuration entry and use a `java.security.auth.login.config' system property to point to the file containing this configuration entry.
The extension will use javax.security.auth.login.LoginContext to create a Subject representing a service principal, using the auto-generated or external JAAS Login Configuration as well as the registered callback unless a keytab is used.
You can customize this process by registering a custom io.quarkiverse.kerberos.ServicePrincipalSubjectFactory:
import jakarta.enterprise.context.ApplicationScoped;
+import javax.security.auth.Subject;
+import io.quarkiverse.kerberos.ServicePrincipalSubjectFactory;
+
+@ApplicationScoped
+public class CustomServicePrincipalSubjectFactory implements ServicePrincipalSubjectFactory {
+ @Override
+ public Subject getSubjectForServicePrincipal(String servicePrincipalName) {
+ ....
+ }
+ }
+}Quarkus Dev Services support the automatic provisioning of unconfigured services in development and test mode.
+This extension provides Dev Services for Kerberos which uses a Kerberos Docker image.
Start your application in a Dev Mode with mvn quarkus:dev.
You will see in the console something similar to:
+$ mvn quarkus:dev
+
+2021-10-07 10:56:18,276 INFO [🐳 [gcavalcante8808/krb5-server:latest]] (build-18) Creating container for image: gcavalcante8808/krb5-server:latest
+...
+2021-10-07 10:56:18,881 INFO [🐳 [gcavalcante8808/krb5-server:latest]] (build-18) Container gcavalcante8808/krb5-server:latest started in PT0.621235S
+...
+Initializing database '/var/lib/krb5kdc/principal' for realm 'EXAMPLE.COM',
+...
+Principal "admin/admin@EXAMPLE.COM" created.
+
+2021-10-07 10:56:19,149 INFO [io.qua.ker.dep.dev.KerberosDevServicesProcessor] (build-18) Kerberos configuration file path: /tmp/devservices-krb516887219905674106017.conf, mapped KDC port: 32771, mapped admin server port: 32769
+2021-10-07 10:56:19,152 INFO [io.qua.ker.dep.dev.KerberosDevServicesProcessor] (build-18) Dev Services for Kerberos started.HTTP/localhost service principal (with a servicepwd password) as well as alice and bob user principals (with passwords equal to their names) are created by default in a default EXAMPLE.COM realm.
Different users can be set with a quarkus.kerberos.devservices.users map property, for example, quarkus.kerberos.devservices.users.jduke=theduke, etc.
+The service principal can be customized with quarkus.kerberos.service-principal-name, its password - with quarkus.kerberos.service-principal-password, the realm - with either quarkus.kerberos.devservices.realm or quarkus.kerberos.service-principal-realm.
Now you can set a KRB5_CONFIG environment property pointing to the file such as /tmp/devservices-krb516887219905674106017.conf, use kinit to prepare a ticket granting ticket for a specific user and use the browser or curl to test the endpoint. Dedicated Dev UI for Dev Services For Kerberos might be offered in the future as well.
Please enable a trace logging level for io.quarkiverse.kerberos.runtime.KerberosIdentityProvider in order to see the log messages reported by this IdentityProvider:
quarkus.log.category."io.quarkiverse.kerberos.runtime.KerberosIdentityProvider".level=TRACE
+quarkus.log.category."io.quarkiverse.kerberos.runtime.KerberosIdentityProvider".min-level=TRACEAlso, if you would like to see the debug messages reported by the Kerberos system itself then make sure that quarkus.kerberos.debug is set to true if the JAAS context is auto-generated or debug is set to true in a custom JAAS context file.
You can test this extension with Dev Services for Kerberos or Apache Directory Service.
In both cases add the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.kerberos</groupId>
+ <artifactId>quarkus-kerberos-test-util</artifactId>
+ <version>${version.quarkus.kerberos.test.util}</version>
+ <scope>test</scope>
+</dependency>You can write the test code like this when using Dev Services:
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.hamcrest.Matchers;
+import org.junit.jupiter.api.Test;
+
+import io.quarkiverse.kerberos.test.utils.KerberosTestClient;
+import io.restassured.RestAssured;
+
+public class SpnegoAuthenticationTestCase {
+ public static final String WWW_AUTHENTICATE = "WWW-Authenticate";
+ public static final String NEGOTIATE = "Negotiate";
+
+ KerberosTestClient kerberosTestClient = new KerberosTestClient();
+
+ @Test
+ public void testSpnegoSuccess() throws Exception {
+
+ var header = RestAssured.get("/identity")
+ .then().statusCode(401).extract().header(WWW_AUTHENTICATE);
+ assertEquals(NEGOTIATE, header);
+
+ var result = kerberosTestClient.get("/identity", "alice", "alice");
+ result.statusCode(200).body(Matchers.is("alice"));
+ }
+}You can write the same test code you can do with Dev Services for Kerberos but you’ll also need to add a test resource initializing Apache DS:
import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import org.hamcrest.Matchers;
+import org.junit.jupiter.api.Test;
+
+import io.quarkiverse.kerberos.test.utils.KerberosKDCTestResource;
+import io.quarkiverse.kerberos.test.utils.KerberosTestClient;
+import io.quarkus.test.common.QuarkusTestResource;
+import io.restassured.RestAssured;
+
+@QuarkusTestResource(KerberosKDCTestResource.class)
+public class SpnegoAuthenticationTestCase {
+ public static final String WWW_AUTHENTICATE = "WWW-Authenticate";
+ public static final String NEGOTIATE = "Negotiate";
+
+ KerberosTestClient kerberosTestClient = new KerberosTestClient();
+
+ @Test
+ public void testSpnegoSuccess() throws Exception {
+
+ var header = RestAssured.get("/identity")
+ .then().statusCode(401).extract().header(WWW_AUTHENTICATE);
+ assertEquals(NEGOTIATE, header);
+
+ var result = kerberosTestClient.get("/identity", "jduke", "theduke");
+ result.statusCode(200).body(Matchers.is("jduke"));
+ }
+}At the moment only a single jduke user is supported when testing with Apache DS and Dev Services for Kerberos have to be disabled: quarkus.kerberos.devservices.enabled=false.
You can also configure your browser such as Firefox to use Negotiate Mechanism.
+A good summary is provided here.
+For example, if you run your application on the localhost then add localhost (without a port) as the only value to the Firefox about:config/network.negotiate-auth.trusted-uris property.
Next, use kinit to create a ticket granting ticket (TGT) for a selected user principal for the browser to use this TGT. Make sure kinit sees the same Kerberos KDC configuration which the browser will see for both kinit (and other Kerberos tools) and the browser to work with the same Kerberos KDC instance.
If the default Kerberos KDC configuration at /etc/krb5.conf is used then you don’t even need to restart a browser. If a custom Kerberos KDC configuration is used by kinit then point to it with KRB5_CONFIG and either update ~/.bashrc or launch the browser from the shell where KRB5_CONFIG is set.
Now open your browser and access the endpoint - the browser will do the negotiation using the created TGT without asking for a user name and password.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine if the Kerberos extension is enabled + |
+boolean |
+
|
+
+
+
+
+
+
+JAAS Login context name. If it is not set then the JAAS configuration will be created automatically otherwise a JAAS configuration file must be available and contain an entry matching its value - in this case use |
+string |
++ |
+
+
+
+
+
+Specifies if a JAAS configuration |
+boolean |
+
|
+
+
+
+
+
+
+Service principal keytab file path which will be used to set a JAAS configuration |
+string |
++ |
+
+
+
+
+
+Specifies if an |
+boolean |
+
|
+
+
+
+
+
+
+Kerberos Service Principal Name. If this property is not set then the service principal name will be calculated by concatenating |
+string |
++ |
+
+
+
+
+
+Kerberos Service Principal Realm Name. If this property is set then it will be added to the service principal name, for example, |
+string |
++ |
+
+
+
+
+
+Kerberos Service Principal Password. Set this property only if using the |
+string |
++ |
In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.kerberos</groupId>
+ <artifactId>quarkus-kerberos-client</artifactId>
+</dependency>This module provides the utility code which can be used to add Kerberos service tickets as HTTP Authorization Negotiate scheme values. It can be done with the help of the JAX-RS KerberosClientRequestFilter or directly in the application code.
Using this module can be useful when a Quarkus endpoint has to make an outbound call to a remote service requiring Kerberos Negotiate Authentication.
For example, lets assume your FrontendService application has to call to the remote IdentityService:
import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import io.quarkiverse.kerberos.KerberosPrincipal;
+import io.quarkus.security.Authenticated;
+import io.quarkus.security.identity.SecurityIdentity;
+
+@Path("identity")
+@Authenticated
+public class IdentityService {
+
+ @Inject
+ SecurityIdentity securityIdentity;
+
+ @Inject
+ KerberosPrincipal kerberosPrincipal;
+
+ @GET
+ public String getIdentity() {
+ return securityIdentity.getPrincipal().getName() + " " + kerberosPrincipal.getFullName() + " "
+ + kerberosPrincipal.getRealm();
+ }
+}Next you can implement FrontendService.
First MP RestClient IdentityServiceClient interface has to be created and KerberosClientRequestFilter registered:
package io.quarkiverse.kerberos.it;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import io.quarkiverse.kerberos.client.KerberosClientRequestFilter;
+
+@RegisterRestClient
+@RegisterProvider(KerberosClientRequestFilter.class)
+@Path("/")
+public interface IdentityServiceClientWithFilter {
+
+ @GET
+ String getIdentity();
+}Now FrontendService will look like this
import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+@Path("frontend")
+public class FrontendResource {
+
+ @Inject
+ @RestClient
+ IdentityServiceClientWithFilter identityServiceClientWithFilter;
+
+ @GET
+ @Path("with-filter")
+ public String getIdentityWithSimpleNegotiationInFilter() {
+ return identityServiceClientWithFilter.getIdentity();
+ }
+}Configure the application like this:
+io.quarkiverse.kerberos.it.IdentityServiceClientWithFilter/mp-rest/url=http://localhost:8081/identity
+
+kerberos-client.user-principal-name=jduke
+kerberos-client.user-principal-password=thedukeIf necessary you can use KerberosClientSupport directly in the application, for example:
import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+import io.quarkiverse.kerberos.client.KerberosClientSupport;
+
+@Path("frontend")
+public class FrontendResource {
+ private static final String NEGOTIATE = "Negotiate";
+
+ @Inject
+ @RestClient
+ IdentityServiceClient identityServiceClient;
+
+ @Inject
+ KerberosClientSupport kerberosClientSupport;
+
+ @GET
+ @Path("with-simple-negotiation")
+ public String getIdentityWithSimpleSimpleNegotiation() throws Exception {
+ return identityServiceClient.getIdentity(NEGOTIATE + " " + kerberosClientSupport.getServiceTicket());
+ }
+}Note IdentityServiceClient does not have KerberosClientRequestFilter registered but instead has a HeaderParam:
import jakarta.ws.rs.GET;
+import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.Path;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+@RegisterRestClient
+@Path("/")
+public interface IdentityServiceClient {
+
+ @GET
+ String getIdentity(@HeaderParam("Authorization") String serviceTicket);
+}Note that a single step Negotiation is shown in both KerberosClientRequestFilter and KerberosClientSupport sections.
Single step Negotiation should work for many practical cases however the Negotiate protocol may involve more than one exchange between the client and the server before a service ticket can be acquired. If you have to deal with such cases then you can write the application code as follows:
import java.security.PrivilegedExceptionAction;
+import java.util.Base64;
+
+import jakarta.inject.Inject;
+import javax.security.auth.Subject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.NotAuthorizedException;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.HttpHeaders;
+
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.ietf.jgss.GSSContext;
+
+import io.quarkiverse.kerberos.client.KerberosClientSupport;
+
+@Path("frontend")
+public class FrontendResource {
+ private static final String NEGOTIATE = "Negotiate";
+
+ @Inject
+ @RestClient
+ IdentityServiceClient identityServiceClient;
+
+ @Inject
+ KerberosClientSupport kerberosClientSupport;
+
+ @GET
+ @Path("with-multi-step-negotiation")
+ public String getIdentityWithMultiStepNegotiation() throws Exception {
+ return Subject.doAs(kerberosClientSupport.getUserPrincipalSubject(), new IdentityServiceAction());
+ }
+
+ private class IdentityServiceAction implements PrivilegedExceptionAction<String> {
+
+ @Override
+ public String run() throws Exception {
+ GSSContext serviceContext = kerberosClientSupport.createServiceContext();
+
+ byte[] tokenBytes = new byte[0];
+
+ while (!serviceContext.isEstablished()) {
+ try {
+ return identityServiceClient.getIdentity(
+ NEGOTIATE + " " + kerberosClientSupport.getNegotiateToken(serviceContext, tokenBytes));
+ } catch (NotAuthorizedException ex) {
+ String header = ex.getResponse().getHeaderString(HttpHeaders.WWW_AUTHENTICATE);
+ if (header != null && header.length() > NEGOTIATE.length() + 1) {
+ tokenBytes = Base64.getDecoder().decode(header.substring(NEGOTIATE.length() + 1));
+ continue;
+ }
+ throw ex;
+ }
+ }
+ throw new RuntimeException("Kerberos ticket can not be created");
+ }
+ };
+}Note if the remote service requires the negotiation to continue then a new token is acquired and a new request is made to the remote service.
+Configuring KerberosClientSupport is similar to the way Kerberos support is configured on the server, see the configuration reference below.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+JAAS Login context name. If it is not set then the JAAS configuration will be created automatically otherwise a JAAS configuration file must be available and contain an entry matching its value - in this case use |
+string |
++ |
+
+
+
+
+
+Specifies if a JAAS configuration |
+boolean |
+
|
+
+
+
+
+
+
+User principal keytab file path which will be used to set a JAAS configuration |
+string |
++ |
+
+
+
+
+
+Specifies if an |
+boolean |
+
|
+
+
+
+
+
+
+Kerberos Service Principal Name. + |
+string |
+
|
+
+
+
+
+
+
+Kerberos User Principal Name. It is a required property. + |
+string |
++ |
+
+
+
+
+
+Kerberos User Principal Realm Name. If this property is set then it will be added to the user principal name, for example, |
+string |
++ |
+
+
+
+
+
+Kerberos User Principal Password. Set this property only if using the |
+string |
++ |
With Kiota you can plug in any authentication mechanism provided by the underlying HTTP client.
+For example, when using the VertX HTTP client you can configure a Bearer Access Token with OIDC like:
+OAuth2Options options =
+ new OAuth2Options()
+ .setFlow(OAuth2FlowType.CLIENT)
+ .setClientId(CLIENT_ID)
+ .setTokenPath(keycloakUrl + "token")
+ .setClientSecret(CLIENT_SECRET);
+
+OAuth2Auth oAuth2Auth = OAuth2Auth.create(vertx, options);
+
+Oauth2Credentials oauth2Credentials = new Oauth2Credentials();
+
+OAuth2WebClient oAuth2WebClient =
+ OAuth2WebClient.create(WebClient.create(vertx), oAuth2Auth)
+ .withCredentials(oauth2Credentials);
+
+var adapter = new VertXRequestAdapter(oAuth2WebClient);First of all you need to add or update the quarkus-maven-plugin configuration with the following:
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Add the extension dependency to your project’s pom.xml file:
<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>quarkus-kiota</artifactId>
+ <version>{project.version}</version>
+</dependency>Now, create a new folder named openapi under src/main/ and add OpenAPI spec files there. Supported file extensions are: json, yaml, yml.
To fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.kiota.petstore.json.package-name=com.mycompanyIf a base package name is not provided, it will be used the default io.apisdk.<filename>. For example, io.apisdk.petstore.json.
You can customize the name of Api Client class using the following property:
+quarkus.kiota.petstore.json.class-name=MyApiClientNow add the additional dependencies to compile the project:
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-abstractions</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>kiota-http-vertx</artifactId> <!-- alternatively <artifactId>kiota-http-jdk</artifactId> -->
+ <version>{version}</version>
+</dependency>
+<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>kiota-serialization-jackson-quarkus</artifactId>
+ <version>{version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-text</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-form</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-multipart</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>jakarta.annotation</groupId>
+ <artifactId>jakarta.annotation-api</artifactId>
+</dependency>Running mvn compile generates your classes under the target/generated-sources/kiota folder.
+You can reference and use the generated code in your project, for example:
import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.apisdk.petstore.json.ApiClient;
+import io.kiota.http.vertx.VertXRequestAdapter;
+import io.vertx.core.Vertx;
+
+@Produces(MediaType.APPLICATION_JSON)
+@Path("/petstore")
+public class PetResource {
+
+ @Inject Vertx vertx;
+
+ RequestAdapter adapter = new VertXRequestAdapter(vertx);
+ ApiClient client = new ApiClient(adapter);
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+Overrides the detected Operating System +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Overrides the detected Architecture +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The path to a kiota executable location to be used. When set, the kiota version is not going to be checked/used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The path to a kiota executable location to be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The kiota version to be used. If not provided we are going to try to resolve "latest" from the GitHub API. Please, set this property in any production grade project. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The timeout to be used when running the kiota CLI. +
+
+Environment variable: |
+string |
+
|
+
Configuration resolved based on the OpenAPI description file name +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The generated API client class name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The generated API client package name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The glob expression to be used to identify the endpoints to be included in the generation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The glob expression to be used to identify the endpoints to be excluded from the generation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+ADVANCED: The serializers to be used in the generated code. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+ADVANCED: The deserializers to be used in the generated code. +
+
+Environment variable: |
+list of string |
++ |
Quarkus' extension for generation of fully typed, client side SDKs based on OpenAPI specification files.
+This extension is based on the Microsoft Kiota generator.
+Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.
+First of all you need to add or update the quarkus-maven-plugin configuration with the following:
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Add the extension dependency to your project’s pom.xml file:
<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>quarkus-kiota</artifactId>
+ <version>{project.version}</version>
+</dependency>Now, create a new folder named openapi under src/main/ and add OpenAPI spec files there. Supported file extensions are: json, yaml, yml.
To fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.kiota.petstore.json.package-name=com.mycompanyIf a base package name is not provided, it will be used the default io.apisdk.<filename>. For example, io.apisdk.petstore.json.
You can customize the name of Api Client class using the following property:
+quarkus.kiota.petstore.json.class-name=MyApiClientNow add the additional dependencies to compile the project:
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-abstractions</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>kiota-http-vertx</artifactId> <!-- alternatively <artifactId>kiota-http-jdk</artifactId> -->
+ <version>{version}</version>
+</dependency>
+<dependency>
+ <groupId>io.kiota</groupId>
+ <artifactId>kiota-serialization-jackson-quarkus</artifactId>
+ <version>{version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-text</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-form</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>com.microsoft.kiota</groupId>
+ <artifactId>microsoft-kiota-serialization-multipart</artifactId>
+ <version>${kiota.libs.version}</version>
+</dependency>
+<dependency>
+ <groupId>jakarta.annotation</groupId>
+ <artifactId>jakarta.annotation-api</artifactId>
+</dependency>Running mvn compile generates your classes under the target/generated-sources/kiota folder.
+You can reference and use the generated code in your project, for example:
import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.apisdk.petstore.json.ApiClient;
+import io.kiota.http.vertx.VertXRequestAdapter;
+import io.vertx.core.Vertx;
+
+@Produces(MediaType.APPLICATION_JSON)
+@Path("/petstore")
+public class PetResource {
+
+ @Inject Vertx vertx;
+
+ RequestAdapter adapter = new VertXRequestAdapter(vertx);
+ ApiClient client = new ApiClient(adapter);
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+With Kiota you can plug in any authentication mechanism provided by the underlying HTTP client.
+For example, when using the VertX HTTP client you can configure a Bearer Access Token with OIDC like:
+OAuth2Options options =
+ new OAuth2Options()
+ .setFlow(OAuth2FlowType.CLIENT)
+ .setClientId(CLIENT_ID)
+ .setTokenPath(keycloakUrl + "token")
+ .setClientSecret(CLIENT_SECRET);
+
+OAuth2Auth oAuth2Auth = OAuth2Auth.create(vertx, options);
+
+Oauth2Credentials oauth2Credentials = new Oauth2Credentials();
+
+OAuth2WebClient oAuth2WebClient =
+ OAuth2WebClient.create(WebClient.create(vertx), oAuth2Auth)
+ .withCredentials(oauth2Credentials);
+
+var adapter = new VertXRequestAdapter(oAuth2WebClient);Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+Overrides the detected Operating System +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Overrides the detected Architecture +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The path to a kiota executable location to be used. When set, the kiota version is not going to be checked/used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The path to a kiota executable location to be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The kiota version to be used. If not provided we are going to try to resolve "latest" from the GitHub API. Please, set this property in any production grade project. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The timeout to be used when running the kiota CLI. +
+
+Environment variable: |
+string |
+
|
+
Configuration resolved based on the OpenAPI description file name +This configuration section is optional |
+Type |
+Default |
+
+
+
+
+
+
+The generated API client class name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The generated API client package name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The glob expression to be used to identify the endpoints to be included in the generation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The glob expression to be used to identify the endpoints to be excluded from the generation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+ADVANCED: The serializers to be used in the generated code. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+ADVANCED: The deserializers to be used in the generated code. +
+
+Environment variable: |
+list of string |
++ |
The core premise of agents involves employing a language model to discern a sequence of actions. +Unlike chains, where actions are hardcoded, agents utilize a language model as a reasoning engine to determine the actions (tools) and their sequence.
+The agent is the core decision-maker responsible for determining the subsequent steps. It’s driven by a language model and a prompt. The inputs include:
+Tools: Descriptions of available actions
+User Input: The high-level objective
+Intermediate Steps: Previous (action, tool output) pairs executed in the order to fulfill the user input
+The output presents the next action(s) to take or the final response to be delivered to the user. Each action specifies a tool (method name) and its corresponding input parameters.
+Tools are the methods an agent can invoke. Two elements are essential when using tools:
+Granting the agent access to the right tools.
+Describing tools in a manner most beneficial to the agent.
+Failure to consider both aspects may hinder the agent’s functionality. Access to an incorrect set of tools impedes the agent from achieving objectives, while improperly described tools hamper their effective utilization.
+When constructing an agent, consider:
+Setting the model temperature to 0 for the agent to consistently choose the most probable action.
+Ensuring well-detailed descriptions of tools.
+Listing steps in the prompt in the desired execution order.
+A tool denotes a method accessible by an agent. It must be part of a CDI bean and have at least one method annotated with @Tool:
// Example of an EmailService tool method
+package io.quarkiverse.langchain4j.sample;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.agent.tool.Tool;
+import io.quarkus.logging.Log;
+import io.quarkus.mailer.Mail;
+import io.quarkus.mailer.Mailer;
+
+@ApplicationScoped
+public class EmailService {
+
+ @Inject
+ Mailer mailer;
+
+ @Tool("send the provided content via email")
+ public void sendAnEmail(String content) {
+ Log.info("Sending an email: " + content);
+ mailer.send(Mail.withText("sendMeALetter@quarkus.io", "A poem for you", content));
+ }
+
+}| + + | +
+A CDI bean can host multiple methods annotated with @Tool.
+However, ensure each method name is unique among all declared tools.
+ |
+
In the AI Service, you can specify the tools accessible to the agent. By default, no tools are available. Hence, ensure to define the list of tools you wish to make accessible:
+@RegisterAiService(tools = EmailService.class)
+public interface MyAiService {
+ // ...
+}When employing tools, configuring the memory provider is necessary. Since tools necessitate a sequence of messages, maintaining this conversation is essential. A minimum memory of three messages is necessary for optimal tool functionality.
+The question of how tools work naturally arises given the fact that no code needs to be written that wires up their usage.
+The short answer is by providing the proper user and system messages and tool descriptions, the extension is able to craft +API requests that allow the LLM to respond back with the proper tool invocations - but it is the extension itself then proceeds to invoke the tool. +The result of the invocation is then used by the extension to make another request to the LLM which will then response with a new answer, potentially leading to another round of a tool invocation and the crafting of a new request to the LLM.
+To help clarify the various interactions, let’s use the following example where we are creating a very simple calculator chatbot that responds to user requests over HTTP, leveraging the quarkus-langchain4j-openai extension.
+Here is the full source code:
import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+import jakarta.annotation.PreDestroy;
+import jakarta.enterprise.context.RequestScoped;
+import jakarta.inject.Singleton;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import org.jboss.resteasy.reactive.RestQuery;
+
+import dev.langchain4j.agent.tool.Tool;
+import dev.langchain4j.memory.ChatMemory;
+import dev.langchain4j.memory.chat.ChatMemoryProvider;
+import io.quarkiverse.langchain4j.RegisterAiService;
+import io.quarkiverse.langchain4j.RemovableChatMemoryProvider;
+
+@Path("assistant-with-tool")
+public class AssistantWithToolsResource {
+
+ private final Assistant assistant;
+
+ public AssistantWithToolsResource(Assistant assistant) {
+ this.assistant = assistant;
+ }
+
+ @GET (3)
+ public String get(@RestQuery String message) {
+ return assistant.chat(message);
+ }
+
+ @Singleton (1)
+ public static class Calculator {
+
+ @Tool("Calculates the length of a string")
+ int stringLength(String s) {
+ return s.length();
+ }
+
+ @Tool("Calculates the sum of two numbers")
+ int add(int a, int b) {
+ return a + b;
+ }
+
+ @Tool("Calculates the square root of a number")
+ double sqrt(int x) {
+ return Math.sqrt(x);
+ }
+ }
+
+ @RegisterAiService(tools = Calculator.class) (2)
+ public interface Assistant {
+
+ String chat(String userMessage);
+ }
+}| 1 | +Declare a CDI bean that provides three different tools | +
| 2 | +Register an AiService that responds to a user’s request and has access to the calculator tools. This service is also able to keep track of the session’s messages using the CDI message store declared above. | +
| 3 | +Declare an HTTP endpoint that retrieves the user’s question via a query parameter and simply responds with chatbot’s response | +
Now, if we ask the chatbot What is the square root of the sum of the numbers of letters in the words "hello" and "world" via:
curl 'http://localhost:8080/assistant-with-tool?message=What%20is%20the%20square%20root%20of%20the%20sum%20of%20the%20numbers%20of%20letters%20in%20the%20words%20%22hello%22%20and%20%22world%22'The response will be The square root of the sum of the numbers of letters in the words "hello" and "world" is approximately 3.162.
What is interesting however in understanding how the tools were used, is seeing the requests the extension has made to OpenAI and the responses the latter provides.
+The application makes a first REST call to OpenAI that contains the following JSON payload:
+{
+ "model": "gpt-3.5-turbo",
+ "messages": [
+ {
+ "role": "user",
+ "content": "What is the square root of the sum of the numbers of letters in the words \"hello\" and \"world\""
+ }
+ ],
+ "temperature": 1.0,
+ "top_p": 1.0,
+ "presence_penalty": 0.0,
+ "frequency_penalty": 0.0,
+ "functions": [
+ {
+ "name": "stringLength",
+ "description": "Calculates the length of a string",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "s": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "s"
+ ]
+ }
+ },
+ {
+ "name": "add",
+ "description": "Calculates the sum of two numbers",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "a": {
+ "type": "integer"
+ },
+ "b": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "a",
+ "b"
+ ]
+ }
+ },
+ {
+ "name": "sqrt",
+ "description": "Calculates the square root of a number",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "x"
+ ]
+ }
+ }
+ ]
+}There are two things to notice in this JSON payload:
+The user message which contains the user’s question (the messages part of the request)
The declaration of the three available functions (the functions part of the request) which directly map to the tools we declared in our source code.
The response from OpenAI is the following:
+{
+ "id": "chatcmpl-8L3uhmaMARLTbpGJGDvFW4pAPxM8V",
+ "object": "chat.completion",
+ "created": 1700030623,
+ "model": "gpt-3.5-turbo-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"hello\"\n}"
+ }
+ },
+ "finish_reason": "function_call"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 118,
+ "completion_tokens": 15,
+ "total_tokens": 133
+ }
+}This response initially looks odd as it does not look like OpenAI has responded to user’s question.
+However, upon closer inspection we see that the response contains something very interesting and that is the function_call part.
+In this part OpenAI is essentially telling the extension to invoke the stringLength tool with hello as the sole parameter.
+This is where the power of the LLM is evident - it has essentially figured out that to answer the user’s question, it first needs to calculate the length of "hello".
Upon receiving this response, the extension invokes calculator.stringLength("hello") and then sends the following new request to OpenAI:
{
+ "model": "gpt-3.5-turbo",
+ "messages": [
+ {
+ "role": "user",
+ "content": "What is the square root of the sum of the numbers of letters in the words \"hello\" and \"world\""
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"hello\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ }
+ ],
+ "temperature": 1.0,
+ "top_p": 1.0,
+ "presence_penalty": 0.0,
+ "frequency_penalty": 0.0,
+ "functions": [
+ {
+ "name": "stringLength",
+ "description": "Calculates the length of a string",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "s": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "s"
+ ]
+ }
+ },
+ {
+ "name": "add",
+ "description": "Calculates the sum of two numbers",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "a": {
+ "type": "integer"
+ },
+ "b": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "a",
+ "b"
+ ]
+ }
+ },
+ {
+ "name": "sqrt",
+ "description": "Calculates the square root of a number",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "x"
+ ]
+ }
+ }
+ ]
+}What is very important to notice here is that the extension is sending not only has the user’s question, +but also the LLM’s first response requesting a tool invocation, along with a new message containing the result of the said invocation. +Recall that LLMs are stateless, therefore the entire message history needs to be sent each time - this is the reason why the use of tools +requires a chat memory.
+OpenAI now responds with the following:
+{
+ "id": "chatcmpl-8L3ukBR1Pblqn4g5m3JocHQVzYqMy",
+ "object": "chat.completion",
+ "created": 1700030626,
+ "model": "gpt-3.5-turbo-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"world\"\n}"
+ }
+ },
+ "finish_reason": "function_call"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 142,
+ "completion_tokens": 15,
+ "total_tokens": 157
+ }
+}Once again we see the LLM can not yet answer the original user’s question, but instead instructs the extension to invoke a tool.
+As you’d expect by now, the extension does just that and sends the following new request to OpenAI:
+{
+ "model": "gpt-3.5-turbo",
+ "messages": [
+ {
+ "role": "user",
+ "content": "What is the square root of the sum of the numbers of letters in the words \"hello\" and \"world\""
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"hello\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"world\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ }
+ ],
+ "temperature": 1.0,
+ "top_p": 1.0,
+ "presence_penalty": 0.0,
+ "frequency_penalty": 0.0,
+ "functions": [
+ {
+ "name": "stringLength",
+ "description": "Calculates the length of a string",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "s": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "s"
+ ]
+ }
+ },
+ {
+ "name": "add",
+ "description": "Calculates the sum of two numbers",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "a": {
+ "type": "integer"
+ },
+ "b": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "a",
+ "b"
+ ]
+ }
+ },
+ {
+ "name": "sqrt",
+ "description": "Calculates the square root of a number",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "x"
+ ]
+ }
+ }
+ ]
+}This new request, in addition to the previous one sent to OpenAI, contains the result of the invocation of calculator.stringLength("world").
In turn, OpenAI responds with:
+{
+ "id": "chatcmpl-8L3uopZa8wdBmGWoWBqWbCO8UdwVv",
+ "object": "chat.completion",
+ "created": 1700030630,
+ "model": "gpt-3.5-turbo-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "add",
+ "arguments": "{\n \"a\": 5,\n \"b\": 5\n}"
+ }
+ },
+ "finish_reason": "function_call"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 166,
+ "completion_tokens": 21,
+ "total_tokens": 187
+ }
+}This time the LLM instructed the extension that it is time to invoke the add tool using 5 and 5 as arguments - these arguments of course are the results of the previous two stringLength invocations.
The extension upon receiving this response invoked calculator.add(5,5) and then crafts and sends the following message to OpenAI:
{
+ "model": "gpt-3.5-turbo",
+ "messages": [
+ {
+ "role": "user",
+ "content": "What is the square root of the sum of the numbers of letters in the words \"hello\" and \"world\""
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"hello\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"world\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "add",
+ "arguments": "{\n \"a\": 5,\n \"b\": 5\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "10",
+ "name": "add"
+ }
+ ],
+ "temperature": 1.0,
+ "top_p": 1.0,
+ "presence_penalty": 0.0,
+ "frequency_penalty": 0.0,
+ "functions": [
+ {
+ "name": "stringLength",
+ "description": "Calculates the length of a string",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "s": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "s"
+ ]
+ }
+ },
+ {
+ "name": "add",
+ "description": "Calculates the sum of two numbers",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "a": {
+ "type": "integer"
+ },
+ "b": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "a",
+ "b"
+ ]
+ }
+ },
+ {
+ "name": "sqrt",
+ "description": "Calculates the square root of a number",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "x"
+ ]
+ }
+ }
+ ]
+}The response from OpenAI is:
+{
+ "id": "chatcmpl-8L3urz1QWWjh3Dzmjqu0O3hK16NUE",
+ "object": "chat.completion",
+ "created": 1700030633,
+ "model": "gpt-3.5-turbo-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "sqrt",
+ "arguments": "{\n \"x\": 10\n}"
+ }
+ },
+ "finish_reason": "function_call"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 195,
+ "completion_tokens": 14,
+ "total_tokens": 209
+ }
+}The LLM this time decided that the sqrt tool needs to be invoked.
The extension following this instruction invokes calculator.sqrt(10) (10 being the result of the previous add invocation) then crafts and sends the following message to OpenAI:
{
+ "model": "gpt-3.5-turbo",
+ "messages": [
+ {
+ "role": "user",
+ "content": "What is the square root of the sum of the numbers of letters in the words \"hello\" and \"world\""
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"hello\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "stringLength",
+ "arguments": "{\n \"s\": \"world\"\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "5",
+ "name": "stringLength"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "add",
+ "arguments": "{\n \"a\": 5,\n \"b\": 5\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "10",
+ "name": "add"
+ },
+ {
+ "role": "assistant",
+ "content": null,
+ "function_call": {
+ "name": "sqrt",
+ "arguments": "{\n \"x\": 10\n}"
+ }
+ },
+ {
+ "role": "function",
+ "content": "3.1622776601683795",
+ "name": "sqrt"
+ }
+ ],
+ "temperature": 1.0,
+ "top_p": 1.0,
+ "presence_penalty": 0.0,
+ "frequency_penalty": 0.0,
+ "functions": [
+ {
+ "name": "stringLength",
+ "description": "Calculates the length of a string",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "s": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "s"
+ ]
+ }
+ },
+ {
+ "name": "add",
+ "description": "Calculates the sum of two numbers",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "a": {
+ "type": "integer"
+ },
+ "b": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "a",
+ "b"
+ ]
+ }
+ },
+ {
+ "name": "sqrt",
+ "description": "Calculates the square root of a number",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "x"
+ ]
+ }
+ }
+ ]
+}Once again, it’s very important to note that entire chat history has been sent by the extension to OpenAI. +Using this entire chat history, the LLM is finally able to answer the original user’s question:
+{
+ "id": "chatcmpl-8L3utMpnSKtgzWcmHJVwVJd36l9fk",
+ "object": "chat.completion",
+ "created": 1700030635,
+ "model": "gpt-3.5-turbo-0613",
+ "choices": [
+ {
+ "index": 0,
+ "message": {
+ "role": "assistant",
+ "content": "The square root of the sum of the numbers of letters in the words \"hello\" and \"world\" is approximately 3.162."
+ },
+ "finish_reason": "stop"
+ }
+ ],
+ "usage": {
+ "prompt_tokens": 224,
+ "completion_tokens": 29,
+ "total_tokens": 253
+ }
+}As seen above, the answer is The square root of the sum of the numbers of letters in the words \"hello\" and \"world\" is approximately 3.162. and that is what Quarkus will send back to the user as the HTTP response.
An AI Service employs a declarative approach to define interactions with the LLM, serving as the pivotal interaction point between your application and the LLM. It operates as an intermediary, known as an ambassador.
+The AI Service serves as the core connection point between your application and the LLM. It abstracts the LLM specifics, encapsulating and declaring all interactions within a singular interface.
+The @RegisterAiService annotation is pivotal for registering an AI Service, placed on an interface:
@RegisterAiService
+public interface MyAiService {
+ // methods.
+}Once registered, you can inject the AI Service into your application:
+@Inject MyAiService service;| + + | +
+
+
+The beans created by |
+
Within the interface annotated with @RegisterAiService, you model interactions with the LLM using methods. These methods accept parameters and are annotated with @SystemMessage and @UserMessage to define instructions directed to the LLM:
@SystemMessage("You are a professional poet.")
+@UserMessage("""
+ Write a poem about {topic}. The poem should be {lines} lines long. Then send this poem by email.
+""")
+String writeAPoem(String topic, int lines);The @SystemMessage annotation defines the scope and initial instructions, serving as the first message sent to the LLM. It delineates the AI service’s role in the interaction:
@SystemMessage("""
+ You are working for a bank, processing reviews about financial products. Triage reviews into positive and negative ones, responding with a JSON document.
+ """
+)The @UserMessage annotation defines primary instructions dispatched to the LLM. It typically encompasses requests and the expected response format:
@UserMessage("""
+ Your task is to process the review delimited by ---.
+ Apply a sentiment analysis to the review to determine if it is positive or negative, considering various languages.
+
+ For example:
+ - "I love your bank, you are the best!" is a 'POSITIVE' review
+ - "J'adore votre banque" is a 'POSITIVE' review
+ - "I hate your bank, you are the worst!" is a 'NEGATIVE' review
+
+ Respond with a JSON document containing:
+ - the 'evaluation' key set to 'POSITIVE' if the review is positive, 'NEGATIVE' otherwise
+ - the 'message' key set to a message thanking or apologizing to the customer. These messages must be polite and match the review's language.
+
+ ---
+ {review}
+ ---
+""")
+TriagedReview triage(String review);AI methods can take parameters referenced in system and user messages using the {parameter} syntax:
@SystemMessage("You are a professional poet")
+@UserMessage("""
+ Write a poem about {topic}. The poem should be {lines} lines long. Then send this poem by email.
+""")
+String writeAPoem(String topic, int lines);If the prompt defines the JSON response format precisely, you can map the response directly to an object:
+// ... See above for the prompt
+TriagedReview triage(String review);In this instance, Quarkus automatically creates an instance of TriagedReview from the LLM’s JSON response.
For situations requiring the user message to be passed as a parameter, you can use the @UserMessage annotation on a parameter. Exercise caution with this feature, especially when the AI has access to tools:
String chat(@UserMessage String userMessage);The annotated parameter should be of type String.
The memory encompasses the cumulative context of the interaction with the LLM. To manage statelessness in LLMs, the complete context must be exchanged between the LLM and the AI service.
+Hence, the AI Service can store the latest messages in a memory, often termed context. The @MemoryId annotation enables referencing the memory for a specific user in the AI method:
String chat(@MemoryId int memoryId, @UserMessage String userMessage);We’ll explore an alternative approach to avoid manual memory handling in the Configuring the Context (Memory) section.
+While LLMs are the base AI models, the chat language model builds upon them, enabling chat-like interactions. If you have a single chat language model, no specific configuration is required.
+However, when multiple model providers are present in the application (such as OpenAI, Azure OpenAI, HuggingFace, etc.) +each model different model needs to be given a name, which is then referenced by the AI service like so:
+@RegisterAiService(modelName="m1")The configuration of the various models could look like so:
+# ensure that the model with the name 'm1', is provided by OpenAI
+quarkus.langchain4j.m1.chat-model.provider=openai
+# ensure that the model with the name 'm1', is provided by OpenAI
+quarkus.langchain4j.m2.chat-model.provider=huggingface
+
+# configure the various aspects of each model
+quarkus.langchain4j.openai.m1.api-key=sk-...
+quarkus.langchain4j.huggingface.m2.api-key=sk-...As LLMs are stateless, the memory — comprising the interaction context — must be exchanged each time. To prevent storing excessive messages, it’s crucial to evict older messages.
+The chatMemoryProviderSupplier attribute of the @RegisterAiService annotation enables configuring the dev.langchain4j.memory.chat.ChatMemoryProvider. The default value of this annotation is RegisterAiService.BeanIfExistsChatMemoryProviderSupplier.class
+which means that the AiService will use whatever ChatMemoryProvider bean is configured by the application.
The extension provides a default implementation of ChatMemoryProvider which does two things:
It uses whatever bean dev.langchain4j.store.memory.chat.ChatMemoryStore bean is configured, as the backing store. The default implementation is dev.langchain4j.store.memory.chat.InMemoryChatMemoryStore
If the application provides its own ChatMemoryStore bean, that will be used instead of the default InMemoryChatMemoryStore,
It leverages the available configuration options under quarkus.langchain4j.chat-memory to construct the ChatMemoryProvider.
The default configuration values result in the usage of dev.langchain4j.memory.chat.MessageWindowChatMemory with a window size of ten.
By setting quarkus.langchain4j.chat-memory.type=token-window, a dev.langchain4j.memory.chat.TokenWindowChatMemory will be used. Note that this requires the presence of a dev.langchain4j.model.Tokenizer bean.
| + + | +
+
+
+The topic of
+
+However, in cases where more fine-grained control is needed (which is the case when the bean is declared as |
+
| + + | +
+
+
+When using an AiService that is expected to use to chat memory, it is very important to use |
+
Although the extension’s default ChatMemoryProvider is very configurable making unnecessary in most cases to resort to a custom implementation, such a capability is possible. Here is a possible example:
package io.quarkiverse.langchain4j.samples;
+
+import jakarta.inject.Singleton;
+
+import dev.langchain4j.memory.ChatMemory;
+import dev.langchain4j.memory.chat.ChatMemoryProvider;
+import dev.langchain4j.store.memory.chat.ChatMemoryStore;
+
+@Singleton
+public class CustomChatMemoryProvider implements ChatMemoryProvider {
+
+ private final ChatMemoryStore store;
+
+ public CustomChatMemoryProvider() {
+ this.store = createCustomStore();
+ }
+
+ private static ChatMemoryStore createCustomStore() {
+ // TODO: provide some kind of custom store
+ return null;
+ }
+
+ @Override
+ public ChatMemory get(Object memoryId) {
+ return createCustomMemory(memoryId);
+ }
+
+ private static ChatMemory createCustomMemory(Object memoryId) {
+ // TODO: implement using memoryId and store
+ return null;
+ }
+}If for some reason different AI services need to have a different ChatMemoryProvider (i.e. not use the globally available bean), this is possible by configuring the chatMemoryProviderSupplier attribute of the @RegisterAiService annotation and implementing as custom provider.
+Here is a possible example:
package io.quarkiverse.langchain4j.samples;
+
+import java.util.function.Supplier;
+
+import dev.langchain4j.memory.ChatMemory;
+import dev.langchain4j.memory.chat.ChatMemoryProvider;
+import dev.langchain4j.memory.chat.MessageWindowChatMemory;
+import dev.langchain4j.store.memory.chat.InMemoryChatMemoryStore;
+
+public class CustomProvider implements Supplier<ChatMemoryProvider> {
+
+ private final InMemoryChatMemoryStore store = new InMemoryChatMemoryStore();
+
+ @Override
+ public ChatMemoryProvider get() {
+ return new ChatMemoryProvider() {
+
+ @Override
+ public ChatMemory get(Object memoryId) {
+ return MessageWindowChatMemory.builder()
+ .maxMessages(20)
+ .id(memoryId)
+ .chatMemoryStore(store)
+ .build();
+ }
+ };
+ }
+}and configuring the AiService as so:
+@RegisterAiService(
+ chatMemoryProviderSupplier = MySmallMemoryProvider.class)| + + | ++For non-memory-reliant LLM interactions, you may skip memory configuration. + | +
Tools are methods that LLMs can invoke to access additional data. These methods, declared using the @Tool annotation, should be part of a bean:
@ApplicationScoped
+public class CustomerRepository implements PanacheRepository<Customer> {
+
+ @Tool("get the customer name for the given customerId")
+ public String getCustomerName(long id) {
+ return find("id", id).firstResult().name;
+ }
+
+}The @Tool annotation can provide a description of the action, aiding the LLM in tool selection. The @RegisterAiService annotation allows configuring the tool provider:
@RegisterAiService(tools = {TransactionRepository.class, CustomerRepository.class })| + + | ++Ensure you configure the memory provider when using tools. + | +
| + + | ++Be cautious to avoid exposing destructive operations via tools. + | +
More information about tools is available in the Agent and Tools page.
+A document retriever fetches data from an external source and provides it to the LLM. It helps by sending only the relevant data, considering the LLM’s context limitations.
+This guidance aims to cover all crucial aspects of designing AI services with Quarkus, ensuring robust and efficient interactions with LLMs.
+By default, @RegisterAiService annotated interfaces don’t moderate content. However, users can opt in to having the LLM moderate
+content by annotating the method with @Moderate.
For moderation to work, the following criteria need to be met:
+A CDI bean for dev.langchain4j.model.moderation.ModerationModel must be configured (the quarkus-langchain4j-openai and quarkus-langchain4j-azure-openai provide one out of the box)
The interface must be configured with @RegisterAiService(moderationModelSupplier = RegisterAiService.BeanModerationModelSupplier.class)
An alternative to providing a CDI bean is to configure the interface with @RegisterAiService(moderationModelSupplier = MyCustomSupplier.class)
+and implement MyCustomModerationSupplier like so:
import dev.langchain4j.model.moderation.ModerationModel;
+
+public class MyCustomModerationSupplier implements Supplier<ModerationModel> {
+
+ @Override
+ public ModerationModel get(){
+ // TODO: implement
+ }
+
+}Observability is built into services created via @RegisterAiService and is provided in the following form:
Metrics are enabled when quarkus-micrometer is part of the application
Traces are enabled when quarkus-opentelemetry is part of the application
Each AI method is automatically timed and the timer data is available using the langchain4j.aiservices.$interface_name.$method_name template for the name.
For example, if the AI service looks like:
+@RegisterAiService
+public interface PoemAiService {
+
+ @SystemMessage("You are a professional poet")
+ @UserMessage("Write a poem about {topic}. The poem should be {lines} lines long")
+ String writeAPoem(String topic, int lines);
+}and one chooses to use quarkus-micrometer-registry-prometheus, then the metrics could be:
# TYPE langchain4j_aiservices counter
+# HELP langchain4j_aiservices
+langchain4j_aiservices_total{aiservice="MyAiService",exception="none",method="writeAPoem",result="success"} 5.0
+
+# TYPE langchain4j_aiservices_seconds_max gauge
+# HELP langchain4j_aiservices_seconds_max
+langchain4j_aiservices_seconds_max{aiservice="MyAiService",method="writeAPoem"} 7.725769221
+# TYPE langchain4j_aiservices_seconds summary
+# HELP langchain4j_aiservices_seconds
+langchain4j_aiservices_seconds_count{aiservice="MyAiService",method="writeAPoem"} 5.0
+langchain4j_aiservices_seconds_sum{aiservice="MyAiService",method="writeAPoem"} 30.229575906Each AI method creates its own span using the langchain4j.aiservices.$interface_name.$method_name template for the name.
+Furthermore, tool invocations also create a span using langchain4j.tools.$tool_name template for the name.
For example, if the AI service looks like:
+@RegisterAiService(tools = EmailService.class)
+public interface PoemAiService {
+
+ @SystemMessage("You are a professional poet")
+ @UserMessage("Write a poem about {topic}. The poem should be {lines} lines long. Then send this poem by email.")
+ String writeAPoem(String topic, int lines);
+
+}a tool that looks like:
+@ApplicationScoped
+public class EmailService {
+
+ @Inject
+ Mailer mailer;
+
+ @Tool("send the given content by email")
+ public void sendAnEmail(String content) {
+ Log.info("Sending an email: " + content);
+ mailer.send(Mail.withText("sendMeALetter@quarkus.io", "A poem for you", content));
+ }
+
+}and invocation of the AI service that looks like:
+@Path("/email-me-a-poem")
+public class EmailMeAPoemResource {
+
+ private final MyAiService service;
+
+ public EmailMeAPoemResource(MyAiService service) {
+ this.service = service;
+ }
+
+ @GET
+ public String emailMeAPoem() {
+ return service.writeAPoem("Quarkus", 4);
+ }
+
+}then an example trace is:
+
+In the trace above we can see the parent span which corresponds to the handling the GET HTTP request, but the real
+interesting thing is the langchain4j.aiservices.MyAiService.writeAPoem span which corresponds to the invocation of the AI service.
+The child spans of this span correspond (from to right) to calling the OpenAI API, invoking the sendEmail tool and finally invoking calling the OpenAI API again.
The extension allows users to audit the process of implementing an AiService by introducing io.quarkiverse.langchain4j.audit.AuditService and io.quarkiverse.langchain4j.audit.Audit.
+By default, if a bean of type AuditService is present in the application, it will be used in order to create an Audit, which received various callbacks pertaining to the implementation
+of the AiService method. More information can be found on the javadoc of these two classes.
When implementing Retrieval Augmented Generation (RAG), a robust document store is crucial. This guide demonstrates how to leverage a Chroma database as the document store.
+To make use of the Chroma document store, you’ll need to include the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-chroma</artifactId>
+ <version>0.9.0</version>
+</dependency>This extension includes a dev service. Therefore, if you’re operating in a container environment, a Chroma instance will automatically start in dev and test mode.
+Upon installing the extension, you can use the Chroma document store with the following code:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.splitter.DocumentSplitters.recursive;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
+import io.quarkiverse.langchain4j.chroma.ChromaEmbeddingStore;
+
+@ApplicationScoped
+public class IngestorExampleWithChroma {
+
+ /**
+ * The embedding store (the database).
+ * The bean is provided by the quarkus-langchain4j-chroma extension.
+ */
+ @Inject
+ ChromaEmbeddingStore store;
+
+ /**
+ * The embedding model (how is computed the vector of a document).
+ * The bean is provided by the LLM (like openai) extension.
+ */
+ @Inject
+ EmbeddingModel embeddingModel;
+
+ public void ingest(List<Document> documents) {
+ EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store)
+ .embeddingModel(embeddingModel)
+ .documentSplitter(recursive(500, 0))
+ .build();
+ // Warning - this can take a long time...
+ ingestor.ingest(documents);
+ }
+}Customize the behavior of the extension by exploring various configuration options:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use:
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Redis server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Redis starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Chroma servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+URL where the Chroma database is listening for requests +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The collection name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the Chroma client. If not specified, 5 seconds will be used. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Environment variables that are passed to the container. +
+
+Environment variable: |
+
|
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
When working with the Retrieval Augmented Generation (RAG) model, it is often necessary to load tabular data, such as a CSV file. This guide provides recommendations for loading CSV files in a way that is compatible with the RAG model.
+When loading a CSV file, the process involves:
+Transforming each row into a document.
+Ingesting the set of documents using an appropriate document splitter.
+Storing the documents in the database.
+You can find a complete example in the GitHub Repository.
+There are multiple ways to load CSV files in Java. In this example, we use the following dependencies:
+<dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-csv</artifactId>
+ <version>1.10.0</version>
+</dependency>You can choose a different library; the APIs are similar enough.
+Once you have the dependency, load the CSV and process the rows:
+/**
+ * The CSV file to load.
+ */
+@ConfigProperty(name = "csv.file")
+File file;
+
+/**
+ * The CSV file headers.
+ * Some libraries provide an API to extract them.
+ */
+@ConfigProperty(name = "csv.headers")
+List<String> headers;
+
+/**
+ * Ingest the CSV file.
+ * This method is executed when the application starts.
+ */
+public void ingest(@Observes StartupEvent event) throws IOException {
+ // Configure the CSV format.
+ CSVFormat csvFormat = CSVFormat.DEFAULT.builder()
+ .setHeader(headers.toArray(new String[0]))
+ .setSkipHeaderRecord(true)
+ .build();
+ // This will be the resulting list of documents:
+ List<Document> documents = new ArrayList<>();
+
+ try (Reader reader = new FileReader(file)) {
+ // Generate one document per row, using the specified syntax.
+ Iterable<CSVRecord> records = csvFormat.parse(reader);
+ int i = 1;
+ for (CSVRecord record : records) {
+ Map<String, String> metadata = new HashMap<>();
+ metadata.put("source", file.getAbsolutePath());
+ metadata.put("row", String.valueOf(i++));
+
+ StringBuilder content = new StringBuilder();
+ for (String header : headers) {
+ // Include all headers in the metadata.
+ metadata.put(header, record.get(header));
+ content.append(header).append(": ").append(record.get(header)).append("\n");
+ }
+ documents.add(new Document(content.toString(), Metadata.from(metadata)));
+ }
+ // ...
+}Once you have the list of documents, they need to be ingested. For this, use a document splitter. We recommend the recurve splitter, a simple splitter that divides the document into chunks of a given size. While it may not be the most suitable splitter for your use case, it serves as a good starting point.
var ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store) // Injected
+ .embeddingModel(embeddingModel) // Injected
+ .documentSplitter(recursive(500, 0))
+ .build();
+ingestor.ingest(documents);With the documents ingested, you can now implement the retriever:
+package io.quarkiverse.langchain4j.sample.chatbot;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import dev.langchain4j.data.segment.TextSegment;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.retriever.EmbeddingStoreRetriever;
+import dev.langchain4j.retriever.Retriever;
+import io.quarkiverse.langchain4j.redis.RedisEmbeddingStore;
+
+@ApplicationScoped
+public class RetrieverExample implements Retriever<TextSegment> {
+
+ private final EmbeddingStoreRetriever retriever;
+
+ RetrieverExample(RedisEmbeddingStore store, EmbeddingModel model) {
+ // Limit the number of documents to avoid exceeding the context size.
+ retriever = EmbeddingStoreRetriever.from(store, model, 10);
+ }
+
+ @Override
+ public List<TextSegment> findRelevant(String s) {
+ return retriever.findRelevant(s);
+ }
+}If you use the Dev mode, the quarkus-langchain4j project provides several pages
+in the Dev UI to facilitate development:
AI Services page: provides a table of all AI Services detected in the application along +with a list of tools that they are declared to use.
+Tools page: provides a list of tools detected in the application.
+Chat page: allows you to manually hold a conversation with a chat model. This +page is only available if the application contains a chat model.
+Images page: allows you to test the outputs of image models and tune its parameters.
+This page is provided specifically by the openai-vanilla extension and is currently specific
+to OpenAI’s image models. It appears if the application uses the openai-vanilla extension
+and doesn’t have image models explicitly disabled.
Moderation page: allows you to test the outputs of moderation models - you submit a prompt
+and receive a list of scores for each appropriateness category (violence, sexual, hate,…).
+This page is currently only available with the openai-vanilla extension, and it
+appears if the application doesn’t explicitly disable moderation models.
By default, all integrations with AI providers (OpenAI, HuggingFace, Azure OpenAI, etc) are enabled. This means that live calls are made to the configured AI provider.
+Each provider has an enable-integration property (i.e. quarkus.langchain4j.openai.enable-integration, quarkus.langchain4j.huggingface.enable-integration, etc) that can be set to false to disable the integration. This property is read at runtime.
When disabled, any call made to the AI provider will end up in an dev.langchain4j.model.ModelDisabledException runtime exception being thrown.
In this case your AI Service could use fault tolerance to handle this and serve a fallback response without making a live call to the AI provider. Below are a few examples of how it could be used:
+package io.quarkiverse.langchain4j.samples;
+
+import org.eclipse.microprofile.faulttolerance.Fallback;
+
+import dev.langchain4j.model.ModelDisabledException;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+public interface AiServiceWithFaultToleranceAndOnDisabledIntegration {
+ @SystemMessage("You are a professional poet")
+ @UserMessage("Write a poem about {topic}. The poem should be {lines} lines long.")
+ @Fallback(fallbackMethod = "fallback")
+ String writeAPoem(String topic, int lines);
+
+ // This fallback is only called when a ModelDisabledException is thrown due to disabled integration
+ default String fallback(String topic, int lines, ModelDisabledException mde) {
+ return "I'm sorry, but the integration with the AI provider because " + mde.getMessage();
+ }
+
+ // This fallback is called for any other exception, except for ModelDisabledException
+ default String fallback(String topic, int lines) {
+ return "I'm sorry, I can't write a poem about " + topic;
+ }
+}package io.quarkiverse.langchain4j.samples;
+
+import org.eclipse.microprofile.faulttolerance.Fallback;
+
+import dev.langchain4j.model.ModelDisabledException;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+public interface AiServiceWithFaultToleranceOnlyOnDisabledIntegration {
+ @SystemMessage("You are a professional poet")
+ @UserMessage("Write a poem about {topic}. The poem should be {lines} lines long.")
+ @Fallback(fallbackMethod = "fallback", applyOn = ModelDisabledException.class)
+ String writeAPoem(String topic, int lines);
+
+ // In this case, the fallback is only applied if a ModelDisabledException is thrown
+ default String fallback(String topic, int lines) {
+ return "I'm sorry, I can't write a poem about " + topic;
+ }
+}When implementing an AI service, leveraging Quarkus fault tolerance annotations can enhance the reliability of your interactions. +To integrate fault tolerance, follow these steps:
+1. Start by adding the quarkus-smallrye-fault-tolerance dependency to your pom.xml file:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
+</dependency>2. Utilize the @Fallback or @Timeout annotation within the AIService class. These annotations help manage exceptional scenarios:
package io.quarkiverse.langchain4j.samples;
+
+import java.util.concurrent.TimeUnit;
+
+import org.eclipse.microprofile.faulttolerance.Fallback;
+import org.junit.jupiter.api.Timeout;
+
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+public interface AiServiceWithFaultTolerance {
+
+ @SystemMessage("You are a professional poet")
+ @UserMessage("Write a poem about {topic}. The poem should be {lines} lines long.")
+ @Timeout(value = 60, unit = TimeUnit.SECONDS)
+ @Fallback(fallbackMethod = "fallback")
+ String writeAPoem(String topic, int lines);
+
+ default String fallback(String topic, int lines) {
+ return "I'm sorry, I can't write a poem about " + topic;
+ }
+}When employing tools in your interactions, multiple requests and responses occur in the background, potentially extending the time required to obtain a response from the AI service. It’s essential to consider this while configuring a timeout to ensure robustness in your system’s interactions.
+Hugging Face is a leading platform in the field of natural language processing (NLP) that provides a comprehensive collection of pre-trained language models. Hugging Face facilitates easy access to a wide range of state-of-the-art models for various NLP tasks. +Its focus on democratizing access to cutting-edge NLP capabilities has made Hugging Face a pivotal player in the advancement of language technology.
+To employ Hugging Face LLMs, integrate the following dependency into your project:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-hugging-face</artifactId>
+ <version>0.9.0</version>
+</dependency>If no other LLM extension is installed, AI Services will automatically utilize the configured Hugging Face model.
+| + + | ++Hugging Face provides multiple kind of models. We only support text-to-text models, which are models that take a text as input and return a text as output. + | +
By default, the extension uses:
+tiiuae/falcon-7b-instruct as chat model (inference endpoint: https://api-inference.huggingface.co/models/tiiuae/falcon-7b-instruct)
+sentence-transformers/all-MiniLM-L6-v2 as embedding model (inference endpoint: https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2)
+Configuring Hugging Face models mandates an API key, obtainable by creating an account on the Hugging Face platform.
+The API key can be set in the application.properties file:
quarkus.langchain4j.huggingface.api-key=hf-...| + + | +
+Alternatively, leverage the QUARKUS_LANGCHAIN4J_HUGGINGFACE_API_KEY environment variable.
+ |
+
Several configuration properties are available:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+HuggingFace API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout for HuggingFace calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the chat model. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to use sampling ; use greedy decoding otherwise. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The number of highest probability vocabulary tokens to keep for top-k-filtering. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to less than
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the embedding. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+HuggingFace API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout for HuggingFace calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the chat model. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to use sampling ; use greedy decoding otherwise. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The number of highest probability vocabulary tokens to keep for top-k-filtering. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to less than
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the embedding. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
You can change the chat model by setting the quarkus.langchain4j.huggingface.chat-model.inference-endpoint-url property.
+When using a model hosted on Hugging Face, the property should be set to: https://api-inference.huggingface.co/models/<model-id>;.
For example, to use the google/flan-t5-small model, set:
quarkus.langchain4j.huggingface.chat-model.inference-endpoint-url=https://api-inference.huggingface.co/models/google/flan-t5-smallRemember that only text to text models are supported.
+Hugging Face models can be deployed to provide inference endpoints.
+In this case, configure the quarkus.langchain4j.huggingface.inference-endpoint-url property to point to the endpoint URL:
quarkus.langchain4j.huggingface.chat-model.inference-endpoint-url=https://j9dkyuliy170f3ia.us-east-1.aws.endpoints.huggingface.cloudIf you run a model locally, adapt the URL accordingly:
+quarkus.langchain4j.huggingface.chat-model.inference-endpoint-url=http://localhost:8085When utilizing Hugging Face models, the recommended practice involves leveraging the EmbeddingModel provided by Hugging Face.
If no other LLM extension is installed, retrieve the embedding model as follows:
+@Inject EmbeddingModel model; // Injects the embedding modelYou can configure the model using:
+quarkus.langchain4j.huggingface.embedding-model.inference-endpoint-url=https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2| + + | ++Not every sentence transformers are supported by the embedding model. If you want to use a custom sentence transformers, you need to create your own embedding model. + | +
When ingesting document or implementing the RAG pattern, you need an embedding model. +This is a model that takes a document and returns a vector representation of that document. +The vector representation is stored in a vector database, and is used to find similar documents.
+When using LLMs like OpenAI or HuggingFace, it provides remote embedding models. +To compute the embedding of a document, you need to send the document to the remote model.
+In-process models avoids this overhead by running the model in the same process as the application. +This is generally faster, but requires more memory.
+The Quarkus LangChain4j extension provides supports for a set of in-process embedding models. +They are not included by default, and you need to add the explicit dependency to your project.
+The following table lists the supported models, and the corresponding dependency to add to your project.
+| Model Name | +Dependency | +Vector Dimension | +Injected type | +
|---|---|---|---|
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
| + |
|
+384 |
+
|
+
You can inject the model in your application using:
+@Inject E5SmallV2QuantizedEmbeddingModel model;Use the corresponding model type for the model you want to use, and make sure you have added the corresponding dependency to your project.
+Note that if you do not have any other embedding model in your project, you can inject the EmbeddingModel interface, and it will be automatically injected with the available model:
@Inject EmbeddingModel model;Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use:
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Redis server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Redis starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Chroma servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+URL where the Chroma database is listening for requests +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+The collection name. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the Chroma client. If not specified, 5 seconds will be used. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+Environment variables that are passed to the container. +
+
+Environment variable: |
+
|
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+HuggingFace API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout for HuggingFace calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the chat model. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to use sampling ; use greedy decoding otherwise. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The number of highest probability vocabulary tokens to keep for top-k-filtering. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to less than
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the embedding. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+HuggingFace API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout for HuggingFace calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the chat model. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to use sampling ; use greedy decoding otherwise. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The number of highest probability vocabulary tokens to keep for top-k-filtering. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+If set to less than
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The URL of the inference endpoint for the embedding. +
+
+When using Hugging Face with the inference API, the URL is
+
+When using a deployed inference endpoint, the URL is the URL of the endpoint. When using a local hugging face model, the URL is the URL of the local model. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the HuggingFace client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the Infinispan client to use. These clients are configured by means of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+long |
+required |
+
+
+
+
+
+
+Name of the cache that will be used in Infinispan when searching for related embeddings. If this cache doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The maximum distance. The most distance between vectors is how close or far apart two embeddings are. +
+
+Environment variable: |
+int |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Base URL where the Ollama serving is running +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for Ollama calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+With a static number the result is always the same. With a random number the result varies Example: Random random = new Random(); int x = random.nextInt(Integer.MAX_VALUE); +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Base URL where the Ollama serving is running +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for Ollama calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+With a static number the result is always the same. With a random number the result varies Example: Random random = new Random(); int x = random.nextInt(Integer.MAX_VALUE); +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Base URL of OpenAI API +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenAI API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+OpenAI Organization ID (https://platform.openai.com/docs/api-reference/organization-optional) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for OpenAI calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of times to retry +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens can’t exceed the model’s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096). +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether embedding model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether embedding model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether moderation model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether moderation model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The path where the generated images will be persisted to disk. This only applies of
+
+Environment variable: |
+path |
+
|
+
+
+
+
+
+
+The format in which the generated images are returned. +
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The size of the generated images. +
+
+Must be one of
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The quality of the image that will be generated. +
+
+
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The number of images to generate. +
+
+Must be between 1 and 10. +
+
+When the model is dall-e-3, only n=1 is supported. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The style of the generated images. +
+
+Must be one of
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether image model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether image model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Base URL of OpenAI API +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenAI API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+OpenAI Organization ID (https://platform.openai.com/docs/api-reference/organization-optional) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for OpenAI calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of times to retry +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens can’t exceed the model’s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096). +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether embedding model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether embedding model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether moderation model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether moderation model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The path where the generated images will be persisted to disk. This only applies of
+
+Environment variable: |
+path |
+
|
+
+
+
+
+
+
+The format in which the generated images are returned. +
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The size of the generated images. +
+
+Must be one of
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The quality of the image that will be generated. +
+
+
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The number of images to generate. +
+
+Must be between 1 and 10. +
+
+When the model is dall-e-3, only n=1 is supported. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The style of the generated images. +
+
+Must be one of
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether image model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether image model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the configured Postgres datasource to use for this store. If not set, the default datasource from the Agroal extension will be used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The table name for storing embeddings +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+int |
+required |
+
+
+
+
+
+
+Use index or not +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+index size +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Create table or not +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Drop table or not +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The API key to Pinecone. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Environment name, e.g. gcp-starter or northamerica-northeast1-gcp. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+ID of the project. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Name of the index within the project. If the index doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Dimension of the embeddings in the index. This is required only in case that the index doesn’t exist yet and needs to be created. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The type of the pod to use. This is only used if the index doesn’t exist yet and needs to be created. The format: One of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the index to become ready. Only relevant if the index doesn’t exist yet and needs to be created. If not specified, 1 minute will be used. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The namespace. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The name of the field that contains the text segment. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the Pinecone client. If not specified, 5 seconds will be used. +
+
+Environment variable: |
+Duration + |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the Redis client to use. These clients are configured by means of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+long |
+required |
+
+
+
+
+
+
+Name of the index that will be used in Redis when searching for related embeddings. If this index doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Names of extra fields that will be stored in Redis along with the embedding vectors. This corresponds to keys in the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Metric used to compute the distance between two vectors. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Name of the key that will be used to store the embedding vector. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the key that will be used to store the embedded text. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Prefix to be applied to all keys by the embedding store. Embeddings are stored in Redis under a key that is the concatenation of this prefix and the embedding ID. +
+
+If the configured prefix does not ends with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Algorithm used to index the embedding vectors. +
+
+Environment variable: |
+
+
|
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The model provider to use +
+
+Environment variable: |
+string |
++ |
Large Language Models (LLMs) are AI-based systems designed to understand, generate, and manipulate human language, showcasing advanced natural language processing capabilities. +The dynamic LLM landscape is reshaping our interactions with applications and the very construction of these applications. +The Quarkus LangChain4j extension seamlessly integrates LLMs into Quarkus applications, enabling the harnessing of LLM capabilities for the development of more intelligent applications.
+For instance, an application utilizing this extension can:
+Automatically triage or classify documents
+Extract structured and unstructured information from various data sources
+Construct chatbots for system interaction
+Generate personalized text such as emails or reports
+This extension is built upon the LangChain4j library. +It offers a declarative approach to interact with diverse LLMs like OpenAI, Hugging Face, or Ollama. It facilitates LLM-invoked functions within Quarkus applications and allows document loading within the LLM "context".
+
+To incorporate Quarkus LangChain4j into your Quarkus project, add the following Maven dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-openai</artifactId>
+ <version>0.9.0</version>
+</dependency>or, to use hugging face:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-huggingface</artifactId>
+ <version>0.9.0</version>
+</dependency>Then, include your OpenAI API key in your application.properties file (or any other mandatory configuration):
quarkus.langchain4j.openai.api-key=sk-...| + + | +
+Alternatively, utilize the QUARKUS_LANGCHAIN4J_OPENAI_API_KEY environment variable.
+ |
+
Once you’ve added the dependency and configuration, the next step involves creating an AI service, serving as the integration point. This service is the interface your application code will utilize to interact with the LLM. A basic example is demonstrated below:
+package io.quarkiverse.langchain4j.samples;
+
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService( (1)
+ tools = EmailService.class (2)
+)
+public interface MyAiService {
+
+ @SystemMessage("You are a professional poet") (3)
+ @UserMessage("""
+ Write a poem about {topic}. The poem should be {lines} lines long. Then send this poem by email. (4)
+ """)
+ String writeAPoem(String topic, int lines); (5)
+}| 1 | +The @RegisterAiService annotation registers the AI service. |
+
| 2 | +The tools attribute defines the tools the LLM can employ.
+During interaction, the LLM can invoke these tools and reflect on their output. |
+
| 3 | +The @SystemMessage annotation registers a system message, setting the initial context or "scope". |
+
| 4 | +The @UserMessage annotation serves as the prompt. |
+
| 5 | +The method invokes the LLM, initiating an exchange between the LLM and the application, beginning with the system message and then the user message. Your application triggers this method and receives the response. | +
The extension offers the following advantages over using the vanilla LangChain4j library in Quarkus:
+Seamless integration with the Quarkus programming model
+CDI beans for the LangChain4j models
+Standard configuration properties for configuring said models
+Built-in observability
+Metrics
+Tracing
+Auditing
+Build time wiring
+Reduced footprint of the library
+Feedback about misuse at build time
+Leverage runtime Quarkus components
+REST calls and JSON handling are performed using the libraries used throughout Quarkus
+Results in reduces library footprint
+Enables GraalVM native image compilation
+Dev UI features
+View table with information about AI services and tools
+Add embeddings into the embedding store
+Search for relevant embeddings in the embedding store
+When implementing Retrieval Augmented Generation (RAG), a capable document store is necessary. This guide will explain how to leverage Infinispan Server as the embeddings store.
+To utilize the Infinispan as embedding store, you’ll need to include the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-infinispan</artifactId>
+ <version>0.9.0</version>
+</dependency>This extension relies on the Quarkus Infinispan client. Ensure the default Infinispan client is configured appropriately. For detailed guidance, refer to the Quarkus Infinispan Client Quickstart and the Quarkus Infinispan Client Reference.
+| + + | +
+The Infinispan document store requires the dimension of the vector to be set. Add the quarkus.langchain4j.infinispan.dimension property to your application.properties file and set it to the dimension of the vector. The dimension depends on the embedding model you use.
+For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536.
+ |
+
Upon installing the extension, you can utilize the Infinispan document store using the following code:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.splitter.DocumentSplitters.recursive;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
+import io.quarkiverse.langchain4j.infinispan.InfinispanEmbeddingStore;
+
+@ApplicationScoped
+public class IngestorExampleWithInfinispan {
+
+ /**
+ * The embedding store (Infinispan).
+ * The bean is provided by the quarkus-langchain4j-infinispan extension.
+ */
+ @Inject
+ InfinispanEmbeddingStore store;
+
+ /**
+ * The embedding model (how is computed the vector of a document).
+ * The bean is provided by the LLM (like openai) extension.
+ */
+ @Inject
+ EmbeddingModel embeddingModel;
+
+ public void ingest(List<Document> documents) {
+ EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store)
+ .embeddingModel(embeddingModel)
+ .documentSplitter(recursive(500, 0))
+ .build();
+ // Warning - this can take a long time...
+ ingestor.ingest(documents);
+ }
+}By default, the extension utilizes the default Infinispan client for storing and indexing the documents. Customize the behavior of the extension by exploring various configuration options:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the Infinispan client to use. These clients are configured by means of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+long |
+required |
+
+
+
+
+
+
+Name of the cache that will be used in Infinispan when searching for related embeddings. If this cache doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The maximum distance. The most distance between vectors is how close or far apart two embeddings are. +
+
+Environment variable: |
+int |
+
|
+
The extension will create and register, both in the client and the server, the protobuf schema needed to serialize and store the indexable embeddings in Infinispan. +For example, for a dimension 384, the schema will register the following entity:
+/**
+ * @Indexed
+ */
+message LangchainItem384 {
+
+ /**
+ * @Keyword
+ */
+ optional string id = 1;
+
+ /**
+ * @Vector(dimension=384, similarity=COSINE)
+ */
+ repeated float floatVector = 2;
+
+ optional string text = 3;
+
+ repeated string metadataKeys = 4;
+
+ repeated string metadataValues = 5;
+}The cache in Infinispan must be an indexed cache. +If the cache does not exist, the following cache will be created. +Note that the cache configuration points to the schema containing the right size of the dimension depending on the use case.
+{
+ "embeddings-cache": {
+ "distributed-cache": {
+ "mode": "SYNC",
+ "remote-timeout": "17500",
+ "statistics": true,
+ "locking": {
+ "concurrency-level": "1000",
+ "acquire-timeout": "15000",
+ "striping": false
+ },
+ "indexing": {
+ "enabled": true,
+ "storage": "local-heap",
+ "indexed-entities": [
+ "LangchainItem384"
+ ]
+ },
+ "state-transfer": {
+ "timeout": "60000"
+ }
+ }
+ }
+}Large Language Models (LLMs) are advanced AI systems designed to comprehend, generate, and manipulate human language, enabling a wide array of natural language processing tasks. +These models utilize vast amounts of data to learn complex patterns and nuances within human language, enabling tasks like text generation, translation, and sentiment analysis. +LLMs, such as GPT-3 by OpenAI and BERT by Google, have substantially improved the understanding and generation of human language. +They serve as the backbone for chatbots, content generation, language translation, and even personalized content recommendation systems. +LLMs can be trained on colossal datasets, allowing them to understand context, grammar, and semantics, delivering responses that mimic human-like language. +They’re revolutionizing various industries, from customer service (with chatbots) to content creation and summarization for journalism or data analysis. +With their ability to understand the context and nuances of language, LLMs enable the automation of tasks that previously required human understanding.
+The size and complexity of these models demand significant computational resources for both training and deployment. +Ethical concerns and biases within LLMs are topics of ongoing discussion and research within the AI community. +Continued research and development in LLMs are constantly pushing the boundaries of what AI can achieve in language understanding and generation.
+LLMs are a core component of the Quarkus LangChain4j extension. +The extension does not serve its own LLMs, but rather provides a standard interface for interacting with many different LLMs such as OpenAI GPT-3/4, Hugging Face, and Ollama. +This interface is designed to be simple and intuitive, allowing developers to quickly integrate LLMs into their applications.
+Note that each LLM has a different feature set. +Please check the specific documentation for the LLM you are using to see what features are available:
+To use Ollama, you need to have a running Ollama server. +Go to the Ollama download page and download the server for your platform.
+Once installed, check that Ollama is running using:
+> ollama listIt may not display any model, which is fine, let’s pull the llama2 model:
> ollama pull llama2| + + | ++Models are huge. For example Llama2 is 3.8Gb. Make sure you have enough disk space. + | +
Let’s also pull the default embedding model:
+> ollama pull nomic-embed-text| + + | +
+ Dev Service
+
+
+If you have Ollama running locally, you do not need a dev service. +However, if you want to use the Ollama dev service, add the following dependency to your project: +
+
+
+
+
+
+Then, in your
+
+
+
+
+
+The dev service will start an Ollama server for you, using a docker container. Note that the provisioning can take some time. + |
+
To integrate with models running on Ollama, add the following dependency into your project:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-ollama</artifactId>
+ <version>0.9.0</version>
+</dependency>If no other LLM extension is installed, AI Services will automatically utilize the configured Ollama model.
+By default, the extension uses llama2, the model we pulled in the previous section.
+You can change it by setting the quarkus.langchain4j.ollama.chat-model.model-id property in the application.properties file:
# Do not forget to pull the model before using it using `ollama pull <model-id>`
+quarkus.langchain4j.ollama.chat-model.model-id=mistralSeveral configuration properties are available:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Base URL where the Ollama serving is running +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for Ollama calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+With a static number the result is always the same. With a random number the result varies Example: Random random = new Random(); int x = random.nextInt(Integer.MAX_VALUE); +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Base URL where the Ollama serving is running +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for Ollama calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the Ollama client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+With a static number the result is always the same. With a random number the result varies Example: Random random = new Random(); int x = random.nextInt(Integer.MAX_VALUE); +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Model to use. According to Ollama docs, the default value is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The temperature of the model. Increasing the temperature will make the model answer with more variability. A lower temperature will make the model answer more conservatively. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Maximum number of tokens to predict when generating text +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Sets the stop sequences to use. When this pattern is encountered the LLM will stop generating text and return +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Works together with top-k. A higher value (e.g., 0.95) will lead to more diverse text, while a lower value (e.g., 0.5) will generate more focused and conservative text +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Reduces the probability of generating nonsense. A higher value (e.g. 100) will give more diverse answers, while a lower value (e.g. 10) will be more conservative +
+
+Environment variable: |
+int |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Ollama also provides embedding models.
+By default, it uses nomic-embed-text (make sure you pulled that model as indicated in the prerequisites section).
You can change the default embedding model by setting the quarkus.langchain4j.ollama.embedding-model.model-id property in the application.properties file:
quarkus.langchain4j.ollama.log-requests=true
+quarkus.langchain4j.ollama.log-responses=true
+
+quarkus.langchain4j.ollama.chat-model.model-id=mistral
+quarkus.langchain4j.ollama.embedding-model.model-id=mistralIf no other LLM extension is installed, retrieve the embedding model as follows:
+@Inject EmbeddingModel model; // Injects the embedding modelHowever, in general, we recommend using local embedding models, as Ollama embeddings are rather slow.
+OpenAI stands as a pioneering AI research organization, famous for its groundbreaking Large Language Models (LLMs) like GPT-3 and GPT-4, setting new benchmarks in natural language understanding and generation.
+OpenAI’s LLMs offer extensive support for:
+Tools facilitating seamless interaction between the LLM and applications.
+Document retrievers enabling the transmission of pertinent content to the LLM.
+To employ OpenAI LLMs, integrate the following dependency into your project:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-openai</artifactId>
+ <version>0.9.0</version>
+</dependency>If no other LLM extension is installed, AI Services will automatically utilize the configured OpenAI model.
+Configuring OpenAI models mandates an API key, obtainable by creating an account on the OpenAI platform.
+The API key can be set in the application.properties file:
quarkus.langchain4j.openai.api-key=sk-...| + + | +
+Alternatively, leverage the QUARKUS_LANGCHAIN4J_OPENAI_API_KEY environment variable.
+ |
+
Several configuration properties are available:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the model should be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Base URL of OpenAI API +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenAI API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+OpenAI Organization ID (https://platform.openai.com/docs/api-reference/organization-optional) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for OpenAI calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of times to retry +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens can’t exceed the model’s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096). +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether embedding model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether embedding model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether moderation model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether moderation model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The path where the generated images will be persisted to disk. This only applies of
+
+Environment variable: |
+path |
+
|
+
+
+
+
+
+
+The format in which the generated images are returned. +
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The size of the generated images. +
+
+Must be one of
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The quality of the image that will be generated. +
+
+
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The number of images to generate. +
+
+Must be between 1 and 10. +
+
+When the model is dall-e-3, only n=1 is supported. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The style of the generated images. +
+
+Must be one of
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether image model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether image model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Base URL of OpenAI API +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenAI API key +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+OpenAI Organization ID (https://platform.openai.com/docs/api-reference/organization-optional) +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout for OpenAI calls +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of times to retry +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log requests +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the OpenAI client should log responses +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether or not to enable the integration. Defaults to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+What sampling temperature to use, with values between 0 and 2. Higher values means the model will take more risks. A value of 0.9 is good for more creative applications, while 0 (argmax sampling) is good for ones with a well-defined answer. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with topP probability mass. 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or topP, but not both. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens can’t exceed the model’s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096). +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Whether chat model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether chat model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The response format the model should use. Some models are not compatible with some response formats, make sure to review OpenAI documentation. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether embedding model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether embedding model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether moderation model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether moderation model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Model name to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure whether the generated images will be saved to disk. By default, persisting is disabled, but it is implicitly enabled when
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The path where the generated images will be persisted to disk. This only applies of
+
+Environment variable: |
+path |
+
|
+
+
+
+
+
+
+The format in which the generated images are returned. +
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The size of the generated images. +
+
+Must be one of
+
+Must be one of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The quality of the image that will be generated. +
+
+
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The number of images to generate. +
+
+Must be between 1 and 10. +
+
+When the model is dall-e-3, only n=1 is supported. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The style of the generated images. +
+
+Must be one of
+
+This param is only supported for when the model is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether image model requests should be logged +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether image model responses should be logged +
+
+Environment variable: |
+boolean |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
When utilizing OpenAI models, the recommended practice involves leveraging the OpenAiEmbeddingModel. If no other LLM extension is installed, retrieve the embedding model as follows:
@Inject EmbeddingModel model; // Injects the OpenAIEmbeddingModel| + + | +
+The OpenAIEmbeddingModel transmits the document to OpenAI for embedding computation.
+ |
+
Applications can leverage the Azure’s version of OpenAI services simply by using the quarkus-langchain4j-azure-openai extension instead of the quarkus-langchain4j-openai extension.
When this extension is used, the following configuration properties are required:
+quarkus.langchain4j.azure-openai.api-key=
+quarkus.langchain4j.azure-openai.resource-name=
+quarkus.langchain4j.azure-openai.deployment-name=quarkus-langchain4j-openai and quarkus-langchain4j-azure-openai extensions use a REST Client under the hood to make the REST calls required by LangChain4j.
+This client is however available for use in a Quarkus application in the same way as any other REST client.
An example usage is the following:
+import java.net.URI;
+import java.net.URISyntaxException;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+import org.jboss.resteasy.reactive.RestStreamElementType;
+
+import dev.ai4j.openai4j.chat.ChatCompletionChoice;
+import dev.ai4j.openai4j.chat.ChatCompletionResponse;
+import dev.ai4j.openai4j.chat.Delta;
+import dev.ai4j.openai4j.chat.Message;
+import dev.ai4j.openai4j.completion.CompletionChoice;
+import dev.ai4j.openai4j.completion.CompletionResponse;
+import io.quarkiverse.langchain4j.openai.OpenAiRestApi;
+import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
+import io.smallrye.mutiny.Multi;
+
+
+@Path("restApi")
+@ApplicationScoped
+public class QuarkusRestApiResource {
+
+ private final OpenAiRestApi restApi;
+ private final String token;
+
+ public QuarkusRestApiResource() throws URISyntaxException {
+ this.restApi = QuarkusRestClientBuilder.newBuilder()
+ .baseUri(new URI("https://api.openai.com/v1/"))
+ .build(OpenAiRestApi.class);
+ this.token = "sometoken";
+
+ }
+
+ @GET
+ @Path("language/streaming")
+ @RestStreamElementType(MediaType.TEXT_PLAIN)
+ public Multi<String> languageStreaming() {
+ return restApi.streamingCompletion(
+ createCompletionRequest("Write a short 1 paragraph funny poem about Enterprise Java"), token, null)
+ .map(r -> {
+ if (r.choices() != null) {
+ if (r.choices().size() == 1) {
+ CompletionChoice choice = r.choices().get(0);
+ var text = choice.text();
+ if (text != null) {
+ return text;
+ }
+ }
+ }
+ return "";
+ });
+ }
+}This example allows for streaming OpenAIs response back to the user’s browser as Server Sent Events.
+| + + | +
+
+
+We used |
+
When implementing Retrieval Augmented Generation (RAG), a capable document store is necessary. This guide will explain how to leverage a pgvector database as the document store.
+To utilize the Redis document store, you’ll need to include the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-pgvector</artifactId>
+ <version>0.9.0</version>
+</dependency>This extension will check for a default datasource, ensure you have defined at least one datasource. For detailed guidance, refer to the CONFIGURE DATA SOURCES IN QUARKUS.
+| + + | +
+If you plan to use devservices be sure to use this property : quarkus.datasource.devservices.image-name=ankane/pgvector:v0.5.1.
+ |
+
| + + | +
+The pgvector store requires the dimension of the vector to be set. Add the quarkus.langchain4j.pgvector.dimension property to your application.properties file and set it to the dimension of the vector. The dimension depends on the embedding model you use.
+For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536.
+ |
+
Upon installing the extension, you can utilize the pgvector store using the following code:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.splitter.DocumentSplitters.recursive;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
+import io.quarkiverse.langchain4j.pgvector.PgVectorEmbeddingStore;
+
+@ApplicationScoped
+public class IngestorExampleWithPgvector {
+
+ /**
+ * The embedding store (the database).
+ * The bean is provided by the quarkus-langchain4j-pgvector extension.
+ */
+ @Inject
+ PgVectorEmbeddingStore store;
+
+ /**
+ * The embedding model (how is computed the vector of a document).
+ * The bean is provided by the LLM (like openai) extension.
+ */
+ @Inject
+ EmbeddingModel embeddingModel;
+
+ public void ingest(List<Document> documents) {
+ EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store)
+ .embeddingModel(embeddingModel)
+ .documentSplitter(recursive(500, 0))
+ .build();
+ // Warning - this can take a long time...
+ ingestor.ingest(documents);
+ }
+}Customize the behavior of the extension by exploring various configuration options:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the configured Postgres datasource to use for this store. If not set, the default datasource from the Agroal extension will be used. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The table name for storing embeddings +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+int |
+required |
+
+
+
+
+
+
+Use index or not +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+index size +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Create table or not +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Drop table or not +
+
+Environment variable: |
+boolean |
+
|
+
When implementing Retrieval Augmented Generation (RAG), a robust document store is crucial. This guide demonstrates how to leverage a Pinecone database as the document store.
+To make use of the Pinecone document store, you’ll need to include the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-pinecone</artifactId>
+</dependency>Customize the behavior of the extension by exploring various configuration options:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The API key to Pinecone. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Environment name, e.g. gcp-starter or northamerica-northeast1-gcp. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+ID of the project. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Name of the index within the project. If the index doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Dimension of the embeddings in the index. This is required only in case that the index doesn’t exist yet and needs to be created. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The type of the pod to use. This is only used if the index doesn’t exist yet and needs to be created. The format: One of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the index to become ready. Only relevant if the index doesn’t exist yet and needs to be created. If not specified, 1 minute will be used. +
+
+Environment variable: |
+Duration + |
++ |
+
+
+
+
+
+The namespace. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The name of the field that contains the text segment. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The timeout duration for the Pinecone client. If not specified, 5 seconds will be used. +
+
+Environment variable: |
+Duration + |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Prompt engineering involves crafting inputs for language models to elicit specific behaviors or responses. +It plays a pivotal role in directing the sequence of actions and outcomes generated by the model.
+This page lists a few techniques that can be used to guide the model in performing specific tasks or sequences of actions.
+Input delimiters play a vital role in structuring the instructions for the language model. They mark the boundaries between different sections or segments of the prompt, guiding the model in processing distinct pieces of information.
+For instance, hyphens (---) or similar markers delineate various components within the prompt, aiding the model in discerning user input, intermediate steps, and the final actions to be executed.
Objective: Write a summary of the text delimited by ---
+
+---
+{text}
+---Text is the user text (method parameter in an AI Service). +Input delimiters also avoids prompt injections.
+Few-shot learning techniques are instrumental in training models to comprehend and generate output based on a limited number of examples or demonstrations. +This approach involves presenting the model with a handful of examples, allowing it to generalize and adapt to similar scenarios.
+By strategically crafting a few-shot prompt that includes diverse yet concise samples of the desired actions, one can guide the model to understand and execute tasks based on the provided exemplars.
+Using a few-shot technique guides a model to understand sentiment analysis based on minimal examples:
+Provide sentiment labels for the statements delimited by ---
+The response must be either 'Positive', 'Neutral', or 'Negative'.
+
+Here are a few examples:
+- 'I love this product' - Positive
+- 'Not bad, but could be better' - Neutral
+- 'I'm thoroughly disappointed' - Negative
+
+---
+{text}
+---In this example, the model is presented with a few labeled statements to learn sentiment analysis, followed by a new {text} to analyze.
To instruct a language model to perform a sequence of actions, a carefully structured prompt containing a list of actions is essential. This involves delineating each action along with its associated tool and parameters within the prompt.
+For example, a structured list could entail a set of instructions such as:
+Action 1: Tool A with parameters X, Y
+Action 2: Tool B with parameters Z
+Action 3: Tool C with parameter WGuiding the model through a well-defined sequence of actions within the prompt facilitates the execution of a chain of tasks or tools.
+For example:
+Objective: Perform a series of data processing tasks:
+
+Task 1: CleanData with parameters {method: 'standard', missing_values: 'drop'}
+Task 2: ScaleData with parameters {method: 'min-max', feature_range: (0, 1)}
+Task 3: ApplyModel with parameters {model: 'random-forest', features: 'all'}"Here, the prompt instructs the model to execute a sequence of data processing task involving data cleaning, scaling, and model application. +Each task is defined by a tool and its associated parameters.
+Prompt engineering can also involve requesting specific structured data formats, such as JSON, from the language model. +In this scenario, specifying the expected JSON keys aids the model in generating the desired output structure:
+Objective: Generate a JSON response with specific keys:
+
+JSON Structure:
+{
+ 'name': 'String',
+ 'age': 'Number',
+ 'email': 'String',
+ 'address': {
+ 'street': 'String',
+ 'city': 'String',
+ 'zip_code': 'String'
+ }
+}
+
+Provided Data: John Doe, 30, john@example.com, 123 Main St, New York, 10001In this example, the prompt specifies the expected structure for the JSON response, comprising keys like name, age, email, and address, with their respective value types. The Provided Data segment serves as the input to be formatted into the requested JSON structure.
Being able to describe the JSON output is essential when an AI method returns an object.
+Even if a JSON format is not directly provided by the developer in the prompt, the LangChain4j will automatically add it, and the Quarkus LangChain4j extension will use the JSON structure to create an instance of the return type.
+In this case, when working with JSON formats, it’s good to specify this fact in a prompt and always ask for a valid and unwrapped JSON, for example:
+You must respond in a valid JSON format.
+You must not wrap JSON response in backticks, markdown, or in any other way, but return it as plain text.Control tokens or prefixes within prompts guide the model’s behavior. For example:
+Answer: What is the capital of France?Here, the prefix Answer: directs the model to provide the solution to the question that follows.
Using domain-specific language or vocabulary in prompts enhances the model’s understanding within a specific domain. +For instance:
+Medicine: List the symptoms and treatment for strep throat.Employing domain-specific terms like Medicine ensures the model addresses medical-related queries specifically.
+These techniques offer additional methods to direct language models effectively, providing further insight and control over their output.
In relation to the previous technique, giving a role to the AI is a technique that involves assigning a specific role to the language model, such as a teacher, student, or assistant. +This is generally done in the system message to guide the model’s behavior:
+@SystemMessage("""
+ You are a bank account fraud detection AI. You have to detect frauds in transactions.
+""")When implementing Retrieval Augmented Generation (RAG), a capable document store is necessary. This guide will explain how to leverage a Redis database as the document store.
+To utilize the Redis document store, you’ll need to include the following dependency:
+<dependency>
+ <groupId>io.quarkiverse.langchain4j</groupId>
+ <artifactId>quarkus-langchain4j-redis</artifactId>
+ <version>0.9.0</version>
+</dependency>This extension relies on the Quarkus Redis client. Ensure the default Redis datasource is configured appropriately. For detailed guidance, refer to the Quarkus Redis Quickstart and the Quarkus Redis Reference.
+| + + | +
+The Redis document store’s functionality is built on the Redis JSON and Redis Search modules. Ensure these modules are installed, or consider using the Redis Stack. When the quarkus-langchain4j-redis extension is present, the default image used for Redis is redis-stack:latest but this can be changed by setting quarkus.redis.devservices.image-name=someotherimage in your application.properties file.
+ |
+
| + + | +
+The Redis document store requires the dimension of the vector to be set. Add the quarkus.langchain4j.redis.dimension property to your application.properties file and set it to the dimension of the vector. The dimension depends on the embedding model you use.
+For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536.
+ |
+
Upon installing the extension, you can utilize the Redis document store using the following code:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.splitter.DocumentSplitters.recursive;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
+import io.quarkiverse.langchain4j.redis.RedisEmbeddingStore;
+
+@ApplicationScoped
+public class IngestorExampleWithRedis {
+
+ /**
+ * The embedding store (the database).
+ * The bean is provided by the quarkus-langchain4j-redis extension.
+ */
+ @Inject
+ RedisEmbeddingStore store;
+
+ /**
+ * The embedding model (how is computed the vector of a document).
+ * The bean is provided by the LLM (like openai) extension.
+ */
+ @Inject
+ EmbeddingModel embeddingModel;
+
+ public void ingest(List<Document> documents) {
+ EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store)
+ .embeddingModel(embeddingModel)
+ .documentSplitter(recursive(500, 0))
+ .build();
+ // Warning - this can take a long time...
+ ingestor.ingest(documents);
+ }
+}By default, the extension utilizes the default Redis datasource for storing and indexing the documents. Customize the behavior of the extension by exploring various configuration options:
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The name of the Redis client to use. These clients are configured by means of the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The dimension of the embedding vectors. This has to be the same as the dimension of vectors produced by the embedding model that you use. For example, AllMiniLmL6V2QuantizedEmbeddingModel produces vectors of dimension 384. OpenAI’s text-embedding-ada-002 produces vectors of dimension 1536. +
+
+Environment variable: |
+long |
+required |
+
+
+
+
+
+
+Name of the index that will be used in Redis when searching for related embeddings. If this index doesn’t exist, it will be created. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Names of extra fields that will be stored in Redis along with the embedding vectors. This corresponds to keys in the
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Metric used to compute the distance between two vectors. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Name of the key that will be used to store the embedding vector. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the key that will be used to store the embedded text. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Prefix to be applied to all keys by the embedding store. Embeddings are stored in Redis under a key that is the concatenation of this prefix and the embedding ID. +
+
+If the configured prefix does not ends with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Algorithm used to index the embedding vectors. +
+
+Environment variable: |
+
+
|
+
|
+
Many applications involving Large Language Models (LLMs) often require user-specific data beyond their training set, such as CSV files, data from various sources, or reports. To achieve this, the process of Retrieval Augmented Generation (RAG) is commonly employed.
+Before delving into the RAG process, it’s crucial to delineate two distinct phases:
+Involves data collection, cleaning, transformation, and adding metadata, resulting in a set of vectorized documents stored in a database.
+Before engaging with the LLM, it seeks relevant documents in the database and passes them for model augmentation.
+
+Embeddings denote data representations, typically in a lower-dimensional space (arrays of floats), preserving essential characteristics of the original data. In the realm of language or text, word embeddings represent words as numerical vectors in a continuous space.
+| + + | +
+ Why Use Vectors/Embeddings?
+Efficiently comparing documents to user queries during the RAG process, a crucial step in finding relevant documents, relies on computing similarity (or distance) between documents and queries. Vectorizing documents significantly speeds up this process.
+ |
+
The ingestion process varies based on the data source, operating as a one-shot or continuous process, possibly within a data streaming architecture where each message is treated as a document.
+To illustrate document creation, the following code exemplifies creating a Document from a text file:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.loader.FileSystemDocumentLoader.loadDocument;
+
+import java.io.File;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.data.document.parser.TextDocumentParser;
+
+public class DocumentFromTextCreationExample {
+
+ Document createDocument(File file) {
+ return loadDocument(file.toPath(), new TextDocumentParser());
+ }
+}A more complex scenario involves creating a Document from a CSV line:
+package io.quarkiverse.langchain4j.samples;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.data.document.Metadata;
+
+public class DocumentCreationExample {
+
+ Document createFromCSVLine(List<String> headers, List<String> line,
+ List<String> columnsToIncludeInMetadata) {
+ Map<String, String> metadata = new HashMap<>();
+ var content = new StringBuilder();
+ for (int i = 0; i < headers.size(); i++) {
+ var columnName = headers.get(i);
+ var value = line.get(i).trim();
+
+ if (columnName.trim().isEmpty()) {
+ continue;
+ }
+
+ if (columnsToIncludeInMetadata.contains(columnName)) {
+ metadata.put(columnName, value);
+ }
+ // We compute a Text format for the CSV line: key: value, key: value, ...
+ content.append(columnName).append(": ").append(value).append(", ");
+ }
+ // The \n is added to the end of the content
+ return new Document(content.append("\n").toString(), Metadata.from(metadata));
+ }
+
+}Following document creation, the documents need to be ingested. The Quarkus LangChain4j extension offers ingestor components for database storage. +For instance, quarkus-langchain4j-redis stores data in a Redis database, while quarkus-langchain4j-chroma uses a Chroma database.
+The following code demonstrates document ingestion in a Redis database:
+package io.quarkiverse.langchain4j.samples;
+
+import static dev.langchain4j.data.document.splitter.DocumentSplitters.recursive;
+
+import java.util.List;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import dev.langchain4j.data.document.Document;
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
+import io.quarkiverse.langchain4j.redis.RedisEmbeddingStore;
+
+@ApplicationScoped
+public class IngestorExampleWithRedis {
+
+ /**
+ * The embedding store (the database).
+ * The bean is provided by the quarkus-langchain4j-redis extension.
+ */
+ @Inject
+ RedisEmbeddingStore store;
+
+ /**
+ * The embedding model (how is computed the vector of a document).
+ * The bean is provided by the LLM (like openai) extension.
+ */
+ @Inject
+ EmbeddingModel embeddingModel;
+
+ public void ingest(List<Document> documents) {
+ EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
+ .embeddingStore(store)
+ .embeddingModel(embeddingModel)
+ .documentSplitter(recursive(500, 0))
+ .build();
+ // Warning - this can take a long time...
+ ingestor.ingest(documents);
+ }
+}Adjust the documentSplitter parameter based on the data structure.
+For instance, for CSV files with document representation separated by \n, new DocumentByLineSplitter(500, 0) is a recommended starting point.
Once documents are ingested, they can augment the LLM’s capabilities. The following code illustrates the creation of a RetrievalAugmentor:
package io.quarkiverse.langchain4j.samples;
+
+import java.util.function.Supplier;
+
+import jakarta.inject.Singleton;
+
+import dev.langchain4j.model.embedding.EmbeddingModel;
+import dev.langchain4j.rag.DefaultRetrievalAugmentor;
+import dev.langchain4j.rag.RetrievalAugmentor;
+import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
+import io.quarkiverse.langchain4j.redis.RedisEmbeddingStore;
+
+@Singleton
+public class RetrievalAugmentorExample implements Supplier<RetrievalAugmentor> {
+
+ private final RetrievalAugmentor augmentor;
+
+ RetrievalAugmentorExample(RedisEmbeddingStore store, EmbeddingModel model) {
+ EmbeddingStoreContentRetriever contentRetriever = EmbeddingStoreContentRetriever.builder()
+ .embeddingModel(model)
+ .embeddingStore(store)
+ .maxResults(3)
+ .build();
+ augmentor = DefaultRetrievalAugmentor
+ .builder()
+ .contentRetriever(contentRetriever)
+ .build();
+ }
+
+ @Override
+ public RetrievalAugmentor get() {
+ return augmentor;
+ }
+
+}| + + | +
+This is the simplest example of retrieval augmentor, which only uses a
+EmbeddingStoreContentRetriever to retrieve documents from an embedding
+store to pass them directly to the LLM. A retrieval augmentor can use more
+sophisticated strategies to process queries, such as query compression,
+splitting a query into multiple queries and then routing them via different
+content retrievers (which may or may not be based on vector storage, but for
+example on a full-text search engine), using a scoring model to further
+filter the retrieved results, etc. For more information about advanced RAG
+strategies, refer to https://docs.langchain4j.dev/tutorials/rag/.
+ |
+
The example above is a CDI bean that implements
+Supplier<RetrievalAugmentor>. An alternative way to wire things up is to
+create a CDI bean that directly implements RetrievalAugmentor, for example
+via a CDI producer, and letting Quarkus auto-discover it (by not specifying
+the retrievalAugmentor parameter of the @RegisterAiService annotation).
The EmbeddingStoreContentRetriever necessitates a configured embedding store +(Redis, Chroma, etc.) and an embedding model. Configure the maximum number +of documents to retrieve (e.g., 3 in the example) and set the minimum +relevance score if required.
+Make sure that the number of documents is not too high (or document too large). +More document you have, more data you are adding to the LLM context, and you may exceed the limit.
+An AI service does not use a retrieval augmentor by default, one needs to be configured explicitly via the retrievalAugmentor property of @RegisterAiService and the configured
+Supplier<RetrievalAugmentor> is expected to be a CDI bean.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the JSON console formatting extension, which disables "normal" console formatting. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Determine whether to enable the JSON file formatting extension, which disables "normal" file formatting. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Used to wrap arguments in an json object, with this fieldName on root json. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable output of structured logging arguments
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable output of non structured logging arguments, default is false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+What prefix to use, when outputting non structured arguments. Default is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The date format to use. The special string "default" indicates that the default format should be used. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The zone to use when formatting the timestamp. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Will write the values at the top level of the JSON log object. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable "pretty printing" of the JSON record. Note that some JSON parsers will fail to read pretty printed output. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The special end-of-record delimiter to be used. By default, newline delimiter is used. +
+
+Environment variable: |
+string |
+` +` |
+
+
+
+
+
+
+Support changing logging format. +
+
+Environment variable: |
+
+
|
+
|
+
For adding fields to the json output directly from the config |
+Type |
+Default |
+
+
+
+
+
+
+Additional field value. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Type of the field, default is STRING. Supported types: STRING, INT, LONG, FLOAT, DOUBLE. +
+
+Environment variable: |
+
+
|
+
|
+
Quarkus logging extension outputting the logging in JSON.
+If you want to use this extension, you need to add the quarkus-logging-json extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.loggingjson</groupId>
+ <artifactId>quarkus-logging-json</artifactId>
+ <version>3.0.0</version>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the JSON console formatting extension, which disables "normal" console formatting. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Determine whether to enable the JSON file formatting extension, which disables "normal" file formatting. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Used to wrap arguments in an json object, with this fieldName on root json. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable output of structured logging arguments
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable output of non structured logging arguments, default is false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+What prefix to use, when outputting non structured arguments. Default is
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The date format to use. The special string "default" indicates that the default format should be used. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The zone to use when formatting the timestamp. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Will write the values at the top level of the JSON log object. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Used to change the json key for the field. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enable or disable the field. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Enable "pretty printing" of the JSON record. Note that some JSON parsers will fail to read pretty printed output. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The special end-of-record delimiter to be used. By default, newline delimiter is used. +
+
+Environment variable: |
+string |
+` +` |
+
+
+
+
+
+
+Support changing logging format. +
+
+Environment variable: |
+
+
|
+
|
+
For adding fields to the json output directly from the config |
+Type |
+Default |
+
+
+
+
+
+
+Additional field value. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Type of the field, default is STRING. Supported types: STRING, INT, LONG, FLOAT, DOUBLE. +
+
+Environment variable: |
+
+
|
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way. + |
+list of string |
+
|
+
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located + |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. + |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. + |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. + |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. + |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. + |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. + |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname + |
+
|
++ |
This extension allows you to use Logback to configure Quarkus logging via logback.xml. This extension parses the config
+file at build time, and then bridges the resulting config with jboss-logmanager.
If you want to use this extension, you need to add the io.quarkiverse.logging.logback:quarkus-logging-logback extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.logging.logback</groupId>
+ <artifactId>quarkus-logging-logback</artifactId>
+</dependency>This extension does not actually replace jboss-logmanager as the default logging engine, instead it bridges to the two, +to allow them to co-exist. JBoss Logging is still the core logmanager for Quarkus, however any logging events it receives +are also sent to the logback and will be sent through any logback appenders.
+Log levels for loggers are also parsed, and are used to set the default log level for the corresponding jboss-logmanager
+loggers. These defaults can still be overriden however, so if you set a log level in application.properties it will take
+precidence.
If a console appender is detected in logback.xml then the standard Quarkus console logging is disabled, to prevent double
+logging of messages, otherwise it is left enabled and will work as normal.
You may see an error similar to below:
+SLF4J: Class path contains multiple SLF4J bindings.
+SLF4J: Found binding in [jar:file:/home/stuart/.m2/repository/ch/qos/logback/logback-classic/1.2.3/logback-classic-1.2.3.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: Found binding in [jar:file:/home/stuart/.m2/repository/org/jboss/slf4j/slf4j-jboss-logmanager/1.1.0.Final/slf4j-jboss-logmanager-1.1.0.Final.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
+SLF4J: Actual binding is of type [ch.qos.logback.classic.util.ContextSelectorStaticBinder]To get around this you need to exclude the ch.qos.logback:logback-classic artifact from your project. Quarkus will automatically
+bring in a modified version at runtime that has had the SLF4J binding removed. Run mvn dependency:tree to figure out what is
+bringing in the artifact, and then exclude it from the pom.xml.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the Sentry logging extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Sentry DSN The DSN is the first and most important thing to configure because it tells the SDK where to send events. You can find your project’s DSN in the “Client Keys” section of your “Project Settings” in Sentry. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sentry log level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The minimum event level. Every log statement that is greater than minimum event level is turned into Sentry event. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The minimum breadcrumb level. Every log statement that is greater than minimum breadcrumb level is added to Sentry scope as a breadcrumb, which can be later attached to SentryEvent if one is triggered. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Sentry differentiates stack frames that are directly related to your application (“in application”) from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The difference is visible in the Sentry web interface where only the “in application” frames are displayed by default. You can configure which package prefixes your application uses with this option. This option is highly recommended as it affects stacktrace grouping and display on Sentry. See documentation: https://quarkus.io/guides/logging-sentry#in-app-packages +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Environment With Sentry you can easily filter issues, releases, and user feedback by environment. The environment filter on sentry affects all issue-related metrics like count of users affected, times series graphs, and event count. By setting the environment option, an environment tag will be added to each new issue sent to Sentry. There are a few restrictions: → the environment name cannot contain newlines or spaces, cannot be the string “None” or exceed 64 characters. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Release A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you unlock a number of new features: - Determine the issues and regressions introduced in a new release - Predict which commit caused an issue and who is likely responsible - Resolve issues by including the issue number in your commit message - Receive email notifications when your code gets deployed +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Server name Sets the server name that will be sent with each event. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Debug Enables Sentry debug mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+This should be a float/double between 0.0 and 1.0 (inclusive) and represents the percentage chance that any given transaction will be sent to Sentry. So, barring outside influence, 0.0 is a 0% chance (none will be sent) and 1.0 is a 100% chance (all will be sent). This rate applies equally to all transactions. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Context Tags Specifics the MDC tags that are used as Sentry tags +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Determine whether to enable a Proxy for all Sentry outbound requests. This is also used for HTTPS requests. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Sets the host name of the proxy server. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the port number of the proxy server +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the username to authenticate on the proxy server +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the password to authenticate on the proxy server +
+
+Environment variable: |
+string |
++ |
This guide explains how to configure Quarkus to log to Sentry.
+Sentry is a really easy way to be notified of errors happening in your Quarkus application.
+It is a self-hosted and cloud-based error monitoring that helps software teams discover, triage, and prioritize errors in real-time.
+They offer a free starter price for cloud-based or you can self host it for free.
+| + + | ++Sentry’s Java SDK is open source, but recently sentry.io changed the license for their backend to the non-open source BSL license. This might or might not be an issue for your project and product. + | +
To start with, you need to get a Sentry DSN either by creating a Sentry account or installing your own self-hosted Sentry.
+In order to configure Sentry logging, add the logging-sentry extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="logging-sentry"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.loggingsentry</groupId>
+ <artifactId>quarkus-logging-sentry</artifactId>
+ <version>2.0.4</version>
+</dependency>Sentry differentiates stack frames that are directly related to your application (“in application”) from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The difference is visible in the Sentry web interface where only the “in application” frames are displayed by default.
+You can configure which package prefixes your application uses with the in-app-packages option, which takes a comma separated list of packages:
quarkus.log.sentry.in-app-packages=com.mycompany,com.other.nameIf you don’t want to use this feature but want to disable the warning, simply set it to *:
quarkus.log.sentry.in-app-packages=*https://abcd@sentry.io/1234quarkus.log.sentry=true
+quarkus.log.sentry.dsn=https://abcd@sentry.io/1234
+quarkus.log.sentry.in-app-packages=*org.example will be sent to Sentry with DSN https://abcd@sentry.io/1234quarkus.log.sentry=true
+quarkus.log.sentry.dsn=https://abcd@sentry.io/1234
+quarkus.log.sentry.level=ERROR
+quarkus.log.sentry.in-app-packages=org.exampleSentry events can be customised before transmission using Sentry’s builtin BeforeSendCallback interface.
+Any application-scoped bean marked with the interface will be called. This can be used to add data to the event as well as completely suppressing the event.
+Make sure to mark beans as unremovable.
@ApplicationScoped
+@Unremovable
+public class SentryCallbackHandler implements SentryOptions.BeforeSendCallback {
+ @Override
+ public SentryEvent execute(SentryEvent sentryEvent, Hint hint) {
+ return sentryEvent; // event unchanged
+ }
+}This extension is configured through the standard application.properties file.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the Sentry logging extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Sentry DSN The DSN is the first and most important thing to configure because it tells the SDK where to send events. You can find your project’s DSN in the “Client Keys” section of your “Project Settings” in Sentry. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The sentry log level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The minimum event level. Every log statement that is greater than minimum event level is turned into Sentry event. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+The minimum breadcrumb level. Every log statement that is greater than minimum breadcrumb level is added to Sentry scope as a breadcrumb, which can be later attached to SentryEvent if one is triggered. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Sentry differentiates stack frames that are directly related to your application (“in application”) from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The difference is visible in the Sentry web interface where only the “in application” frames are displayed by default. You can configure which package prefixes your application uses with this option. This option is highly recommended as it affects stacktrace grouping and display on Sentry. See documentation: https://quarkus.io/guides/logging-sentry#in-app-packages +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Environment With Sentry you can easily filter issues, releases, and user feedback by environment. The environment filter on sentry affects all issue-related metrics like count of users affected, times series graphs, and event count. By setting the environment option, an environment tag will be added to each new issue sent to Sentry. There are a few restrictions: → the environment name cannot contain newlines or spaces, cannot be the string “None” or exceed 64 characters. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Release A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you unlock a number of new features: - Determine the issues and regressions introduced in a new release - Predict which commit caused an issue and who is likely responsible - Resolve issues by including the issue number in your commit message - Receive email notifications when your code gets deployed +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Server name Sets the server name that will be sent with each event. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Debug Enables Sentry debug mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+This should be a float/double between 0.0 and 1.0 (inclusive) and represents the percentage chance that any given transaction will be sent to Sentry. So, barring outside influence, 0.0 is a 0% chance (none will be sent) and 1.0 is a 100% chance (all will be sent). This rate applies equally to all transactions. +
+
+Environment variable: |
+double |
++ |
+
+
+
+
+
+Context Tags Specifics the MDC tags that are used as Sentry tags +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Determine whether to enable a Proxy for all Sentry outbound requests. This is also used for HTTPS requests. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Sets the host name of the proxy server. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the port number of the proxy server +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Sets the username to authenticate on the proxy server +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Sets the password to authenticate on the proxy server +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the handler +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The splunk handler log level. By default, it is no more strict than the root handler level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Splunk HEC endpoint base url. +
+
+With raw events, the endpoint targeted is /services/collector/raw. With flat or nested JSON events, the endpoint targeted is /services/collector/event/1.0. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable TLS certificate validation with HEC endpoint +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The application token to authenticate with HEC, the token is mandatory if the extension is enabled https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#HEC_token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The strategy to send events to HEC. +
+
+In sequential mode, there is only one HTTP connection to HEC and the order of events is preserved, but performance is lower. In parallel mode, event batches are sent asynchronously over multiple HTTP connections, and events with the same timestamp (that has 1 millisecond resolution) may be indexed out of order by Splunk. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+A GUID to identify an HEC client and guarantee isolation at HEC level in case of slow clients. https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck#About_channels_and_sending_data +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Batching delay before sending a group of events. If 0, the events are sent immediately. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Maximum number of events in a batch. By default 10, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum total size in bytes of events in a batch. By default 10KB, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum number of retries in case of I/O exceptions with HEC connection. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The log format, defining which metadata are inlined inside the log main payload. +
+
+Specific metadata (hostname, category, thread name, …), as well as MDC key/value map, can also be sent in a structured way. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether to send the thrown exception message as a structured metadata of the log event (as opposed to %e in a formatted message, it does not include the exception name or stacktrace). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the logger name as a structured metadata of the log event (equivalent of %c in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the thread name as a structured metadata of the log event (equivalent of %t in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Overrides the host name metadata value. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The source value to assign to the event data. For example, if you’re sending data from an app you’re developing, you could set this key to the name of the app. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The optional format of the events, to enable some parsing on Splunk side. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+A given source type may have indexed fields extraction enabled, which is the case of the built-in _json used for nested serialization. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The optional name of the index by which the event data is to be stored. If set, it must be within the list of allowed indexes of the token (if it has the indexes parameter set). https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The name of the key used to convey the severity / log level in the metadata fields. Only applicable to 'flat' serialization. With 'nested' serialization, there is already a 'severity' field. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The format of the payload. +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Indicates whether to log asynchronously +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The queue length to use before flushing writing +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Determine whether to block the publisher (rather than drop the message) when the queue is full +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Optional static key/value pairs to populate the "fields" key of event metadata. This isn’t applicable to raw serialization. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Determine whether to enable the handler +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The splunk handler log level. By default, it is no more strict than the root handler level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Splunk HEC endpoint base url. +
+
+With raw events, the endpoint targeted is /services/collector/raw. With flat or nested JSON events, the endpoint targeted is /services/collector/event/1.0. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable TLS certificate validation with HEC endpoint +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The application token to authenticate with HEC, the token is mandatory if the extension is enabled https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#HEC_token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The strategy to send events to HEC. +
+
+In sequential mode, there is only one HTTP connection to HEC and the order of events is preserved, but performance is lower. In parallel mode, event batches are sent asynchronously over multiple HTTP connections, and events with the same timestamp (that has 1 millisecond resolution) may be indexed out of order by Splunk. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+A GUID to identify an HEC client and guarantee isolation at HEC level in case of slow clients. https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck#About_channels_and_sending_data +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Batching delay before sending a group of events. If 0, the events are sent immediately. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Maximum number of events in a batch. By default 10, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum total size in bytes of events in a batch. By default 10KB, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum number of retries in case of I/O exceptions with HEC connection. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The log format, defining which metadata are inlined inside the log main payload. +
+
+Specific metadata (hostname, category, thread name, …), as well as MDC key/value map, can also be sent in a structured way. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether to send the thrown exception message as a structured metadata of the log event (as opposed to %e in a formatted message, it does not include the exception name or stacktrace). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the logger name as a structured metadata of the log event (equivalent of %c in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the thread name as a structured metadata of the log event (equivalent of %t in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Overrides the host name metadata value. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The source value to assign to the event data. For example, if you’re sending data from an app you’re developing, you could set this key to the name of the app. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The optional format of the events, to enable some parsing on Splunk side. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+A given source type may have indexed fields extraction enabled, which is the case of the built-in _json used for nested serialization. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The optional name of the index by which the event data is to be stored. If set, it must be within the list of allowed indexes of the token (if it has the indexes parameter set). https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional static key/value pairs to populate the "fields" key of event metadata. This isn’t applicable to raw serialization. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+The name of the key used to convey the severity / log level in the metadata fields. Only applicable to 'flat' serialization. With 'nested' serialization, there is already a 'severity' field. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The format of the payload. +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Indicates whether to log asynchronously +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The queue length to use before flushing writing +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Determine whether to block the publisher (rather than drop the message) when the queue is full +
+
+Environment variable: |
+
+
|
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
Splunk is a middleware +solution that receives, stores, indexes and finally allows to exploit the logs of an application.
+This Quarkus extension provides the support of the official Splunk client library to index log events through the HTTP Event collection, provided by Splunk enterprise solution.
+If you want to use this extension, you need to add the quarkus-logging-splunk extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.logging.splunk</groupId>
+ <artifactId>quarkus-logging-splunk</artifactId>
+ <version>{project-version}</version>
+</dependency>The extension can be used transparently with any log frontend used by Quarkus (Log4j, SLF4J, … ).
+In all cases the log message formatter is aligned by default with the one of Quarkus console handler:
+quarkus.log.handler.splunk.format="%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n"This can be adapted in order to avoid duplication with metadata that are passed in a structured way.
+The type of metadata depends on the serialization format.
+If quarkus.log.handler.splunk.raw is enabled or quarkus.log.handler.splunk.serialization is raw, there are no per-event metadata.
+Only few global metadata shared between all events of a batch are sent via HTTP headers and query parameters.
In other cases, the extension uses structured logging, via JSON serialization. +There are two supported structured formats:
+The nested serialization is the default format of Splunk HEC Java client and defines the name of some pre-defined metadata. Combined with quarkus.log.handler.splunk.format=%s%e it also support log messages that are themselves JSON.
The flat serialization is a simpler and more generic format, also used by the OpenTelemetry Splunk HEC exporter.
Some metadata can be indexed by Splunk, see indexed fields.
+The default _json source type indexes metadata passed in the fields object.
The extension provides the support of the resolution of MDC scoped properties, as defined in JBoss supported formatters.
+| Serialization format | +nested |
+flat |
+
|---|---|---|
HEC metadata |
+
+
|
+|
Pre-defined metadata |
+
+
+Only
+
|
+
+
+Only
+
|
+
MDC properties |
+
+ Passed via |
+
+ Passed via |
+
Static metadata |
+
+ Passed via |
+|
A structured query to Splunk HEC looks like:
+curl -k -v -X POST https://localhost:8080/services/collector/event/1.0 -H "Content-type: application/json; profile=\"urn:splunk:event:1.0\"; charset=utf-8" -H "Authorization: Splunk 29fe2838-cab6-4d17-a392-37b7b8f41f75" -d@events.json
+{
+ "time": "1673001538.042",
+ "host": "hostname",
+ "source": "mysource",
+ "sourcetype": "_json",
+ "index": "main",
+ "event": {
+ "message": "2023-01-06 ERROR The log message",
+ "logger": "com.acme.MyClass",
+ "severity": "ERROR",
+ "exception": "java.lang.NullPointerException",
+ "properties": {
+ "mdc-key": "mdc-value"
+ }
+ },
+ "fields": {
+ "key": "static-value"
+ }
+}{
+ "time": "1673001538.042",
+ "host": "hostname",
+ "source": "mysource",
+ "index": "main",
+ "event": "2023-01-06 ERROR The log message",
+ "fields": {
+ "severity": "ERROR",
+ "mdc-key": "mdc-value",
+ "key": "static-value"
+ }
+}Batched events that cannot be sent to the Splunk indexer will be logged to stdout:
+Formatted using console handler settings if the console handler is enabled
+Formatted using splunk handler settings otherwise
+In any case, the root cause of the failure is always logged to stderr.
+By default, the log handler is synchronous and only the HTTP requests to HEC endpoint are done asynchronously:
+
+This can be an issue because the Splunk library #send is synchronized, so any preprocessing of the batch HTTP request itself happens on the application thread of the log event that triggered the batch to be full (either by reaching quarkus.log.handler.splunk.batch-size-count or quarkus.log.handler.splunk.batch-size-bytes)
By enabling quarkus.log.handler.splunk.async=true, an intermediate event queue is used, which decouples the flushing of the batch from any application thread:
participant "Application" as App +participant Slf4j +participant AsyncHandler +participant SplunkLogHandler +participant "Splunk library" as Lib +participant "HTTP client" as OkHttp +participant "Splunk HEC" as HEC + +group Application thread +App -> Slf4j: info(message) +Slf4j -> AsyncHandler: doPublish(record) +AsyncHandler -> AsyncHandler: Capture MDC +AsyncHandler -> AsyncHandler: Add to queue +AsyncHandler --> App +end + +group AsyncHandler single (daemon) thread +AsyncHandler -> AsyncHandler: Peek from queue +AsyncHandler -> SplunkLogHandler: doPublish(record) +SplunkLogHandler -> Lib: send(record) +note left + synchronized +end note +Lib -> Lib: Add event to batch +alt batch is full +Lib -> OkHttp: enqueue(HTTP request) +OkHttp --> Lib +end +Lib --> SplunkLogHandler +SplunkLogHandler --> AsyncHandler + +end +group HTTP client - multiple connections in parallel mode. +OkHttp -> OkHttp: Peek from queue +OkHttp -> HEC: HTTP POST /services/collector/event/1.0 +HEC --> OkHttp: 200 +alt status code != 200 +OkHttp --> Lib: handle errors +Lib -> Lib: stderr.println +end +end+
By default quarkus.log.handler.splunk.async.queue-length=block, so applicative threads will block once the queue limit has reached quarkus.log.handler.splunk.async.queue-length.
There’s no link between quarkus.log.handler.splunk.async.queue-length and quarkus.log.handler.splunk.batch-size-count.
The number of events kept in memory for batching purposes is not limited.
+After tuning quarkus.log.handler.splunk.batch-size-count and quarkus.log.handler.splunk.batch-size-bytes, in case the HEC endpoint cannot keep up with the batch throughput, using multiple HTTP connections might help to reduce memory usage on the client.
By setting quarkus.log.handler.splunk.send-mode=parallel multiple batches will be sent over the wire in parallel, potentially increasing throughput with the HEC endpoint.
A named log handler can be configured to manage multiple Splunk configurations for particular log emissions. Like for core Quarkus handlers (console, file or syslog), +Splunk named handlers follow the same configuration:
+# Global configuration
+quarkus.log.handler.splunk.token=12345678-1234-1234-1234-1234567890AB
+quarkus.log.handler.splunk.metadata-index=mylogindex
+
+# Splunk named handler configuration, named here MONITORING
+quarkus.log.handler.splunk."MONITORING".token=12345678-0000-0000-0000-1234567890AB
+quarkus.log.handler.splunk."MONITORING".metadata-index=mystatsindex
+
+# Registration of the custom handler through Quarkus core category management, here monitoring as the logging category
+quarkus.log.category."monitoring".handlers=MONITORING
+quarkus.log.category."monitoring".use-parent-handlers=falseNext to use such logger in actual code, you can rely on annotation or factory:
+With annotation:
+@LoggerName("monitoring")
+Logger monitoringLogger;With factory:
+static final Logger monitoringLogger = Logger.getLogger("monitoring");Every handler is isolated and uses a separate Splunk client and connection pool, which means it has a cost.
+The configuration from the root handler are not inherited by named handlers.
+Use quarkus.log.category."named-handler".use-parent-handlers=false is required if you do not want the root handler to also receive log events already sent to named handlers.
This extension follows the log handlers configuration domain that is defined by Quarkus, every configuration property of this extension will belong to the following configuration root : quarkus.log.handler.splunk
When present this extension is enabled by default, meaning the client would expect a valid connection to a Splunk indexer and would print an error message for every log created by the application.
+So in local environment, the log handler can be disabled with the following property :
+quarkus.log.handler.splunk.enabled=falseEvery configuration property of the extension is overridable at runtime.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Determine whether to enable the handler +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The splunk handler log level. By default, it is no more strict than the root handler level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Splunk HEC endpoint base url. +
+
+With raw events, the endpoint targeted is /services/collector/raw. With flat or nested JSON events, the endpoint targeted is /services/collector/event/1.0. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable TLS certificate validation with HEC endpoint +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The application token to authenticate with HEC, the token is mandatory if the extension is enabled https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#HEC_token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The strategy to send events to HEC. +
+
+In sequential mode, there is only one HTTP connection to HEC and the order of events is preserved, but performance is lower. In parallel mode, event batches are sent asynchronously over multiple HTTP connections, and events with the same timestamp (that has 1 millisecond resolution) may be indexed out of order by Splunk. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+A GUID to identify an HEC client and guarantee isolation at HEC level in case of slow clients. https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck#About_channels_and_sending_data +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Batching delay before sending a group of events. If 0, the events are sent immediately. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Maximum number of events in a batch. By default 10, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum total size in bytes of events in a batch. By default 10KB, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum number of retries in case of I/O exceptions with HEC connection. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The log format, defining which metadata are inlined inside the log main payload. +
+
+Specific metadata (hostname, category, thread name, …), as well as MDC key/value map, can also be sent in a structured way. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether to send the thrown exception message as a structured metadata of the log event (as opposed to %e in a formatted message, it does not include the exception name or stacktrace). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the logger name as a structured metadata of the log event (equivalent of %c in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the thread name as a structured metadata of the log event (equivalent of %t in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Overrides the host name metadata value. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The source value to assign to the event data. For example, if you’re sending data from an app you’re developing, you could set this key to the name of the app. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The optional format of the events, to enable some parsing on Splunk side. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+A given source type may have indexed fields extraction enabled, which is the case of the built-in _json used for nested serialization. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The optional name of the index by which the event data is to be stored. If set, it must be within the list of allowed indexes of the token (if it has the indexes parameter set). https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The name of the key used to convey the severity / log level in the metadata fields. Only applicable to 'flat' serialization. With 'nested' serialization, there is already a 'severity' field. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The format of the payload. +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Indicates whether to log asynchronously +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The queue length to use before flushing writing +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Determine whether to block the publisher (rather than drop the message) when the queue is full +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Optional static key/value pairs to populate the "fields" key of event metadata. This isn’t applicable to raw serialization. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Determine whether to enable the handler +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The splunk handler log level. By default, it is no more strict than the root handler level. +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Splunk HEC endpoint base url. +
+
+With raw events, the endpoint targeted is /services/collector/raw. With flat or nested JSON events, the endpoint targeted is /services/collector/event/1.0. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable TLS certificate validation with HEC endpoint +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The application token to authenticate with HEC, the token is mandatory if the extension is enabled https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#HEC_token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The strategy to send events to HEC. +
+
+In sequential mode, there is only one HTTP connection to HEC and the order of events is preserved, but performance is lower. In parallel mode, event batches are sent asynchronously over multiple HTTP connections, and events with the same timestamp (that has 1 millisecond resolution) may be indexed out of order by Splunk. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+A GUID to identify an HEC client and guarantee isolation at HEC level in case of slow clients. https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck#About_channels_and_sending_data +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Batching delay before sending a group of events. If 0, the events are sent immediately. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Maximum number of events in a batch. By default 10, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum total size in bytes of events in a batch. By default 10KB, if 0 no batching. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Maximum number of retries in case of I/O exceptions with HEC connection. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The log format, defining which metadata are inlined inside the log main payload. +
+
+Specific metadata (hostname, category, thread name, …), as well as MDC key/value map, can also be sent in a structured way. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether to send the thrown exception message as a structured metadata of the log event (as opposed to %e in a formatted message, it does not include the exception name or stacktrace). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the logger name as a structured metadata of the log event (equivalent of %c in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to send the thread name as a structured metadata of the log event (equivalent of %t in a formatted message). Only applicable to 'nested' serialization. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Overrides the host name metadata value. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The source value to assign to the event data. For example, if you’re sending data from an app you’re developing, you could set this key to the name of the app. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The optional format of the events, to enable some parsing on Splunk side. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+A given source type may have indexed fields extraction enabled, which is the case of the built-in _json used for nested serialization. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The optional name of the index by which the event data is to be stored. If set, it must be within the list of allowed indexes of the token (if it has the indexes parameter set). https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional static key/value pairs to populate the "fields" key of event metadata. This isn’t applicable to raw serialization. https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+The name of the key used to convey the severity / log level in the metadata fields. Only applicable to 'flat' serialization. With 'nested' serialization, there is already a 'severity' field. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The format of the payload. +
+
+
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Indicates whether to log asynchronously +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The queue length to use before flushing writing +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Determine whether to block the publisher (rather than drop the message) when the queue is full +
+
+Environment variable: |
+
+
|
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If Dev Services for Mailpit has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The Mailpit container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Flag to control if verbose logging of Mailpit container is requested. +
+
+Environment variable: |
+boolean |
+
|
+
A Quarkus extension that lets you utilize Mailpit as a Dev Service for the Quarkus Mailer enabling zero-config SMTP for testing or running in dev mode. Mailpit acts as an SMTP server, provides a modern web interface to view & test captured emails, and contains an API for automated integration testing.
+Using this service has some obvious advantages when running in dev mode including but not limited to:
+Verify e-mail and their content without a real mail server
+Prevent accidentally sending a customer an email while developing
+Use the REST API to verify contents of real send emails and not mocked mail
+12 Factor App: Backing services Treat backing services as attached resources
+12 Factor App: Dev/Prod Parity Keep development, staging, and production as similar as possible
+If you want to use this extension, you need to add the io.quarkiverse.mailpit:quarkus-mailpit extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.mailpit</groupId>
+ <artifactId>quarkus-mailpit</artifactId>
+ <version>0.0.9</version>
+</dependency>
+
+<!-- If you want to use test framework to verify emails also -->
+<dependency>
+ <groupId>io.quarkiverse.mailpit</groupId>
+ <artifactId>quarkus-mailpit-testing</artifactId>
+ <version>0.0.9</version>
+ <scope>test</scope>
+</dependency>Now that you configured your POM to use the service, now you need to tell your dev mode to send emails to Mailpit by modifying the following properties in your application.properties:
%dev.quarkus.mailer.host=localhost
+%dev.quarkus.mailer.port=1025
+%dev.quarkus.mailer.mock=falseThis will enable the Mailer to send real e-mails that will be intercepted by Mailpit. Next, add some code that sends an e-mail…
+@Path("/superheroes")
+@ApplicationScoped
+public class SuperheroResource {
+ @Inject
+ Mailer mailer;
+
+ @GET
+ public String villainAlert() {
+ Mail m = new Mail();
+ m.setFrom("admin@hallofjustice.net");
+ m.setTo(List.of("superheroes@quarkus.io"));
+ m.setText("Lex Luthor has been seen in Gotham City!");
+ m.setSubject("WARNING: Super Villain Alert");
+ mailer.send(m);
+
+ return "Superheroes alerted!";
+ }
+}Simply run your application with mvn quarkus:dev and execute your code. Browse to the Dev UI to see this Mailpit card under Extensions:
+You can also inspect the container image that was started under Dev Services:
+
+Click on the "Mailpit UI" link to then see the UI with all your captured e-mails.
+
+You can view all of Mailpit’s container logs right in the DevUI log area to debug all messages and errors from Mailpit.
+
+Mailpit ships with REST APIs that allow you to query, inspect, mark read, or delete e-mails from the running instance. This extension has wrapped up the API nicely and allows you to query Mailpit to check the emails were sent.
+@QuarkusTest
+@WithMailbox
+public class MailpitResourceTest {
+
+ @InjectMailbox
+ Mailer mailbox;
+
+ @AfterEach
+ public void afterEach() throws ApiException {
+ // clear the mailbox after each test run if you prefer
+ mailbox.clear();
+ }
+
+ @Test
+ public void testAlert() throws ApiException {
+ given()
+ .when().get("/mailpit/alert")
+ .then()
+ .statusCode(200)
+ .body(is("Superheroes alerted!!"));
+
+ // look up the mail and assert it
+ Message message = mailbox.findFirst("admin@hallofjustice.net");
+ assertThat(message, notNullValue());
+ assertThat(message.getTo().get(0).getAddress(), is("superheroes@quarkus.io"));
+ assertThat(message.getSubject(), is("WARNING: Super Villain Alert"));
+ assertThat(message.getText(), is("Lex Luthor has been seen in Gotham City!\r\n"));
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If Dev Services for Mailpit has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The Mailpit container image to use. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Flag to control if verbose logging of Mailpit container is requested. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||
|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to AzureMonitor.
+ Support for AzureMonitor will be enabled if Micrometer support is enabled, the Azure Monitor registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||
+
+
+
+
+
+Azure Monitor registry configuration properties. +
+
+A property source for configuration of the AzureMonitor MeterRegistry. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Datadog
+ Support for Datadog will be enabled if Micrometer support is enabled, the Datadog registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||
+
+
+
+
+
+Datadog MeterRegistry configuration properties. +
+
+A property source for configuration of the Datadog MeterRegistry to push +metrics using the Datadog API, see https://micrometer.io/docs/registry/datadog. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Support for export to JMX
+ Support for JMX will be enabled if Micrometer support is enabled, the JMX registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ |
+
+
+
+
+
+JMX registry configuration properties. +
+
+A property source for configuration of the JMX MeterRegistry, +see https://micrometer.io/docs/registry/jmx. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic
+ Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic API, see https://micrometer.io/docs/registry/new-relic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to SignalFx.
+ Support for SignalFx will be enabled if Micrometer support is enabled, the SignalFx registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||
+
+
+
+
+
+SignalFx registry configuration properties. +
+
+A property source for configuration of the SignalFx MeterRegistry, +see https://micrometer.io/docs/registry/signalFx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Stackdriver.
+<p>
+Support for Stackdriver will be enabled if Micrometer
+support is enabled, the Stackdriver registry extension is enabled
+and either this value is true, or this value is unset and
+
+
+
|
+boolean |
++ | ||||||||
+
+
+
+
+
+Stackdriver registry configuration properties. +
+
+A property source for configuration of the Stackdriver MeterRegistry, +see https://micrometer.io/docs/registry/stackdriver. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to StatsD.
+ Support for StatsD will be enabled if Micrometer support is enabled, the Statsd registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||||||||
+
+
+
+
+
+StatsD registry configuration properties. +
+
+A property source for configuration of the StatsD MeterRegistry, +see https://micrometer.io/docs/registry/statsD. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer StatsD documentation, if you want to customize the metrics
+sink, do so by providing your own |
+
|
++ |
This is where the core Quarkus Micrometer extension meets the larger ecosystem of supported registries.
+Please ask questions on stackoverflow (using quarkus and micrometer tags, or join us in the Quarkus Zulip chatroom, or in the #quarkus channel in the Micrometer Slack workspace.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||
|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to AzureMonitor.
+ Support for AzureMonitor will be enabled if Micrometer support is enabled, the Azure Monitor registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||
+
+
+
+
+
+Azure Monitor registry configuration properties. +
+
+A property source for configuration of the AzureMonitor MeterRegistry. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Datadog
+ Support for Datadog will be enabled if Micrometer support is enabled, the Datadog registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||
+
+
+
+
+
+Datadog MeterRegistry configuration properties. +
+
+A property source for configuration of the Datadog MeterRegistry to push +metrics using the Datadog API, see https://micrometer.io/docs/registry/datadog. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Support for export to JMX
+ Support for JMX will be enabled if Micrometer support is enabled, the JMX registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ |
+
+
+
+
+
+JMX registry configuration properties. +
+
+A property source for configuration of the JMX MeterRegistry, +see https://micrometer.io/docs/registry/jmx. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic
+ Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic API, see https://micrometer.io/docs/registry/new-relic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to SignalFx.
+ Support for SignalFx will be enabled if Micrometer support is enabled, the SignalFx registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||
+
+
+
+
+
+SignalFx registry configuration properties. +
+
+A property source for configuration of the SignalFx MeterRegistry, +see https://micrometer.io/docs/registry/signalFx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Stackdriver.
+<p>
+Support for Stackdriver will be enabled if Micrometer
+support is enabled, the Stackdriver registry extension is enabled
+and either this value is true, or this value is unset and
+
+
+
|
+boolean |
++ | ||||||||
+
+
+
+
+
+Stackdriver registry configuration properties. +
+
+A property source for configuration of the Stackdriver MeterRegistry, +see https://micrometer.io/docs/registry/stackdriver. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. + |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to StatsD.
+ Support for StatsD will be enabled if Micrometer support is enabled, the Statsd registry extension is enabled and either this value is true, or this value is unset and |
+boolean |
++ | ||||||||||||||||
+
+
+
+
+
+StatsD registry configuration properties. +
+
+A property source for configuration of the StatsD MeterRegistry, +see https://micrometer.io/docs/registry/statsD. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer StatsD documentation, if you want to customize the metrics
+sink, do so by providing your own |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||
|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to AzureMonitor. +
+
+Support for AzureMonitor will be enabled if Micrometer support is enabled, the Azure Monitor registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||
+
+
+
+
+
+By default, this extension will create a AzureMonitor MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default AzureMonitor MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||
+
+
+
+
+
+Azure Monitor registry configuration properties. +
+
+A property source for configuration of the AzureMonitor MeterRegistry. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Datadog +
+
+Support for Datadog will be enabled if Micrometer support is enabled, the Datadog registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a Datadog MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Datadog MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+Datadog MeterRegistry configuration properties. +
+
+A property source for configuration of the Datadog MeterRegistry to push +metrics using the Datadog API, see https://micrometer.io/docs/registry/datadog. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Graphite. +
+
+Support for Graphite will be enabled if Micrometer support is enabled, the Graphite registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||||
+
+
+
+
+
+By default, this extension will create a Graphite MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Graphite MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||||
+
+
+
+
+
+Graphite registry configuration properties. +
+
+A property source for configuration of the Graphite MeterRegistry, +see https://micrometer.io/docs/registry/graphite. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to InfluxDB. +
+
+Support for InfluxDB will be enabled if Micrometer support is enabled, the InfluxDB registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||||
+
+
+
+
+
+By default, this extension will create a InfluxDB MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default InfluxDB MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||||
+
+
+
+
+
+InfluxDB registry configuration properties. +
+
+A property source for configuration of the InfluxDB MeterRegistry, +see https://micrometer.io/docs/registry/influx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer InfluxDB documentation, if you want to customize the metrics
+sink, do so by providing your own
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Support for export to JMX +
+
+Support for JMX will be enabled if Micrometer support is enabled, the JMX registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+By default, this extension will create a JMX MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default JMX MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+JMX registry configuration properties. +
+
+A property source for configuration of the JMX MeterRegistry, +see https://micrometer.io/docs/registry/jmx. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic +
+
+Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a New Relic MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default New Relic MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic library, see https://github.com/newrelic/micrometer-registry-newrelic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic +
+
+Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||
+
+
+
+
+
+By default, this extension will create a New Relic MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default New Relic MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic API, see https://micrometer.io/docs/registry/new-relic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||
|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to OTLP. +
+
+Support for OTLP will be enabled if Micrometer support is enabled, the OTLP registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||
+
+
+
+
+
+By default, this extension will create a OTLP MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default OTLP MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||
+
+
+
+
+
+OTLP registry configuration properties. +
+
+A property source for configuration of the OTLP MeterRegistry, +see https://micrometer.io/docs/registry/otlp. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to SignalFx. +
+
+Support for SignalFx will be enabled if Micrometer support is enabled, the SignalFx registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||
+
+
+
+
+
+By default, this extension will create a SignalFx MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default SignalFx MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||
+
+
+
+
+
+SignalFx registry configuration properties. +
+
+A property source for configuration of the SignalFx MeterRegistry, +see https://micrometer.io/docs/registry/signalFx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Stackdriver.
+<p>
+Support for Stackdriver will be enabled if Micrometer
+support is enabled, the Stackdriver registry extension is enabled
+and either this value is true, or this value is unset and
+
+
+
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a Stackdriver MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Stackdriver MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+Stackdriver registry configuration properties. +
+
+A property source for configuration of the Stackdriver MeterRegistry, +see https://micrometer.io/docs/registry/stackdriver. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to StatsD. +
+
+Support for StatsD will be enabled if Micrometer support is enabled, the Statsd registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||
+
+
+
+
+
+By default, this extension will create a StatsD MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default StatsD MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||
+
+
+
+
+
+StatsD registry configuration properties. +
+
+A property source for configuration of the StatsD MeterRegistry, +see https://micrometer.io/docs/registry/statsD. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer StatsD documentation, if you want to customize the metrics
+sink, do so by providing your own
+
+Environment variable: |
+
|
++ |
This is where the core Quarkus Micrometer extension meets the larger ecosystem of supported registries.
+Please ask questions on stackoverflow (using quarkus and micrometer tags, or join us in the Quarkus Zulip chatroom, or in the #quarkus channel in the Micrometer Slack workspace.
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-azure-monitor</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||
|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to AzureMonitor. +
+
+Support for AzureMonitor will be enabled if Micrometer support is enabled, the Azure Monitor registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||
+
+
+
+
+
+By default, this extension will create a AzureMonitor MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default AzureMonitor MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||
+
+
+
+
+
+Azure Monitor registry configuration properties. +
+
+A property source for configuration of the AzureMonitor MeterRegistry. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-datadog</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Datadog +
+
+Support for Datadog will be enabled if Micrometer support is enabled, the Datadog registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a Datadog MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Datadog MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+Datadog MeterRegistry configuration properties. +
+
+A property source for configuration of the Datadog MeterRegistry to push +metrics using the Datadog API, see https://micrometer.io/docs/registry/datadog. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-graphite</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Graphite. +
+
+Support for Graphite will be enabled if Micrometer support is enabled, the Graphite registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||||
+
+
+
+
+
+By default, this extension will create a Graphite MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Graphite MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||||
+
+
+
+
+
+Graphite registry configuration properties. +
+
+A property source for configuration of the Graphite MeterRegistry, +see https://micrometer.io/docs/registry/graphite. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-influx</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to InfluxDB. +
+
+Support for InfluxDB will be enabled if Micrometer support is enabled, the InfluxDB registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||||
+
+
+
+
+
+By default, this extension will create a InfluxDB MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default InfluxDB MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||||
+
+
+
+
+
+InfluxDB registry configuration properties. +
+
+A property source for configuration of the InfluxDB MeterRegistry, +see https://micrometer.io/docs/registry/influx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer InfluxDB documentation, if you want to customize the metrics
+sink, do so by providing your own
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-jmx</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Support for export to JMX +
+
+Support for JMX will be enabled if Micrometer support is enabled, the JMX registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+By default, this extension will create a JMX MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default JMX MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+JMX registry configuration properties. +
+
+A property source for configuration of the JMX MeterRegistry, +see https://micrometer.io/docs/registry/jmx. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-newrelic-telemetry</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic +
+
+Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a New Relic MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default New Relic MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic library, see https://github.com/newrelic/micrometer-registry-newrelic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
There is a new library for the New Relic micrometer registry here: +micrometer-registry-newrelic-telemetry
+<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-newrelic</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to New Relic +
+
+Support for New Relic will be enabled if Micrometer support is enabled, the New Relic registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||
+
+
+
+
+
+By default, this extension will create a New Relic MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default New Relic MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||
+
+
+
+
+
+New Relic MeterRegistry configuration properties. +
+
+A property source for configuration of the New Relic MeterRegistry to push +metrics using the New Relic API, see https://micrometer.io/docs/registry/new-relic. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-otlp</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||
|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to OTLP. +
+
+Support for OTLP will be enabled if Micrometer support is enabled, the OTLP registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||
+
+
+
+
+
+By default, this extension will create a OTLP MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default OTLP MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||
+
+
+
+
+
+OTLP registry configuration properties. +
+
+A property source for configuration of the OTLP MeterRegistry, +see https://micrometer.io/docs/registry/otlp. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-signalfx</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to SignalFx. +
+
+Support for SignalFx will be enabled if Micrometer support is enabled, the SignalFx registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||
+
+
+
+
+
+By default, this extension will create a SignalFx MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default SignalFx MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||
+
+
+
+
+
+SignalFx registry configuration properties. +
+
+A property source for configuration of the SignalFx MeterRegistry, +see https://micrometer.io/docs/registry/signalFx. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-stackdriver</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||
|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to Stackdriver.
+<p>
+Support for Stackdriver will be enabled if Micrometer
+support is enabled, the Stackdriver registry extension is enabled
+and either this value is true, or this value is unset and
+
+
+
+
+Environment variable: |
+boolean |
++ | ||||||||
+
+
+
+
+
+By default, this extension will create a Stackdriver MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default Stackdriver MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||
+
+
+
+
+
+Stackdriver registry configuration properties. +
+
+A property source for configuration of the Stackdriver MeterRegistry, +see https://micrometer.io/docs/registry/stackdriver. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+Environment variable: |
+
|
++ |
<dependency>
+ <groupId>io.quarkiverse.micrometer.registry</groupId>
+ <artifactId>quarkus-micrometer-registry-statsd</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+
+
+
+
+Support for export to StatsD. +
+
+Support for StatsD will be enabled if Micrometer support is enabled, the Statsd registry extension is enabled and either this value is true, or this value is unset and
+
+Environment variable: |
+boolean |
++ | ||||||||||||||||
+
+
+
+
+
+By default, this extension will create a StatsD MeterRegistry instance. +
+
+Use this attribute to veto the creation of the default StatsD MeterRegistry. +
+
+Environment variable: |
+boolean |
+
|
+||||||||||||||||
+
+
+
+
+
+StatsD registry configuration properties. +
+
+A property source for configuration of the StatsD MeterRegistry, +see https://micrometer.io/docs/registry/statsD. +
+
+Available values: +
+
+Other Micrometer configuration attributes can also be specified. +
+
+As mentioned in the Micrometer StatsD documentation, if you want to customize the metrics
+sink, do so by providing your own
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||
|---|---|---|---|---|
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ | ||
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+The Minio container image to use. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Indicates if the Minio server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Minio starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Minio servers. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Minio root username access key. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Minio root username secret key. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Should the extension provide a
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+If value is
+
+Only true for clients produced by the extension +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+If minio clients are to produce metrics, then the uri tag will have a max of 100 values +
+
+Environment variable: |
+int |
+
|
+||
+
+
+
+
+
+The minio server URL. +
+
+
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server access key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server secret key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+An optional bucket region +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+Should the extension provide a
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The minio server URL. +
+
+
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server access key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server secret key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+An optional bucket region +
+
+Environment variable: |
+string |
++ |
Integrate Min.io sdk compatible with all S3 Api compliant vendors. Available for jdk and native runtime.
+Once you have your Quarkus project configured you can add the minio extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="minio"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.minio</groupId>
+ <artifactId>quarkus-minio</artifactId>
+ <version>3.7.1</version>
+</dependency>If you need configless programmatic only creation of MinioClient, then your project should be configured as followed :
+<dependency>
+ <groupId>io.quarkiverse.minio</groupId>
+ <artifactId>quarkus-minio-native</artifactId>
+ <version>3.7.1</version>
+</dependency>An io.minio.MinioClient is made available to your application as a CDI bean if configuration is found.
package com.acme.minio;
+
+import io.minio.MinioClient;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+import jakarta.inject.Inject;
+
+@ApplicationScoped
+public class SampleService {
+
+ @Inject
+ MinioClient minioClient;
+
+ @ConfigProperty(name = "minio.bucket-name")
+ String bucketName;
+
+ public String getObject(String name) {
+ try (InputStream is = minio.getObject(
+ GetObjectArgs.builder()
+ .bucket(bucketName)
+ .object(objectName)
+ .build());
+ ) {
+ // Do whatever you want...
+ } catch (MinioException e) {
+ throw new IllegalStateException(e);
+ }
+ }
+
+}Defining multiple minio clients works exactly the same way as defining a single minio client, with one important change: +you define a name.
+In the following example, you have 3 different minio clients:
+The default one,
+A minio client named other,
A minio client named public,
each with its own configuration.
+quarkus.minio.url=http://localhost:9000
+quarkus.minio.access-key=minioaccess
+quarkus.minio.secret-key=miniosecret
+
+quarkus.minio.other.enabled=true
+quarkus.minio.other.url=http://acme:9000
+quarkus.minio.other.access-key=minioaccess
+quarkus.minio.other.secret-key=miniosecret
+
+quarkus.minio.public.enabled=true
+quarkus.minio.public.url=http://public:9000
+quarkus.minio.public.access-key=minioaccess
+quarkus.minio.public.secret-key=miniosecretNotice there is an extra bit in the key.
+The syntax is as follows: quarkus.minio.[optional name.][bucket property].
Named minio clients need to specify at least one build time property so that Quarkus knows they exist. +Generally this will be the `enabled` property.+
When using multiple minio clients, each MinioClient also has the io.quarkiverse.minio.client.MinioQualifier qualifier with the name of the minio client as the value.
+Using the above properties to configure three different minio clients, you can also inject each one as follows:
@Inject
+MinioClient defaultMinioClient;
+
+@Inject
+@MinioQualifier("public")
+MinioClient publicMinioClient;
+
+@Inject
+@MinioQualifier("other")
+MinioClient otherMinioClient;Quarkus supports a feature called Dev Services that allows you to create various containers without any config.
+What that means in practice is that if you have Docker running and have not configured quarkus.minio.url,
+Quarkus will automatically start a Minio container when running tests or in dev mode, and automatically
+configure the connection.
When running the production version of the application, the Minio connection needs to be configured as normal.
+| + + | +
+
+
+If using multiple minio client, all will target the same container. At the moment it’s also not possible to configure devservices individually for each minio client. + |
+
Most of the time you need to share the server between applications. +Dev Services for Minio implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.
+| + + | +
+Dev Services for Minio starts the container with the quarkus-dev-service-minio label which is used to identify the container.
+ |
+
If you need multiple (shared) servers, you can configure the quarkus.minio.devservices.service-name attribute and indicate the server name.
+It looks for a container with the same value, or starts a new one if none can be found.
+The default service name is minio.
Containers are started using Testcontainers and support reusable instances. If you add the property testcontainers.reuse.enable=true in your
+Testcontainers configuration file, then the container will not be stopped after each run, and can be reused. See https://www.testcontainers.org/features/reuse/#how-to-use-it
+for more information.
Sharing is enabled by default in dev mode, but disabled in test mode.
+You can disable the sharing with quarkus.minio.devservices.shared=false.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+||
|---|---|---|---|---|
+
+
+
+
+
+Enable or disable Dev Services explicitly. Dev Services are automatically enabled unless
+
+Environment variable: |
+boolean |
++ | ||
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ | ||
+
+
+
+
+
+The Minio container image to use. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Indicates if the Minio server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Minio starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Minio servers. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Minio root username access key. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Minio root username secret key. +
+
+Environment variable: |
+string |
+
|
+||
+
+
+
+
+
+Should the extension provide a
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+If value is
+
+Only true for clients produced by the extension +
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+If minio clients are to produce metrics, then the uri tag will have a max of 100 values +
+
+Environment variable: |
+int |
+
|
+||
+
+
+
+
+
+The minio server URL. +
+
+
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server access key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server secret key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+An optional bucket region +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+Should the extension provide a
+
+Environment variable: |
+boolean |
+
|
+||
+
+
+
+
+
+The minio server URL. +
+
+
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server access key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+The minio server secret key +
+
+Environment variable: |
+string |
++ | ||
+
+
+
+
+
+An optional bucket region +
+
+Environment variable: |
+string |
++ |
Integrate Min.io sdk compatible with all S3 Api complient vendors. Available for jdk and native runtime.
+Once you have your Quarkus project configured you can add the minio extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="minio"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.minio</groupId>
+ <artifactId>quarkus-minio</artifactId>
+ <version>2.9.3</version>
+</dependency>An io.minio.MinioClient is made available to your application as a CDI bean if configuration is found.
package com.acme.minio;
+
+import io.minio.MinioClient;
+
+import javax.enterprise.context.ApplicationScoped;
+
+import javax.inject.Inject;
+
+@ApplicationScoped
+public class SampleService {
+
+ @Inject
+ MinioClient minioClient;
+
+ @ConfigProperty(name = "minio.bucket-name")
+ String bucketName;
+
+ public String getObject(String objectName) {
+ try (InputStream is = minioClient.getObject(
+ GetObjectArgs.builder()
+ .bucket(bucketName)
+ .object(objectName)
+ .build());
+ ) {
+ // Do whatever you want...
+ } catch (MinioException e) {
+ throw new IllegalStateException(e);
+ }
+ }
+
+}Configuration property |
+Type |
+Default |
+||
|---|---|---|---|---|
+
+
+
+
+
+
+The minio server URL. +
+
+
|
+string |
++ | ||
+
+
+
+
+
+
+The minio server access key + |
+string |
++ | ||
+
+
+
+
+
+
+The minio server secret key + |
+string |
++ | ||
+
+
+
+
+
+
+An optional bucket region + |
+string |
++ | ||
+
+
+
+
+
+
+If allow-empty is set to |
+string |
++ | ||
+
+
+
+
+
+
+If |
+boolean |
+
+
|
+
Quarkus supports a feature called Dev Services that allows you to create various containers without any config.
+What that means in practice is that if you have Docker running and have not configured quarkus.minio.url,
+Quarkus will automatically start a Minio container when running tests or in dev mode, and automatically
+configure the connection.
When running the production version of the application, the Minio connection needs to be configured as normal.
+Most of the time you need to share the server between applications. +Dev Services for Minio implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.
+| + + | +
+Dev Services for Minio starts the container with the quarkus-dev-service-minio label which is used to identify the container.
+ |
+
If you need multiple (shared) servers, you can configure the quarkus.minio.devservices.service-name attribute and indicate the server name.
+It looks for a container with the same value, or starts a new one if none can be found.
+The default service name is minio.
Sharing is enabled by default in dev mode, but disabled in test mode.
+You can disable the sharing with quarkus.minio.devservices.shared=false.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+Configuration property |
+Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a Minio container when running in Dev or Test mode. + |
+boolean |
+true |
+
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. + |
+String |
+
|
+
+
+
+
+
+
+
+Indicates if the Minio server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Minio starts a new container.
+The discovery uses the |
+boolean |
+
|
+
+
+
+
+
+
+
+The value of the |
+String |
+
|
+
+
+
+
+
+
+
+Minio root username access key. + |
+String |
+
|
+
+
+
+
+
+
+
+Minio root username secret key. + |
+String |
+
|
+
This extension allows you to inject MockK mocks in your QuarkusTest tests.
If you want to use this extension, you need to add the quarkus-junit5-mockk extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.mockk</groupId>
+ <artifactId>quarkus-junit5-mockk</artifactId>
+ <version>LATEST</version>
+ <scope>test</scope>
+</dependency>Or add this in your build.gradle file:
dependencies {
+ testImplementation 'io.quarkiverse.mockk:quarkus-junit5-mockk:LATEST'
+}The extension exposes two annotations:
+@InjectMock to inject MockK mocks in your application
@InjectSpy to inject SpyK spies in your application
@InjectMock annotationThis annotation allows you to inject MockK mocks in your application.
+This annotation has three parameters:
+relaxed, if set to true, all function will return simple values. Default to false.
relaxUnitFun, if set to true, Unit function will be relaxed. Default to false.
convertScopes, it set to true, convert the @Singleton scope of bean to @ApplicationScoped. This allows to mock singleton beans
For example, @InjectMock can be used in the following example:
@QuarkusTest
+class InjectionMockTest {
+
+ @Inject
+ private lateinit var firstService: FirstService
+
+ @InjectMock
+ private lateinit var secondService: SecondService
+
+ @Test
+ fun `should respond test`() {
+ every { secondService.greet() } returns "test"
+ assertThat(firstService.greet()).isEqualTo("test")
+ }
+
+ @Test
+ fun `should respond second`() {
+ every { secondService.greet() } returns "second"
+ assertThat(firstService.greet()).isEqualTo("second")
+ verify { secondService.greet() }
+ }
+}In order to mock a RestClient, you must add the @RestClient qualifier alongside the @InjectMock:
@QuarkusTest
+class InjectionMockTest {
+
+ @Inject
+ private lateinit var firstService: FirstService
+
+ @InjectMock
+ @RestClient
+ private lateinit var myRestClientService: MyRestClientService
+
+ @Test
+ fun `should respond test`() {
+ every { myRestClientService.greet() } returns "test"
+ assertThat(firstService.greet()).isEqualTo("test")
+ }
+}@InjectSpy annotationThis annotation allows you to inject spies in your application.
+Spy allows you to mixed real objects and mocks.
+For example, @InjectSpy can be used in the following example:
@QuarkusTest
+class InjectionMockTest {
+
+ @InjectSpy
+ private lateinit var firstService: FirstService
+
+ @Test
+ fun `should respond test`() {
+ assertThat(firstService.greet()).isEqualTo("Hello")
+ }
+
+ @Test
+ fun `should respond second`() {
+ every { firstService.greet() } returns "mock response"
+ assertThat(firstService.greet()).isEqualTo("mock response")
+ verify { firstService.greet() }
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the MockServer server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for MockServer starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+MockServer configuration file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+MockServer’s configuration class-path binding. Useful for the test and CI builds. When set to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The configuration directory to mount in the container /config. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Endpoint of the MockServer +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
Quarkus [MockServer](https://mock-server.com/) extension for tests and local development.
+| + + | ++Quarkus test and dev MockServer extension. + | +
If you want to use this extension, you need to add the io.quarkiverse.mockserver:quarkus-mockserver extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.mockserver</groupId>
+ <artifactId>quarkus-mockserver-test</artifactId>
+ <version>0.6.0</version>
+ <scope>provided</scope>
+</dependency>This extension provides a quarkus.mockserver.endpoint variable that points to the launched Docker container.
Example configuration for local development and testing:
+%dev.quarkus.mockserver.devservices.config-file=src/test/resources/mockserver.properties
+%dev.quarkus.mockserver.devservices.config-dir=src/test/resources/mockserver
+%dev.quarkus.mockserver.devservices.log=true
+
+%dev.activity-client/mp-rest/url=${quarkus.mockserver.endpoint}
+%test.activity-client/mp-rest/url=${quarkus.mockserver.endpoint}To use the extension for test, add the dependency to the target project:
+<dependency>
+ <groupId>io.quarkiverse.mockserver</groupId>
+ <artifactId>quarkus-mockserver-test</artifactId>
+ <version>0.6.0</version>
+ <scope>test</scope>
+</dependency>Test class example
+import io.quarkiverse.mockserver.test.MockServerTestResource;
+import io.quarkus.test.common.QuarkusTestResource;
+
+@QuarkusTest
+@QuarkusTestResource(MockServerTestResource.class)
+public class BaseTest {
+
+ @InjectMockServerClient
+ MockServerClient mockServerClient;
+
+ @Test
+ public void test200() {
+ Map<String, Object> data = new HashMap<>();
+ data.put("key-A", "value-A");
+ data.put("key-B", 1);
+
+ // create mock rest endpoint
+ mockServerClient
+ .when(request()
+ .withPath("/activity/data/1")
+ .withMethod("POST"))
+ .respond(
+ httpRequest -> response()
+ .withStatusCode(200)
+ .withHeader("Content-Type", "application/json")
+ .withBody(JsonBody.json(data))
+ );
+ }
+
+ // ... test
+}We can reuse the test for the integration test.
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+
+@QuarkusIntegrationTest
+public class BaseIT extends BaseTest {
+
+}For more information check examples in the integration-tests directory in this repo.
| + + | ++Remove this section if you don’t have Quarkus configuration properties in your extension. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the MockServer server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for MockServer starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+MockServer configuration file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+MockServer’s configuration class-path binding. Useful for the test and CI builds. When set to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The configuration directory to mount in the container /config. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Endpoint of the MockServer +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the MockServer server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for MockServer starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared MockServer servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+MockServer configuration file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+MockServer’s configuration class-path binding. Useful for the test and CI builds. When set to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The configuration directory to mount in the container /config. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Endpoint of the MockServer +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
Quarkus MockServer extension for tests and local development.
+| + + | ++Quarkus test and dev MockServer extension. + | +
If you want to use this extension, you need to add the io.quarkiverse.mockserver:quarkus-mockserver extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.mockserver</groupId>
+ <artifactId>quarkus-mockserver-test</artifactId>
+ <version>1.4.0</version>
+ <scope>provided</scope>
+</dependency>This extension provides a quarkus.mockserver.endpoint variable that points to the launched Docker container.
Example configuration for local development and testing:
+%dev.quarkus.mockserver.devservices.config-file=src/test/resources/mockserver.properties
+%dev.quarkus.mockserver.devservices.config-dir=src/test/resources/mockserver
+%dev.quarkus.mockserver.devservices.log=true
+
+%dev.activity-client/mp-rest/url=${quarkus.mockserver.endpoint}
+%test.activity-client/mp-rest/url=${quarkus.mockserver.endpoint}To use the extension for test, add the dependency to the target project:
+<dependency>
+ <groupId>io.quarkiverse.mockserver</groupId>
+ <artifactId>quarkus-mockserver-test</artifactId>
+ <version>1.4.0</version>
+ <scope>test</scope>
+</dependency>Test class example
+import io.quarkiverse.mockserver.test.MockServerTestResource;
+import io.quarkus.test.common.QuarkusTestResource;
+
+@QuarkusTest
+@QuarkusTestResource(MockServerTestResource.class)
+public class BaseTest {
+
+ @InjectMockServerClient
+ MockServerClient mockServerClient;
+
+ @Test
+ public void test200() {
+ Map<String, Object> data = new HashMap<>();
+ data.put("key-A", "value-A");
+ data.put("key-B", 1);
+
+ // create mock rest endpoint
+ mockServerClient
+ .when(request()
+ .withPath("/activity/data/1")
+ .withMethod("POST"))
+ .respond(
+ httpRequest -> response()
+ .withStatusCode(200)
+ .withHeader("Content-Type", "application/json")
+ .withBody(JsonBody.json(data))
+ );
+ }
+
+ // ... test
+}We can reuse the test for the integration test.
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+
+@QuarkusIntegrationTest
+public class BaseIT extends BaseTest {
+
+}For more information check examples in the integration-tests directory in this repo.
| + + | ++Remove this section if you don’t have Quarkus configuration properties in your extension. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the MockServer server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for MockServer starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared MockServer servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+MockServer configuration file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+MockServer’s configuration class-path binding. Useful for the test and CI builds. When set to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The configuration directory to mount in the container /config. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Endpoint of the MockServer +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Host of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Port of the MockServer for the MockServerClient +
+
+Environment variable: |
+string |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+enable mybatis xml configuration + |
+boolean |
+
|
+
+
+
+
+
+
+xml configuration file + |
+string |
+
|
+
+
+
+
+
+
+MyBatis environment id + |
+string |
+
|
+
+
+
+
+
+
+MyBatis transaction factory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis data source + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
+
|
+
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
+
|
+
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
+
|
+
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
+
|
+
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
+
|
+
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
+
+
+
+
+
+MyBatis mapperLocations + |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+MyBatis environment id + |
+string |
++ |
+
+
+
+
+
+MyBatis transaction factory + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
++ |
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
++ |
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
++ |
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
++ |
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
++ |
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
++ |
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
++ |
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
++ |
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
++ |
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
++ |
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
++ |
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
This guide demonstrates how your Quarkus application can use MyBatis to support custom SQL, stored procedures and advanced mappings.
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 1.8+ installed with JAVA_HOME configured appropriately
Apache Maven
+A running Mysql Database server
+GraalVM, or Docker, installed if you want to run in native mode.
+The application built in this guide is quite simple: the user can get, add and remove a record through the RESTful API by using the MyBatis Mapper.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus:quarkus-maven-plugin:2.16.12.Final:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=mybatis-quickstart \
+ -Dextensions="resteasy-jackson,jdbc-mysql,io.quarkiverse.mybatis:quarkus-mybatis:1.0.9" \
+ -DnoExamples
+cd mybatis-quickstart| + + | +
+
+
+Maven 3.6.2+ is required for this to work. + |
+
This command generates a Maven project, with its pom.xml importing the quarkus-mybatis extension.
+If you already have your Quarkus project configured, you can add the quarkus-mybatis extension
+to your project by adding the following dependency in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.mybatis</groupId>
+ <artifactId>quarkus-mybatis</artifactId>
+ <version>1.0.9</version>
+</dependency>We are going to create a User POJO to access to the data in the backend mysql server.
+Create the src/main/java/org/acme/mybatis/User.java file, with the following content:
package org.acme.mybatis;
+
+public class User {
+ private Integer id;
+ private String name;
+
+ public Integer getId() {
+ return id;
+ }
+
+ public void setId(Integer id) {
+ this.id = id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}We are going to create a UserMapper class which will use the MyBatis annotations to inject the SQL.
+Create the src/main/java/org/acme/mybatis/UserMapper.java file, with the following content:
package org.acme.mybatis;
+
+import org.apache.ibatis.annotations.Delete;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface UserMapper {
+
+ @Select("SELECT * FROM USERS WHERE id = #{id}")
+ User getUser(Integer id); (1)
+
+ @Insert("INSERT INTO USERS (id, name) VALUES (#{id}, #{name})")
+ Integer createUser(@Param("id") Integer id, @Param("name") String name); (2)
+
+ @Delete("DELETE FROM USERS WHERE id = #{id}")
+ Integer removeUser(Integer id); (3)
+}Get a user from the database.
+Insert a user into the database. We should use the @Param to bind the parameters.
Delete a user from the databse.
+We are going to create a MyBatisResource class which will handle all the requests to create, query or remove the data
+from the database.
package org.acme.mybatis;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.FormParam;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+@Path("/mybatis")
+public class MyBatisResource {
+
+ @Inject
+ UserMapper userMapper; (1)
+
+ @Path("/user/{id}")
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public User getUser(@PathParam("id") Integer id) {
+ return userMapper.getUser(id);
+ }
+
+ @Path("/user")
+ @POST
+ @Produces(MediaType.TEXT_PLAIN)
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Integer createUser(@FormParam("id") Integer id, @FormParam("name") String name) {
+ return userMapper.createUser(id, name);
+ }
+
+ @Path("/user/{id}")
+ @DELETE
+ @Produces(MediaType.TEXT_PLAIN)
+ public Integer removeUser(@PathParam("id") Integer id) {
+ return userMapper.removeUser(id);
+ }
+}It uses the UserMapper which should be injected by the Quarkus to access the database.
+We need to config the datasource used to connect to the database and the mybatis will choose the default one. Also you
+can use quarkus.mybatis.datasource
quarkus.datasource.db-kind=mysql
+quarkus.datasource.username=<db user>
+
+quarkus.datasource.jdbc.url=jdbc:mysql://localhost/test (1)
+quarkus.mybatis.initial-sql=insert.sql (2)The datasource used by the mybatis to connect the database.
+The SQL file which should be executed just after the application is started.
+We could keep the following content in the insert.sql to add some data:
DROP TABLE IF EXISTS USERS;
+
+CREATE TABLE USERS (
+ id integer not null primary key,
+ name varchar(80) not null
+);
+
+INSERT INTO USERS (id, name) values(1, 'Test User1');
+INSERT INTO USERS (id, name) values(2, 'Test User2');
+INSERT INTO USERS (id, name) values(3, 'Test User3');At first, you should make sure the Mysql Server is running and the test database has been created.
+Then, you just need to run:
./mvnw compile quarkus:devYou can get the user by using the following command:
+curl http://localhost:8080/mybatis/user/1Or create a new user:
+curl -X POST http://localhost:8080/mybatis/user -d 'id=4&name=test'Or remove a user:
+curl -X DELETE http://localhost:8080/mybatis/user/1You can build the native executable with:
+./mvnw package -Pnativeand then run with:
+./target/mybatis-quickstart-1.0-SNAPSHOT-runnerYou can choose a specific data source for MyBatis mapper using the annotation @MapperDataSource.
+Query in the next example will be running against data source with name user.
+If there is no such annotation on the mapper, the default data source will be used.
@Mapper
+@MapperDataSource("user")
+public interface UserMapper {
+ @Select("SELECT * FROM USERS WHERE id = #{id}")
+ User getUser(Integer id);
+}Injects default session factory:
+@Inject
+SqlSessionFactory sqlSessionFactory;Injects session factory for data source user:
@Named("user")
+SqlSessionFactory sqlSessionFactory;You need to set quarkus.mybatis.xmlconfig.enabletruequarkus.mybatis.xmlconfig.pathmybatis-config.xmlquarkus.mybatis.environmentenvironment
# H2
+quarkus.datasource.h2.db-kind=h2
+quarkus.datasource.h2.username=sa
+quarkus.datasource.h2.password=sa
+quarkus.datasource.h2.jdbc.url=jdbc:h2:tcp://localhost/mem:default
+
+# MyBatis
+quarkus.mybatis.xmlconfig.enable=true
+quarkus.mybatis.xmlconfig.path=mybatis-config.xml
+quarkus.mybatis.environment=development
+quarkus.mybatis.h2.initial-sql=insert-h2.sql<!DOCTYPE configuration
+ PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
+ "http://mybatis.org/dtd/mybatis-3-config.dtd">
+
+<configuration>
+ <typeHandlers>
+ <package name="io.quarkiverse.it.mybatis"/>
+ </typeHandlers>
+
+ <!-- setup environment with Quarkus data source -->
+ <environments default="development">
+ <environment id="development">
+ <transactionManager type="JDBC"/>
+ <dataSource type="QUARKUS">
+ <property name="db" value="h2"/>
+ </dataSource>
+ </environment>
+ </environments>
+
+ <mappers>
+ <package name="io.quarkiverse.it.mybatis"/>
+ </mappers>
+</configuration>The dataSource type must be QARKUSdb
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+enable mybatis xml configuration + |
+boolean |
+
|
+
+
+
+
+
+
+xml configuration file + |
+string |
+
|
+
+
+
+
+
+
+MyBatis environment id + |
+string |
+
|
+
+
+
+
+
+
+MyBatis transaction factory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis data source + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
+
|
+
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
+
|
+
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
+
|
+
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
+
|
+
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
+
|
+
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
+
+
+
+
+
+MyBatis mapperLocations + |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+MyBatis environment id + |
+string |
++ |
+
+
+
+
+
+MyBatis transaction factory + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
++ |
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
++ |
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
++ |
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
++ |
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
++ |
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
++ |
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
++ |
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
++ |
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
++ |
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
++ |
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
++ |
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+enable mybatis xml configuration + |
+boolean |
+
|
+
+
+
+
+
+
+xml configuration file + |
+string |
+
|
+
+
+
+
+
+
+MyBatis environment id + |
+string |
+
|
+
+
+
+
+
+
+MyBatis transaction factory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis data source + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
+
|
+
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
+
|
+
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
+
|
+
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
+
|
+
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
+
|
+
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
+
+
+
+
+
+MyBatis mapperLocations + |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+MyBatis environment id + |
+string |
++ |
+
+
+
+
+
+MyBatis transaction factory + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
++ |
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
++ |
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
++ |
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
++ |
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
++ |
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
++ |
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
++ |
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
++ |
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
++ |
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
++ |
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
++ |
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
This guide demonstrates how your Quarkus application can use MyBatis to support custom SQL, stored procedures and advanced mappings.
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven
+A running Mysql Database server
+GraalVM, or Docker, installed if you want to run in native mode.
+The application built in this guide is quite simple: the user can get, add and remove a record through the RESTful API by using the MyBatis Mapper.
+We recommend that you follow the instructions in the next sections and create the application step by step.
+First, we need a new project. Create a new project with the following command:
+mvn io.quarkus:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=mybatis-quickstart \
+ -Dextensions="resteasy-jackson,jdbc-mysql,io.quarkiverse.mybatis:quarkus-mybatis:2.2.2" \
+ -DnoExamples
+cd mybatis-quickstart| + + | +
+
+
+Maven 3.6.2+ is required for this to work. + |
+
This command generates a Maven project, with its pom.xml importing the quarkus-mybatis extension.
+If you already have your Quarkus project configured, you can add the quarkus-mybatis extension
+to your project by adding the following dependency in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.mybatis</groupId>
+ <artifactId>quarkus-mybatis</artifactId>
+ <version>2.2.2</version>
+</dependency>We are going to create a User POJO to access to the data in the backend mysql server.
+Create the src/main/java/org/acme/mybatis/User.java file, with the following content:
package org.acme.mybatis;
+
+public class User {
+ private Integer id;
+ private String name;
+
+ public Integer getId() {
+ return id;
+ }
+
+ public void setId(Integer id) {
+ this.id = id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}We are going to create a UserMapper class which will use the MyBatis annotations to inject the SQL.
+Create the src/main/java/org/acme/mybatis/UserMapper.java file, with the following content:
package org.acme.mybatis;
+
+import org.apache.ibatis.annotations.Delete;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface UserMapper {
+
+ @Select("SELECT * FROM USERS WHERE id = #{id}")
+ User getUser(Integer id); (1)
+
+ @Insert("INSERT INTO USERS (id, name) VALUES (#{id}, #{name})")
+ Integer createUser(@Param("id") Integer id, @Param("name") String name); (2)
+
+ @Delete("DELETE FROM USERS WHERE id = #{id}")
+ Integer removeUser(Integer id); (3)
+}Get a user from the database.
+Insert a user into the database. We should use the @Param to bind the parameters.
Delete a user from the databse.
+We are going to create a MyBatisResource class which will handle all the requests to create, query or remove the data
+from the database.
package org.acme.mybatis;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.FormParam;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/mybatis")
+public class MyBatisResource {
+
+ @Inject
+ UserMapper userMapper; (1)
+
+ @Path("/user/{id}")
+ @GET
+ @Produces(MediaType.APPLICATION_JSON)
+ public User getUser(@PathParam("id") Integer id) {
+ return userMapper.getUser(id);
+ }
+
+ @Path("/user")
+ @POST
+ @Produces(MediaType.TEXT_PLAIN)
+ @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
+ public Integer createUser(@FormParam("id") Integer id, @FormParam("name") String name) {
+ return userMapper.createUser(id, name);
+ }
+
+ @Path("/user/{id}")
+ @DELETE
+ @Produces(MediaType.TEXT_PLAIN)
+ public Integer removeUser(@PathParam("id") Integer id) {
+ return userMapper.removeUser(id);
+ }
+}It uses the UserMapper which should be injected by the Quarkus to access the database.
+We need to config the datasource used to connect to the database and the mybatis will choose the default one. Also you
+can use quarkus.mybatis.datasource
quarkus.datasource.db-kind=mysql
+quarkus.datasource.username=<db user>
+
+quarkus.datasource.jdbc.url=jdbc:mysql://localhost/test (1)
+quarkus.mybatis.initial-sql=insert.sql (2)The datasource used by the mybatis to connect the database.
+The SQL file which should be executed just after the application is started.
+We could keep the following content in the insert.sql to add some data:
DROP TABLE IF EXISTS USERS;
+
+CREATE TABLE USERS (
+ id integer not null primary key,
+ name varchar(80) not null
+);
+
+INSERT INTO USERS (id, name) values(1, 'Test User1');
+INSERT INTO USERS (id, name) values(2, 'Test User2');
+INSERT INTO USERS (id, name) values(3, 'Test User3');At first, you should make sure the Mysql Server is running and the test database has been created.
+Then, you just need to run:
./mvnw compile quarkus:devYou can get the user by using the following command:
+curl http://localhost:8080/mybatis/user/1Or create a new user:
+curl -X POST http://localhost:8080/mybatis/user -d 'id=4&name=test'Or remove a user:
+curl -X DELETE http://localhost:8080/mybatis/user/1You can build the native executable with:
+./mvnw package -Pnativeand then run with:
+./target/mybatis-quickstart-1.0-SNAPSHOT-runnerYou can choose a specific data source for MyBatis mapper using the annotation @MapperDataSource.
+Query in the next example will be running against data source with name user.
+If there is no such annotation on the mapper, the default data source will be used.
@Mapper
+@MapperDataSource("user")
+public interface UserMapper {
+ @Select("SELECT * FROM USERS WHERE id = #{id}")
+ User getUser(Integer id);
+}Injects default session factory:
+@Inject
+SqlSessionFactory sqlSessionFactory;Injects session factory for data source user:
@Named("user")
+SqlSessionFactory sqlSessionFactory;You need to set quarkus.mybatis.xmlconfig.enabletruequarkus.mybatis.xmlconfig.pathmybatis-config.xmlquarkus.mybatis.environmentenvironment
# H2
+quarkus.datasource.h2.db-kind=h2
+quarkus.datasource.h2.username=sa
+quarkus.datasource.h2.password=sa
+quarkus.datasource.h2.jdbc.url=jdbc:h2:tcp://localhost/mem:default
+
+# MyBatis
+quarkus.mybatis.xmlconfig.enable=true
+quarkus.mybatis.xmlconfig.path=mybatis-config.xml
+quarkus.mybatis.environment=development
+quarkus.mybatis.h2.initial-sql=insert-h2.sql<!DOCTYPE configuration
+ PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
+ "http://mybatis.org/dtd/mybatis-3-config.dtd">
+
+<configuration>
+ <typeHandlers>
+ <package name="io.quarkiverse.it.mybatis"/>
+ </typeHandlers>
+
+ <!-- setup environment with Quarkus data source -->
+ <environments default="development">
+ <environment id="development">
+ <transactionManager type="JDBC"/>
+ <dataSource type="QUARKUS">
+ <property name="db" value="h2"/>
+ </dataSource>
+ </environment>
+ </environments>
+
+ <mappers>
+ <package name="io.quarkiverse.it.mybatis"/>
+ </mappers>
+</configuration>The dataSource type must be QUARKUSdb
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+enable mybatis xml configuration + |
+boolean |
+
|
+
+
+
+
+
+
+xml configuration file + |
+string |
+
|
+
+
+
+
+
+
+MyBatis environment id + |
+string |
+
|
+
+
+
+
+
+
+MyBatis transaction factory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis data source + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
+
|
+
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
+
|
+
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
+
|
+
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
+
|
+
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
+
|
+
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
+
|
+
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
+
|
+
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
+
|
+
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
+
+
+
+
+
+MyBatis mapperLocations + |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+MyBatis environment id + |
+string |
++ |
+
+
+
+
+
+MyBatis transaction factory + |
+string |
++ |
+
+
+
+
+
+MyBatis initial sql + |
+string |
++ |
+
+
+
+
+
+MyBatis cacheEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis lazyLoadingEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis aggressiveLazyLoading + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useColumnLabel + |
+boolean |
++ |
+
+
+
+
+
+MyBatis useGeneratedKeys + |
+boolean |
++ |
+
+
+
+
+
+MyBatis autoMappingBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis autoMappingUnknownColumnBehavior + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultExecutorType + |
+
|
++ |
+
+
+
+
+
+MyBatis defaultStatementTimeout + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultFetchSize + |
+int |
++ |
+
+
+
+
+
+MyBatis defaultResultSetType + |
+
|
++ |
+
+
+
+
+
+MyBatis safeRowBoundsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis safeResultHandlerEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis mapUnderscoreToCamelCase + |
+boolean |
++ |
+
+
+
+
+
+MyBatis multipleResultSetsEnabled + |
+boolean |
++ |
+
+
+
+
+
+MyBatis localCacheScope + |
+
|
++ |
+
+
+
+
+
+MyBatis jdbcTypeForNull + |
+
|
++ |
+
+
+
+
+
+MyBatis lazyLoadTriggerMethods + |
+list of string |
++ |
+
+
+
+
+
+MyBatis defaultScriptingLanguage + |
+string |
++ |
+
+
+
+
+
+MyBatis defaultEnumTypeHandler + |
+string |
++ |
+
+
+
+
+
+MyBatis callSettersOnNulls + |
+boolean |
++ |
+
+
+
+
+
+MyBatis returnInstanceForEmptyRow + |
+boolean |
++ |
+
+
+
+
+
+MyBatis logPrefix + |
+string |
++ |
+
+
+
+
+
+MyBatis logImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis proxyFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis vfsImpl + |
+string |
++ |
+
+
+
+
+
+MyBatis useActualParamName + |
+boolean |
++ |
+
+
+
+
+
+MyBatis configurationFactory + |
+string |
++ |
+
+
+
+
+
+MyBatis shrinkWhitespacesInSql + |
+boolean |
++ |
+
+
+
+
+
+MyBatis defaultSqlProviderType + |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This value can be used to specify the port to which the bolt-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j container is reachable over bolt. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+This value can be used to specify the port to which the http-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j Browser is available. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Additional environment entries that can be added to the container before its start. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This value can be used to specify the port to which the bolt-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j container is reachable over bolt. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+This value can be used to specify the port to which the http-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j Browser is available. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The uri this driver should connect to. The driver supports bolt, bolt+routing or neo4j as schemes. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If the driver should use encrypted traffic. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure the maximum time transactions are allowed to retry. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Additional environment entries that can be added to the container before its start. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The login of the user connecting to the database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The password of the user connecting to the database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Set this to true to disable authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional field that when is not empty has precedence over
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Configures which trust strategy to apply when using encrypted traffic. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The file of the certificate to use. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+If hostname verification is used. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Flag, if metrics are enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Flag, if leaked sessions logging is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The maximum amount of connections in the connection pool towards a single database. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Pooled connections that have been idle in the pool for longer than this timeout will be tested before they are used again. The value
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Pooled connections older than this threshold will be closed and removed from the pool. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Acquisition of new connections will be attempted for at most configured timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
Neo4j is a graph database management system developed by Neo4j, Inc. Neo4j is a native graph database focused not only on the data itself, but especially on the relations between data. +Neo4j stores data as a property graph, which consists of vertices or nodes as we call them, connected with edges or relationships. +Both of them can have properties.
+Neo4j offers Cypher, a declarative query language much like SQL. +Cypher is used to for both querying the graph and creating or updating nodes and relationships. +As a declarative language it used to tell the database what to do and not how to do it.
+| + + | ++Learn more about Cypher in the Neo4j Cypher manual. + Cypher is not only available in Neo4j, but for example coming to Apache Spark. + A spec called OpenCypher is available, too. + | +
Clients communicate over the so-called Bolt protocol with the database.
+Neo4j - as the most popular graph database according to DB-Engines ranking - provides a variety of drivers for various languages.
+The Quarkus Neo4j extension is based on the official Neo4j Java Driver. +The extension provides an instance of the driver configured ready for usage in any Quarkus application. +You will be able to issue arbitrary Cypher statements over Bolt with this extension. +Those statements can be simple CRUD statements as well as complex queries, calling graph algorithms and more.
+The driver itself is released under the Apache 2.0 license, +while Neo4j itself is available in a GPL3-licensed open-source "community edition", +with online backup and high availability extensions licensed under a closed-source commercial license.
+The driver and thus the Quarkus extension support three different programming models:
+Blocking database access (much like standard JDBC)
+Asynchronous programming based on JDK’s completable futures and related infrastructure
+Reactive programming based on Reactive Streams
+The reactive programming model is only available when connected against a 4.0+ version of Neo4j. +Reactive programming in Neo4j is fully end-to-end reactive and therefore requires a server that supports backpressure.
+In this guide you will learn how to
+Add the Neo4j extension to your project
+Configure the driver
+And how to use the driver to access a Neo4j database
+This guide will focus on asynchronous access to Neo4j, as this is ready to use for everyone. +At the end of this guide, there will be a reactive version, which needs however a 4.0 database version.
+As with some other guides, the application shall manage fruit entities.
+package org.acme.neo4j;
+
+public class Fruit {
+ public UUID id;
+
+ public String name;
+
+ public Fruit() {
+ // This is needed for the REST-Easy JSON Binding
+ }
+
+ public Fruit(String name) {
+ this.name = name;
+ }
+
+ public Fruit(UUID id, String name) {
+ this.id = id;
+ this.name = name;
+ }
+}To complete this guide, you need:
+JDK 11+ installed with JAVA_HOME configured appropriately
an IDE
+Apache Maven 3.8.1+
+Access to a Neo4j Database
+Optional Docker for your system
+The easiest way to start a Neo4j instance is a locally installed Docker environment.
+docker run --publish=7474:7474 --publish=7687:7687 -e 'NEO4J_AUTH=neo4j/secret' neo4j:4.4This starts a Neo4j instance, that publishes its Bolt port on 7687 and a web interface on http://localhost:7474.
Have a look at the download page for other options to get started with the product itself.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
+The solution is located in the neo4j-quickstart directory.
+It contains a very simple UI to use the JAX-RS resources created here, too.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.1:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=neo4j-quickstart \
+ -DclassName="org.acme.datasource.GreetingResource" \
+ -Dextensions="neo4j,resteasy-reactive-jackson"
+cd neo4j-quickstartIt generates:
+the Maven structure
+a landing page accessible on http://localhost:8080
example Dockerfile files for both native and jvm modes
the application configuration file
+an org.acme.datasource.GreetingResource resource
an associated test
+The Neo4j extension has been added already to your pom.xml.
+In addition, we added resteasy-reactive-jackson, which allows us to expose Fruit instances over HTTP in the JSON format via JAX-RS resources.
+If you have an already created project, the neo4j extension can be added to an existing Quarkus project with the add-extension command:
./mvnw quarkus:add-extension -Dextensions="neo4j"Otherwise, you can manually add this to the dependencies section of your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.neo4j</groupId>
+ <artifactId>quarkus-neo4j</artifactId>
+ <version>3.8.0</version>
+</dependency>The Neo4j driver can be configured with standard Quarkus properties:
+# Those are the default values and are implicitly assumed
+quarkus.neo4j.uri = bolt://localhost:7687
+quarkus.neo4j.authentication.username = neo4j
+quarkus.neo4j.authentication.password = secretYou’ll recognize the authentication here that you passed on to the docker command above.
+Having done that, the driver is ready to use, there are however other configuration options, detailed below.
+Quarkus supports a feature called Dev Services that allows you to create various datasources without any config.
+In the case of Neo4j this support applies to the single Neo4j driver instance.
+Dev Services will bring up a Neo4j container if you didn’t explicit add the default values or configured custom values for
+any of quarkus.neo4j.uri, quarkus.neo4j.authentication.username or quarkus.neo4j.authentication.password.
+If Neo4j seems to be reachable via the default properties, Dev Services will also step back.
Otherwise, Quarkus will automatically start a Neo4j container when running tests or dev-mode, +and automatically configure the connection.
+When running the production version of the application, the Neo4j connection need to be configured as normal,
+so if you want to include a production database config in your application.properties and continue to use Dev Services
+we recommend that you use the %prod. profile to define your Neo4j settings.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This value can be used to specify the port to which the bolt-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j container is reachable over bolt. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+This value can be used to specify the port to which the http-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j Browser is available. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Additional environment entries that can be added to the container before its start. +
+
+Environment variable: |
+
|
++ |
The result of a statement consists usually of one or more org.neo4j.driver.Record.
+Those records contain arbitrary values, supported by the driver.
+If you return a node of the graph, it will be a org.neo4j.driver.types.Node.
We add the following method to the Fruit, as a convenient way to create them:
public static Fruit from(Node node) {
+ return new Fruit(UUID.fromString(node.get("id").asString()), node.get("name").asString());
+}Add a FruitResource skeleton like this and @Inject a org.neo4j.driver.Driver instance and a ThreadContext instance:
package org.acme.neo4j;
+
+import java.net.URI;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.CompletionStage;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DELETE;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.ResponseBuilder;
+import jakarta.ws.rs.core.Response.Status;
+
+import org.eclipse.microprofile.context.ThreadContext;
+import org.neo4j.driver.Driver;
+import org.neo4j.driver.async.AsyncSession;
+import org.neo4j.driver.async.ResultCursor;
+import org.neo4j.driver.exceptions.NoSuchRecordException;
+
+@Path("/fruits")
+@Consumes(MediaType.APPLICATION_JSON)
+@Produces(MediaType.APPLICATION_JSON)
+public class FruitResource {
+
+ @Inject
+ Driver driver;
+
+ @Inject
+ ThreadContext threadContext; (1)
+}| 1 | +The ThreadContext is related to context propagation with completion stage. A completion stage,
+unlike Mutiny, does not have a hook to automatically "capture and restore" the context.
+So, we need to use this construct in later steps when using the connections asynchronous api. |
+
Add the following method to the fruit resource:
+@GET
+public CompletionStage<Response> get() {
+ AsyncSession session = driver.session(AsyncSession.class); (1)
+ CompletionStage<List<Fruit>> cs = session
+ .executeReadAsync(tx -> tx
+ .runAsync("MATCH (f:Fruit) RETURN f ORDER BY f.name") (2)
+ .thenCompose(cursor -> cursor (3)
+ .listAsync(record -> Fruit.from(record.get("f").asNode()))));
+ return threadContext.withContextCapture(cs) (4)
+ .thenCompose(fruits -> (5)
+ session.closeAsync().thenApply(signal -> fruits))
+ .thenApply(Response::ok) (6)
+ .thenApply(ResponseBuilder::build);
+}| 1 | +Open a new, asynchronous session with Neo4j | +
| 2 | +Execute a query. This is a Cypher statement. | +
| 3 | +Retrieve a cursor, list the results and create Fruits. This must happen inside the transactional function, not outside. |
+
| 4 | +Wrap the completion stage so that the current context is captured, and restored it before calling a continuation +method of the completion stage. With that, the context is restored and available in any callback. | +
| 5 | +Close the session after processing | +
| 6 | +Create a JAX-RS response | +
Now start Quarkus in dev mode with:
./mvnw compile quarkus:devand retrieve the endpoint like this
+curl localhost:8080/fruitsThere are not any fruits, so let’s create some.
+The POST method looks similar.
+It uses transaction functions of the driver:
@POST
+public CompletionStage<Response> create(Fruit fruit) {
+ AsyncSession session = driver.session(AsyncSession.class);
+ CompletionStage<Fruit> cs = session
+ .executeWriteAsync(tx -> tx
+ .runAsync(
+ "CREATE (f:Fruit {id: randomUUID(), name: $name}) RETURN f",
+ Map.of("name", fruit.name))
+ .thenCompose(ResultCursor::singleAsync)
+ .thenApply(record -> Fruit.from(record.get("f").asNode())));
+ return threadContext.withContextCapture(cs)
+ .thenCompose(persistedFruit -> session
+ .closeAsync().thenApply(signal -> persistedFruit))
+ .thenApply(persistedFruit -> Response
+ .created(URI.create("/fruits/" + persistedFruit.id))
+ .build());
+}As you can see, we are now using a Cypher statement with named parameters (The $name of the fruit).
+The node is returned, a Fruit entity created and then mapped to a 201 created response.
A curl request against this path may look like this:
+curl -v -X "POST" "http://localhost:8080/fruits" \
+ -H 'Content-Type: application/json; charset=utf-8' \
+ -d $'{
+ "name": "Banana"
+}'The response contains an URI that shall return single nodes.
+This time, we ask for a read-only transaction. +We also add some exception handling, in case the resource is called with an invalid id:
+@GET
+@Path("/{id}")
+public CompletionStage<Response> getSingle(String id) {
+ AsyncSession session = driver.session(AsyncSession.class);
+ return threadContext.withContextCapture(session
+ .executeReadAsync(tx -> tx
+ .runAsync("MATCH (f:Fruit) WHERE f.id = $id RETURN f", Map.of("id", id))
+ .thenCompose(ResultCursor::singleAsync))
+ .handle((record, exception) -> {
+ if (exception != null) {
+ Throwable source = exception;
+ if (exception instanceof CompletionException) {
+ source = exception.getCause();
+ }
+ Status status = Status.INTERNAL_SERVER_ERROR;
+ if (source instanceof NoSuchRecordException) {
+ status = Status.NOT_FOUND;
+ }
+ return Response.status(status).build();
+ } else {
+ return Response.ok(Fruit.from(record.get("f").asNode())).build();
+ }
+ }))
+ .thenCompose(response -> session.closeAsync().thenApply(signal -> response));
+}A request may look like this:
+curl localhost:8080/fruits/42| + + | ++In case Neo4j has been setup as a cluster, the transaction mode is used to decide whether a request is routed + to a leader or a follower instance. Write transactions must be handled by a leader, whereas read-only transactions + can be handled by followers. + | +
Finally, we want to get rid of fruits again and we add the DELETE method:
@DELETE
+@Path("{id}")
+public CompletionStage<Response> delete(String id) {
+ AsyncSession session = driver.session(AsyncSession.class);
+ return threadContext.withContextCapture(session
+ .executeWriteAsync(tx -> tx
+ .runAsync("MATCH (f:Fruit) WHERE f.id = $id DELETE f", Map.of("id", id))
+ .thenCompose(ResultCursor::consumeAsync) (1)
+ ))
+ .thenCompose(response -> session.closeAsync())
+ .thenApply(signal -> Response.noContent().build());
+}| 1 | +There is no result for us, only a summary of the query executed. | +
A request may look like this
+curl -X DELETE localhost:8080/fruits/42And that’s already the most simple CRUD application with one type of nodes. +Feel free to add relationships to the model. +One idea would be to model recipes that contain fruits. +The Cypher manual linked in the introduction will help you with modelling your queries.
+Packaging your application is as simple as ./mvnw clean package.
+It can be run with java -jar target/quarkus-app/quarkus-run.jar.
With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative.
+Depending on your system, that will take some time.
If you are using the quarkus-smallrye-health extension, quarkus-neo4j will automatically add a readiness health check
+to validate the connection to Neo4j.
So when you access the /q/health/ready endpoint of your application you will have information about the connection validation status.
This behavior can be disabled by setting the quarkus.neo4j.health.enabled property to false in your application.properties.
If you are using a metrics extension and specify the config property quarkus.neo4j.pool.metrics.enabled=true, the Neo4j extension will
+expose several metrics related to the Neo4j connection pool.
There are tons of options to model your domain within a Graph. +The Neo4j docs, the sandboxes and more are a good starting point.
+If you have access to Neo4j 4.0, you can go fully reactive.
+To make life a bit easier, we will use Mutiny for this.
+| + + | +
+ Mutiny
+
+
+The following example uses Mutiny reactive types. +If you are not familiar with Mutiny, check Mutiny - an intuitive reactive programming library. + |
+
The reactive fruit resources streams the name of all fruits:
+package io.quarkus.it.neo4j;
+
+import java.util.Map;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.jboss.resteasy.reactive.ResponseStatus;
+import org.neo4j.driver.Driver;
+import org.neo4j.driver.reactive.ReactiveResult;
+import org.neo4j.driver.reactive.ReactiveSession;
+
+import io.smallrye.mutiny.Multi;
+import io.smallrye.mutiny.Uni;
+
+@Path("reactivefruits")
+@Consumes(MediaType.APPLICATION_JSON)
+public class ReactiveFruitResource {
+
+ @Inject
+ Driver driver;
+
+ static Uni<Void> sessionFinalizer(ReactiveSession session) { (1)
+ return Uni.createFrom().publisher(session.close());
+ }
+
+ @GET
+ @Produces(MediaType.SERVER_SENT_EVENTS)
+ public Multi<String> get() {
+ // Create a stream from a resource we can close in a finalizer...
+ return Multi.createFrom().resource(() -> driver.session(ReactiveSession.class), (2)
+ session -> session.executeRead(tx -> {
+ var result = tx.run("MATCH (f:Fruit) RETURN f.name as name ORDER BY f.name");
+ return Multi.createFrom().publisher(result).flatMap(ReactiveResult::records);
+ }))
+ .withFinalizer(ReactiveFruitResource::sessionFinalizer) (3)
+ .map(record -> record.get("name").asString());
+ }
+}| 1 | +A finalizer that will close a Neo4j driver session in a non-blocking fashion | +
| 2 | +The Multi.createFrom().resource() is used to defer the creation of session until the publisher is subscribed to |
+
| 3 | +When the publisher is done, the finalizer will be called | +
driver.rxSession() returns a reactive session.
+It exposes its API based on Reactive Streams, most prominently, as org.reactivestreams.Publisher.
+Those can be used directly, but we found it easier and more expressive to wrap them in reactive types such as the one provided by Mutiny.
+Typically, in the previous code, the session is closed when the stream completes, fails or the subscriber cancels.
If you want to return a Mutiny! Uni object, you need to be very careful before you convert a Multi into a Uni:
+The conversion works in such a way, that the first item is emitted and then a cancellation signal is sent to the publisher,
+that will propagate upto the drivers' session, indicating a cancellation of the transaction, thus doing a rollback.
In most cases you are better off returning a Multi or just a generic Publisher. If you need a Uni, you can still realize
+this with an emitter:
@POST
+@Produces(MediaType.TEXT_PLAIN)
+@ResponseStatus(201)
+public Uni<String> create(Fruit fruit) {
+
+ return Uni.createFrom().emitter(e -> Multi.createFrom().resource(() -> driver.session(ReactiveSession.class), (1)
+ session -> session.executeWrite(tx -> {
+ var result = tx.run(
+ "CREATE (f:Fruit {id: randomUUID(), name: $name}) RETURN f",
+ Map.of("name", fruit.name));
+ return Multi.createFrom().publisher(result).flatMap(ReactiveResult::records);
+ }))
+ .withFinalizer(ReactiveFruitResource::sessionFinalizer)
+ .map(record -> Fruit.from(record.get("f").asNode()))
+ .toUni()
+ .subscribe().with( (2)
+ persistedFruit -> e.complete("/fruits/" + persistedFruit.id)));
+}| 1 | +Here we use Uni.createFrom().emitter() to retrieve an UniEmitter that we use in 2. |
+
| 2 | +Notice how we subscribe to a Multi setup in a similar fashion as in the prior example. The subscription will emit the one
+and only item via the emitter, without a cancellation event. |
+
| + + | +
+Each of the neo4j and bolt URI schemes permit variants that contain extra encryption and trust information.
+ The +s variants enable encryption with a full certificate check, and the +ssc variants enable encryption,
+ but with no certificate check. This latter variant is designed specifically for use with self-signed certificates.
+ The variants are basically shortcuts over explicit configuration. If you use one of them, Quarkus won’t pass
+ quarkus.neo4j.encrypted and related to the driver creation as the driver prohibits this.
+ + The only check applied when Quarkus detects a secure url (either of +s or +ssc) is to ensure availability of
+ SSL in native image and will throw ConfigurationException if it isn’t available.
+ |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This value can be used to specify the port to which the bolt-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j container is reachable over bolt. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+This value can be used to specify the port to which the http-port of the container is exposed. It must be a free port, otherwise startup will fail. A random, free port will be used by default. Either way, a messsage will be logged on which port the Neo4j Browser is available. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The uri this driver should connect to. The driver supports bolt, bolt+routing or neo4j as schemes. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If the driver should use encrypted traffic. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configure the maximum time transactions are allowed to retry. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Additional environment entries that can be added to the container before its start. +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+The login of the user connecting to the database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The password of the user connecting to the database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Set this to true to disable authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional field that when is not empty has precedence over
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Configures which trust strategy to apply when using encrypted traffic. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+The file of the certificate to use. +
+
+Environment variable: |
+path |
++ |
+
+
+
+
+
+If hostname verification is used. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Flag, if metrics are enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Flag, if leaked sessions logging is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The maximum amount of connections in the connection pool towards a single database. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Pooled connections that have been idle in the pool for longer than this timeout will be tested before they are used again. The value
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Pooled connections older than this threshold will be closed and removed from the pool. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Acquisition of new connections will be attempted for at most configured timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+The format for durations uses the standard
+
+You can also provide duration values starting with a number.
+In this case, if the value consists only of a number, the converter treats the value as seconds.
+Otherwise, |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether ngrok should be started when Quarkus dev-mode is launched. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory into which to save the ngrok binary if it doesn’t exist +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Specify a download URL where the ngrok distribution will be obtained from. If not set, the platform default will be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The authentication token used to authenticate this client when it connects to the ngrok.com service +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The region where the ngrok agent will connect to host its tunnels +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The port where ngrok will be serving the local web interface and api +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The domain or hostname to use instead of the one ngrok generates. See https://ngrok.com/blog-post/free-static-domains-ngrok-users +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Name of the tunnel to start from ngrok default config instead of Quarkus configuration. Useful to use extended ngrok configuration. +
+
+Environment variable: |
+string |
++ |
This Quarkus extension integrates [ngrok](https://ngrok.com/) into Quarkus Dev Mode thus allowing users to expose their application to the public internet while they are still developing it.
+| + + | ++The extension has absolutely no impact on the production Quarkus application + | +
If you want to use this extension, you need to add the io.quarkiverse.ngrok:quarkus-ngrok extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.ngrok</groupId>
+ <artifactId>quarkus-ngrok</artifactId>
+</dependency>Add the extension to the application’s dependencies ./mvnw quarkus:add-extension -Dextensions="io.quarkiverse.ngrok:quarkus-ngrok"
Get a [ngrok auth token](https://ngrok.com/docs/getting-started/#step-2-connect-your-account) and configure it using ngrok or set it via quarkus.ngrok.authtoken
A short while after the application has started, you should see something in the application logs like:
+ngrok is running and its web interface can be accessed at: 'http://localhost:4040'
+The application can be accessed publicly over the internet using: 'http://4f59-68-81-186-238.ngrok-free.app'Use the .ngrok-free.app URL to access the running application from the public internet
You can get a stable url by setting quarkus.ngrok.domain to a domain you own and have configured in ngrok.
Tip: ngrok at current time of writing offer a free domain per user for free. See details at https://ngrok.com/blog-post/free-static-domains-ngrok-users.
+For further customization of ngrok, assign quarkus.ngrok.tunnel-name to a named tunnel specified in your ngrok configuration file for your operating system. Quarkus will then utilize that configuration instead.
Example, set this in your application.properties:
quarkus.ngrok.tunnel-name=${quarkus.application.name}And lets say your app is named quarkus-my-app then in your ngrok.yml file:
version: 2
+tunnels:
+ quarkus-my-app:
+ proto: http
+ addr: 8080
+ bind_tls: true
+ basic_auth:
+ - "bob:bobpassword"
+ domain: my-app.ngrok.ioThen Quarkus will launch ngrok using ngrok start quarkus-my-app and use that specific named tunnel configuration.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether ngrok should be started when Quarkus dev-mode is launched. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory into which to save the ngrok binary if it doesn’t exist +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Specify a download URL where the ngrok distribution will be obtained from. If not set, the platform default will be used +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The authentication token used to authenticate this client when it connects to the ngrok.com service +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The region where the ngrok agent will connect to host its tunnels +
+
+Environment variable: |
+
+
|
++ |
+
+
+
+
+
+The port where ngrok will be serving the local web interface and api +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The domain or hostname to use instead of the one ngrok generates. See https://ngrok.com/blog-post/free-static-domains-ngrok-users +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Name of the tunnel to start from ngrok default config instead of Quarkus configuration. Useful to use extended ngrok configuration. +
+
+Environment variable: |
+string |
++ |
A Quarkus extension that lets you utilize OmniFaces library to make JSF development so much easier!
+If you want to use this extension, you need to add the io.quarkiverse.omnifaces:quarkus-omnifaces extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.omnifaces</groupId>
+ <artifactId>quarkus-omnifaces</artifactId>
+ <version>4.3.0</version>
+</dependency>This extension is for REST code generation for client side only. If you’re looking for code generation for the server side, please take a look at the Quarkus OpenAPI Generator Server Extension.
+Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.
+Add the following dependency to your project’s pom.xml file:
| + + | ++Version 2.x.x of this extension supports Quarkus 3, and version 1.x.x supports Quarkus 2. We strongly recommend you to use version 2.x.x. No updates are planned for version 1.x.x. + | +
<dependency>
+ <groupId>io.quarkiverse.openapi.generator</groupId>
+ <artifactId>quarkus-openapi-generator</artifactId>
+ <version>3.0.0-SNAPSHOT</version>
+</dependency>You will also need to add or update the quarkus-maven-plugin configuration with the following:
| + + | +
+You probably already have this configuration if you created your application with Code Quarkus. That said, double-check your configuration not to add another plugin entry.
+ |
+
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ <goal>generate-code-tests</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Now, create the directory openapi under your src/main/ path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.
If you want to change the directory where OpenAPI files must be found, use the property quarkus.openapi-generator.codegen.input-base-dir.
+IMPORTANT: it is relative to the project base directory. For example, if you have a project called MyJavaProject and decide to place them in MyJavaProject/openapi-definitions, use the following property:
quarkus.openapi-generator.codegen.input-base-dir=openapi-definitionsTo fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-model-type-annotations=@org.test.Foo;@org.test.BarIf you want to change the base package in which the classes are generated, use the quarkus.openapi-generator.codegen.spec.<filename>.base-package property.
+If a base package is not provided, it will default to org.openapi.quarkus.<filename>. For example, org.openapi.quarkus.petstore_json.
quarkus.openapi-generator.codegen.spec.petstore_json.base-package=org.acmeConfiguring additional-model-type-annotations will add all annotations to the generated model files (extra details can be found in OpenApi Generator Doc).
You can customize the name of generated classes. To do that, you must define the following properties:
+quarkus.openapi-generator.codegen.spec.petstore_json.api-name-suffix=CustomApiSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-suffix=CustomModelSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-prefix=CustomModelPrefixThe same way you can add any additional annotations to the generated api files with additional-api-type-annotations. Given you want to include Foo and Bar annotations, you must define additional-api-type-annotations as:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-api-type-annotations=@org.test.Foo;@org.test.Bar| + + | +
+Note that the file name`petstore_json`is used to configure the specific information for each spec. We follow the Environment Variables Mapping Rules from Microprofile Configuration to sanitize the OpenAPI spec filename. Any non-alphabetic characters are replaced by an underscore _.
+ |
+
Run mvn compile to generate your classes in target/generated-sources/open-api-json path:
- org.acme.openapi
+ - api
+ - PetApi.java
+ - StoreApi.java
+ - UserApi.java
+ - model
+ - Address.java
+ - Category.java
+ - Customer.java
+ - ModelApiResponse.java
+ - Order.java
+ - Pet.java
+ - Tag.java
+ - User.javaYou can reference the generated code in your project, for example:
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.acme.openapi.api.PetApi;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.jboss.resteasy.annotations.jaxrs.PathParam;
+
+@Produces(MediaType.APPLICATION_JSON)
+@Path("/petstore")
+public class PetResource {
+
+ @RestClient
+ @Inject
+ PetApi petApi;
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+You can use the quarkus-openapi-generator with REST Client Classic or REST Client Reactive respectively. To do so add either the classic or reactive jackson dependency to your project’s pom.xml file:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-rest-client-jackson</artifactId>
+</dependency>| + + | ++After Version 1.2.1 / 2.1.1 you need to declare the above dependency explicitly! Even if you stay with the REST Client Classic implementation! + | +
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-rest-client-reactive-jackson</artifactId>
+</dependency>To make truly non-blocking calls, you need to also set the mutiny option to true. This
+will wrap all API return types in a io.smallrye.mutiny.Uni.
quarkus.openapi-generator.codegen.spec.my_openapi_yaml.mutiny=trueWhen using RESTEasy Reactive:
+The client must not declare multiple MIME-TYPES with @Consumes
You might need to implement a ParamConverter for each complex type
Response objectsBy default, this extension generates the methods according to their returning models based on the OpenAPI specification Schema Object. If no response model is defined, jakarta.ws.rs.core.Response is returned.
If you want to return jakarta.ws.rs.core.Response in all cases instead, you can set the return-response property to true.
Since the most part of this extension work is in the generate-code execution phase of the Quarkus Maven’s plugin, the log configuration must be set in the Maven context. When building your project, add -Dorg.slf4j.simpleLogger.log.org.openapitools=off to the mvn command to reduce the internal generator noise. For example:
mvn clean install -Dorg.slf4j.simpleLogger.log.org.openapitools=offFor more information, see the Maven Logging Configuration and Maven Configuration guides.
+By default, the extension will process every OpenAPI specification file in the given path.
+To limit code generation to only a specific set of OpenAPI specification files, you can set the quarkus.openapi-generator.codegen.include property.
For instance, if you want to limit code generation for include-openapi.yaml and include-openapi-2.yaml files, you need to define the property like:
quarkus.openapi-generator.codegen.include=include-openapi.yaml,include-openapi-2.yamlIf you prefer to specify which files you want to skip, you can set the quarkus.openapi-generator.codegen.exclude property.
+For instance, if you want to skip code generation for exclude-openapi.yaml and exclude-openapi-2.yaml files, you need to define the property like:
quarkus.openapi-generator.codegen.exclude=exclude-openapi.yaml,exclude-openapi-2.yaml| + + | +
+exclude supersedes include, meaning that if a file is in both property it will NOT be analysed.
+ |
+
See the module integration-tests/ignore for an example of how to use this feature.
If your OpenAPI specification file has securitySchemes definitions, the inner generator
+will register ClientRequestFilter providers for you to
+implement the given authentication mechanism.
To provide the credentials for your application, you can use the Quarkus configuration support. The configuration key is composed using this
+pattern: quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]. Where:
filename is the sanitized name of file containing the OpenAPI spec, for example petstore_json.
security_scheme_name is the sanitized name of the security scheme object definition in the OpenAPI file. Given the following excerpt, we
+have api_key and basic_auth security schemes:
{
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "basic_auth": {
+ "type": "http",
+ "scheme": "basic"
+ }
+ }
+}| + + | ++Note that the securityScheme name used to configure the specific information for each spec is sanitized using the same rules as for the file names. + | +
auth_property_name varies depending on the authentication provider. For example, for Basic Authentication we have username and password. See the following sections for more details.
++++Tip: on production environments you will likely to use HashiCorp Vault or Kubernetes Secrets to provide this information for your application.
+
If the OpenAPI specification file has securitySchemes definitions, but no Security Requirement Object definitions, the generator can be configured to create these by default. In this case, for all operations without a security requirement the default one will be created. Note that the property value needs to match the name of a security scheme object definition, eg. api_key or basic_auth in the securitySchemes list above.
| Description | +Property Key | +Example | +
|---|---|---|
Create security for the referenced security scheme |
+
|
+
|
+
See the module security for an example of how to use this feature.
+For Basic HTTP Authentication, these are the supported configurations:
+| Description | +Property Key | +Example | +
|---|---|---|
Username credentials |
+
|
+
|
+
Password credentials |
+
|
+
|
+
Authentication, these are the supported configurations:
+| Description | +Property Key | +Example | +
|---|---|---|
Bearer Token |
+
|
+
|
+
Similarly to bearer token, the API Key Authentication also has the token entry key property:
+| Description | +Property Key | +Example | +
|---|---|---|
API Key |
+
|
+
|
+
The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you.
+The extension will generate a ClientRequestFilter capable to add OAuth2 authentication capabilities to the OpenAPI operations that require it. This means that you can use
+the Quarkus OIDC Extension configuration to define your authentication flow.
The generated code creates a named OidcClient for each Security Scheme listed in the OpenAPI specification files. For example, given
+the following excerpt:
{
+ "securitySchemes": {
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://petstore3.swagger.io/oauth/authorize",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}You can configure this OidcClient as:
quarkus.oidc-client.petstore_auth.auth-server-url=https://petstore3.swagger.io/oauth/authorize
+quarkus.oidc-client.petstore_auth.discovery-enabled=false
+quarkus.oidc-client.petstore_auth.token-path=/tokens
+quarkus.oidc-client.petstore_auth.credentials.secret=secret
+quarkus.oidc-client.petstore_auth.grant.type=password
+quarkus.oidc-client.petstore_auth.grant-options.password.username=alice
+quarkus.oidc-client.petstore_auth.grant-options.password.password=alice
+quarkus.oidc-client.petstore_auth.client-id=petstore-appThe configuration suffix quarkus.oidc-client.petstore_auth is exclusive for the schema defined in the specification file and the schemaName is sanitized by applying the rules described above.
For this to work you must add Quarkus OIDC Client Filter Extension to your project:
+RESTEasy Classic:
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-oidc-client-filter</artifactId>
+</dependency>RESTEasy Reactive:
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-oidc-client-reactive-filter</artifactId>
+</dependency>If authentication support doesn’t suit your needs you can decide to disable it with enable-security-generation=false. In such case CompositeAuthenticationProvider and AuthenticationPropagationHeadersFactory wont be generated and used with your api.
+The option can be set globally with quarkus.openapi-generator.codegen.enable-security-generation or per api quarkus.openapi-generator.codegen.spec.my_spec_yml.enable-security-generation
+Custom authentication provider can be used with additional-api-type-annotations
See the module generation-tests for an example of how to use this feature.
+The authorization token propagation can be used with OpenApi operations secured with a security scheme of type "oauth2" or "bearer". +When configured, you can propagate the authorization tokens passed to your service and the invocations to the REST clients generated by the quarkus-openapi-generator.
+Let’s see how it works by following a simple example:
+Imagine that we have a updatePet operation defined in the petstore.json specification file and secured with the petstore_auth security scheme.
+The code below shows a simple example of the usage of this operation in a user-programmed service.
import org.acme.api.PetApi;
+import org.acme.model.Pet;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+/**
+ * User programmed service.
+ */
+@Path("/petstore")
+public class PetResource {
+
+ /**
+ * Inject the rest client generated by the quarkus-openapi-generator.
+ */
+ @Inject
+ @RestClient
+ PetApi petApi;
+
+ /**
+ * User programmed operation.
+ */
+ @Path("/pet/{id}")
+ @PATCH
+ @Produces(MediaType.APPLICATION_JSON)
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response customUpdatePet(@PathParam("id") long id, PetData petData) {
+
+ // Create a new instance of the Pet class generated by the quarkus-openapi-generator and
+ // populate accordingly.
+ Pet pet = new Pet();
+ pet.setId(id);
+ applyDataToPet(pet, petData);
+
+ // Execute the rest call using the generated client.
+ // The petstore.json open api spec stays that the "updatePet" operation is secured with the
+ // security scheme "petstore_auth".
+ petApi.updatePet(pet);
+
+ // Do other required things and finally return something.
+ return Response.ok().build();
+ }
+
+ public static class PetData {
+ // Represents the Pet modifiable data sent to the user programmed service.
+ }
+
+ private void applyDataToPet(Pet pet, PetData petData) {
+ // Set the corresponding values to the Pet instance.
+ }
+}Let’s see what happens when the PetResource service customUpdatePet operation is invoked by a third party.
The customUpdatePet operation is invoked.
An authorization token is obtained using the corresponding petstore_auth OidcClient configuration. (for more information see OAuth2 Authentication)
The authorization token is automatically passed along the PetApi updatePet operation execution using an automatically generated request filter, etc.
However, there are scenarios where we want to propagate the authorization token that was initially passed to the PetResource service when the customUpdatePet operation was invoked instead of having to obtain it by using the OidcClient.
The user service customUpdatePet operation is invoked, and an authorization token is passed by the third party typically by using the HTTP Authorization header.
The incoming authorization token is automatically passed along the PetApi updatePet operation execution according to the user-provided configuration.
| + + | +
+When configured, the token propagation applies to all the operations secured with the same securityScheme in the same specification file.
+ |
+
The token propagation can be used with type "oauth2" or "bearer" security schemes. Finally, considering that a given security scheme might be configured on a set of operations in the same specification file when configured, it’ll apply to all these operations.
+| Property Key | +Example | +
|---|---|
|
+
|
+
|
+
|
+
You can define the CircuitBreaker annotation from MicroProfile Fault Tolerance
+in your generated classes by setting the desired configuration in application.properties.
Let’s say you have the following OpenAPI definition:
+{
+ "openapi": "3.0.3",
+ "info": {
+ "title": "Simple API",
+ "version": "1.0.0-SNAPSHOT"
+ },
+ "paths": {
+ "/hello": {
+ "get": {
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/bye": {
+ "get": {
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}And you want to configure Circuit Breaker for the /bye endpoint, you can do it in the following way:
Add the SmallRye Fault Tolerance extension to your project’s pom.xml file:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
+</dependency>Assuming your Open API spec file is in src/main/openapi/simple-openapi.json, add the following configuration to your application.properties file:
# Note that the file name must have only alphabetic characters or underscores (_).
+quarkus.openapi-generator.codegen.spec.simple_openapi_json.base-package=org.acme.openapi.simple
+# Enables the CircuitBreaker extension for the byeGet method from the DefaultApi class
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/enabled=trueWith the above configuration, your Rest Clients will be created with a code similar to the following:
+package org.acme.openapi.simple.api;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.List;
+import java.util.Map;
+
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("")
+@RegisterRestClient(configKey="simple-openapi_json")
+public interface DefaultApi {
+
+ @GET
+ @Path("/bye")
+ @Produces({ "text/plain" })
+ @org.eclipse.microprofile.faulttolerance.CircuitBreaker
+ public String byeGet();
+
+ @GET
+ @Path("/hello")
+ @Produces({ "text/plain" })
+ public String helloGet();
+
+}You can also override the default Circuit Breaker configuration by setting the properties
+in application.properties just as you would for a traditional MicroProfile application:
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failOn=java.lang.IllegalArgumentException,java.lang.NullPointerException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/skipOn=java.lang.NumberFormatException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delay=33
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delayUnit=MILLIS
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/requestVolumeThreshold=42
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio=3.14
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold=22See the module circuit-breaker for an example of how to use this feature.
+The rest client also supports request with mime-type multipart/form-data and, if the schema of the request body is known in advance, we can also automatically generate the models of the request +bodies.
+| + + | ++RESTEasy Reactive supports multipart/form-data out of the box. Thus, no additional dependency is required. + | +
If you’re using RESTEasy Classic, you need to add the following additional dependency to your pom.xml:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy-multipart</artifactId>
+</dependency>For any multipart/form-data operation a model for the request body will be generated. Each part of the multipart is a field in this model that is annotated with the following annotations:
+jakarta.ws.rs.FormParam, where the value parameter denotes the part name,
PartType, where the parameter is the jax-rs MediaType of the part (see below for details),
and, if the part contains a file, PartFilename, with a generated default parameter that will be passed as the fileName sub-header in the
+Content-Disposition header of the part.
For example, the model for a request that requires a file, a string and some complex object will look like this:
+public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("fileFile")
+ public File file;
+
+ @FormParam("fileName")
+ @PartType(MediaType.TEXT_PLAIN)
+ public String fileName;
+
+ @FormParam("someObject")
+ @PartType(MediaType.APPLICATION_JSON)
+ public MyComplexObject someObject;
+}Then in the client, when using RESTEasy Classic, the org.jboss.resteasy.annotations.providers.multipart.MultipartForm annotation is added in front of the multipart parameter:
@Path("/echo")
+@RegisterRestClient(baseUri="http://my.endpoint.com/api/v1", configKey="multipart-requests_yml")
+public interface MultipartService {
+
+ @POST
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ @Produces(MediaType.TEXT_PLAIN)
+ String sendMultipartData(@MultipartForm MultipartBody data);
+
+}When using RESTEasy Reactive, the jakarta.ws.rs.BeanParam annotation is added in front of the multipart parameter:
@Path("/echo")
+@RegisterRestClient(baseUri="http://my.endpoint.com/api/v1", configKey="multipart-requests_yml")
+public interface MultipartService {
+
+ @POST
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ @Produces(MediaType.TEXT_PLAIN)
+ String sendMultipartData(@jakarta.ws.rs.BeanParam MultipartBody data);
+
+}See Quarkus - Using the REST Client with Multipart and +the RESTEasy JAX-RS specifications for more details.
+| + + | +
+MultipartForm is deprecated when using RESTEasy Reactive.
+ |
+
baseURI value of RegisterRestClient annotation is extracted from the servers section of the file, if present. If not, it will be left empty and it is expected you set up the uri to be used in your configuration.
Importantly, if some multipart request bodies contain complex objects (i.e. non-primitives) you need to explicitly tell the Open API generator to create models for these objects by setting
+the skip-form-model property corresponding to your spec in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.skip-form-model=falseSee the module multipart-request for an example of how to use this feature.
+In case the default PartFilename annotation is not required, its generation can be disabled by setting the generate-part-filename property (globally or corresponding to your spec) in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.generate-part-filename=falseBy default, the PartFilename value representing the filename is prefixed by the field name. This can be changed by setting the use-field-name-in-part-filename property (globally or corresponding to your spec) in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.use-field-name-in-part-filename=falseAnd in case the default PartFilename value is not suitable (e.g. a conversion service only allows/supports specific extensions), the value can be set by using the part-filename-value property (globally or corresponding to your spec) in the application.properties, e.g.:
quarkus.openapi-generator.codegen.spec.my_first_multipart_requests_yml.part-filename-value=".pdf"So for instance, by setting part-filename-value to some.pdf and use-field-name-in-part-filename to false the generated code will look like this:
public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("some.pdf")
+ public File file;
+}And by setting only part-filename-value to .pdf, the generated code will look like this:
public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("file.pdf")
+ public File file;
+}See the module part-filename for examples of how to use these features.
+The OAS 3.0 specifies the following default content-types for a multipart:
+If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain
If the property is complex, or an array of complex values, the default Content-Type is application/json
If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream
A different content-type may be defined in your api spec, but this is not yet supported in the code generation. Also, this "annotation-oriented" approach of RestEasy (i.e. using @MultipartForm to
+denote the multipart body parameter) does not seem to properly support the unmarshalling of arrays of the same type (e.g. array of files), in these cases it uses Content-Type equal
+to application/json.
Having the files in the src/main/openapi directory will generate the REST stubs by default. Alternatively, you can implement
+the io.quarkiverse.openapi.generator.deployment.codegen.OpenApiSpecInputProvider
+interface to provide a list of `InputStream`s of OpenAPI specification files. This is useful in scenarios where you want to dynamically generate the client code without having the target spec file
+saved locally in your project.
See the example implementation here
+The domain objects are classes generated in the model package. These classes might have deprecated attributes in the Open API specification
+file. By default, these attributes are generated. You can fine tune this behavior if the deprecated attributes should not be generated.
Use the property key <base_package>.model.MyClass.generateDeprecated=false to disable the deprecated attributes in the given model. For example org.acme.weather.Country.generatedDeprecated=false.
The client objects are classes generated in the api package. These classes might have deprecated operations in the Open API specification
+file. By default, these operations are generated. You can fine tune this behavior if the deprecated operations should not be generated.
Use the property key <base_package>.api.MyClass.generateDeprecated=false to disable the deprecated operations in the given API. For example org.acme.openapi.simple.api.DefaultApi.generatedDeprecated=false.
package org.acme.openapi.simple.api;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.List;
+import java.util.Map;
+
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("")
+@RegisterRestClient(configKey="simple-openapi_json")
+@RegisterProvider(org.test.Foo.class)
+@RegisterProvider(org.test.Bar.class)
+public interface DefaultApi {
+
+ @GET
+ @Path("/bye")
+ @Produces({ "text/plain" })
+ @org.eclipse.microprofile.faulttolerance.CircuitBreaker
+ public String byeGet();
+}See the module integration-tests/register-provider for an example of how to use this feature.
Use the property key quarkus.openapi-generator.codegen.validateSpec=false to disable validating the input specification file before code generation. By default, invalid specifications will result in an error.
It’s possible to remap types in the generated files. For example, instead of a File you can configure the code generator to use InputStream for all file upload parts of multipart request, or you could change all UUID types to String. You can configure this in your application.properties using the following configuration keys:
| Description | +Property Key | +Example | +
|---|---|---|
Type Mapping |
+
|
+
|
+
Import Mapping |
+
|
+
|
+
Note that these configuration properties are maps. For the type-mapping the keys are OAS data types and the values are Java types.
+Another common example is needing java.time.Instant as type for date-time fields in your POJO classes. You can achieve with these settings:
quarkus.openapi-generator.codegen.spec.my_spec_yml.type-mappings.DateTime=Instant
+quarkus.openapi-generator.codegen.spec.my_spec_yml.import-mappings.Instant=java.time.InstantIt’s also possible to only use a type mapping with a fully qualified name, for instance quarkus.openapi-generator.codegen.spec.my_spec_yml.type-mappings.File=java.io.InputStream. For more information and a list of all types see the OpenAPI generator documentation on Type Mappings and Import Mappings.
See the module type-mapping for an example of how to use this feature.
+By default, the @RegisterRestClient configKey property is the sanitized name of the file containing the OpenAPI spec. For example, if the file name is petstore.json, the configKey will be petstore_json:
/* omitted */
+@RegisterRestClient(configKey="petstore_json")
+public interface DefaultApi { /* omitted */ }If you want to use a different configKey than the default one, you can set the quarkus.openapi-generator.codegen.spec.petstore_json.[config-key] property.
Using the config-key the extension allow you to define all allowed properties with quarkus.openapi-generator.codegen.spec.[my_custom_config_key].* prefix. For example:
quarkus.openapi-generator.codegen.spec.petstore_json.config-key=petstore
+quarkus.openapi-generator.codegen.spec.petstore.additional-api-type-annotations=@org.test.FooWith it, you will have the following result:
+/* omitted */
+@RegisterRestClient(configKey="petstore")
+@org.test.Foo
+public interface DefaultApi { /* omitted */ }| + + | ++If you configure the property config-key, it will override the sanitized file name (will not consider the order of the configurations). For example, having the following configuration: + | +
quarkus.openapi-generator.codegen.spec.petstore_json.config-key=custom_config_key
+quarkus.openapi-generator.codegen.spec.custom_config_key.additional-api-type-annotations=@org.test.Foo
+quarkus.openapi-generator.codegen.spec.petstore_json.additional-api-type-annotations=@org.test.BarThe generated code will be:
+/* omitted */
+@RegisterRestClient(configKey="custom_config_key")
+@org.test.Foo
+public interface DefaultApi { /* omitted */ }You have the option to swap out the templates used by this extension with your customized versions. To achieve this, place your custom templates under the resources/templates directory. It’s crucial that the filename of each custom template matches that of the original template.
You can find an example of using customized templates in integration-tests/custom-templates.
+| + + | ++While the option to replace templates exists, it’s essential to exercise caution and consider this as a final resort. Prior to altering templates, exhaust all possibilities of achieving your goals through configuration settings. Modifying templates could have broader implications for the extension’s functionality and may introduce complexities. Only resort to template replacement when configuration adjustments prove insufficient for your requirements. + | +
Furthermore, be aware that customizing templates increases the risk of compatibility issues during future upgrades. Therefore, exercise discretion and weigh the benefits against the potential risks before opting for template customization.
+In some cases is necessary to use additionalProperties inside the OpenAPI specification, by default this extension creates an object that inherits a java.util.HashMap
+class. It works well, but there are some issues with Jackson on serialize/deserialize:
Serialization throws com.fasterxml.jackson.databind.exc.MismatchedInputException exception.
Deserialization Jackson does ignore plain fields.
If you want to use composition instead inheritance and serialize/deserialize with Jackson without those problems, consider to configure the additional-properties-as-attributes.
To map additionalProperties as attribute, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-properties-as-attribute=true+
This configuration implies that all models using additionalProperties will be mapped using a java.util.Map as composition.
To add custom request specific parameters you can use the additional-request-args property.
Should work with:
+@PathParam
+@QueryParam
+@CookieParam
+@FormParam
+@MatrixParam
+To use additional-request-args as attribute, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-request-args=@CookieParam("cookie") String cookie;@HeaderParam("x-correlation-id") String correlationId
+This configuration is applied to every generated method.
+These are the known limitations of this pre-release version:
+Only Jackson support
+We will work in the next few releases to address these use cases, until there please provide feedback for the current state of this extension. We also love contributions .
+In some cases is necessary to use additionalProperties inside the OpenAPI specification, by default this extension creates an object that inherits a java.util.HashMap
+class. It works well, but there are some issues with Jackson on serialize/deserialize:
Serialization throws com.fasterxml.jackson.databind.exc.MismatchedInputException exception.
Deserialization Jackson does ignore plain fields.
If you want to use composition instead inheritance and serialize/deserialize with Jackson without those problems, consider to configure the additional-properties-as-attributes.
To map additionalProperties as attribute, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-properties-as-attribute=true+
This configuration implies that all models using additionalProperties will be mapped using a java.util.Map as composition.
To add custom request specific parameters you can use the additional-request-args property.
Should work with:
+@PathParam
+@QueryParam
+@CookieParam
+@FormParam
+@MatrixParam
+To use additional-request-args as attribute, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-request-args=@CookieParam("cookie") String cookie;@HeaderParam("x-correlation-id") String correlationId
+This configuration is applied to every generated method.
+If your OpenAPI specification file has securitySchemes definitions, the inner generator
+will register ClientRequestFilter providers for you to
+implement the given authentication mechanism.
To provide the credentials for your application, you can use the Quarkus configuration support. The configuration key is composed using this
+pattern: quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]. Where:
filename is the sanitized name of file containing the OpenAPI spec, for example petstore_json.
security_scheme_name is the sanitized name of the security scheme object definition in the OpenAPI file. Given the following excerpt, we
+have api_key and basic_auth security schemes:
{
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "basic_auth": {
+ "type": "http",
+ "scheme": "basic"
+ }
+ }
+}| + + | ++Note that the securityScheme name used to configure the specific information for each spec is sanitized using the same rules as for the file names. + | +
auth_property_name varies depending on the authentication provider. For example, for Basic Authentication we have username and password. See the following sections for more details.
++++Tip: on production environments you will likely to use HashiCorp Vault or Kubernetes Secrets to provide this information for your application.
+
If the OpenAPI specification file has securitySchemes definitions, but no Security Requirement Object definitions, the generator can be configured to create these by default. In this case, for all operations without a security requirement the default one will be created. Note that the property value needs to match the name of a security scheme object definition, eg. api_key or basic_auth in the securitySchemes list above.
| Description | +Property Key | +Example | +
|---|---|---|
Create security for the referenced security scheme |
+
|
+
|
+
See the module security for an example of how to use this feature.
+For Basic HTTP Authentication, these are the supported configurations:
+| Description | +Property Key | +Example | +
|---|---|---|
Username credentials |
+
|
+
|
+
Password credentials |
+
|
+
|
+
Authentication, these are the supported configurations:
+| Description | +Property Key | +Example | +
|---|---|---|
Bearer Token |
+
|
+
|
+
Similarly to bearer token, the API Key Authentication also has the token entry key property:
+| Description | +Property Key | +Example | +
|---|---|---|
API Key |
+
|
+
|
+
The API Key scheme has an additional property that requires where to add the API key in the request token: header, cookie or query. The inner provider takes care of that for you.
+The extension will generate a ClientRequestFilter capable to add OAuth2 authentication capabilities to the OpenAPI operations that require it. This means that you can use
+the Quarkus OIDC Extension configuration to define your authentication flow.
The generated code creates a named OidcClient for each Security Scheme listed in the OpenAPI specification files. For example, given
+the following excerpt:
{
+ "securitySchemes": {
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://petstore3.swagger.io/oauth/authorize",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}You can configure this OidcClient as:
quarkus.oidc-client.petstore_auth.auth-server-url=https://petstore3.swagger.io/oauth/authorize
+quarkus.oidc-client.petstore_auth.discovery-enabled=false
+quarkus.oidc-client.petstore_auth.token-path=/tokens
+quarkus.oidc-client.petstore_auth.credentials.secret=secret
+quarkus.oidc-client.petstore_auth.grant.type=password
+quarkus.oidc-client.petstore_auth.grant-options.password.username=alice
+quarkus.oidc-client.petstore_auth.grant-options.password.password=alice
+quarkus.oidc-client.petstore_auth.client-id=petstore-appThe configuration suffix quarkus.oidc-client.petstore_auth is exclusive for the schema defined in the specification file and the schemaName is sanitized by applying the rules described above.
For this to work you must add Quarkus OIDC Client Filter Extension to your project:
+RESTEasy Classic:
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-oidc-client-filter</artifactId>
+</dependency>RESTEasy Reactive:
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-oidc-client-reactive-filter</artifactId>
+</dependency>If authentication support doesn’t suit your needs you can decide to disable it with enable-security-generation=false. In such case CompositeAuthenticationProvider and AuthenticationPropagationHeadersFactory wont be generated and used with your api.
+The option can be set globally with quarkus.openapi-generator.codegen.enable-security-generation or per api quarkus.openapi-generator.codegen.spec.my_spec_yml.enable-security-generation
+Custom authentication provider can be used with additional-api-type-annotations
See the module generation-tests for an example of how to use this feature.
+The authorization token propagation can be used with OpenApi operations secured with a security scheme of type "oauth2" or "bearer". +When configured, you can propagate the authorization tokens passed to your service and the invocations to the REST clients generated by the quarkus-openapi-generator.
+Let’s see how it works by following a simple example:
+Imagine that we have a updatePet operation defined in the petstore.json specification file and secured with the petstore_auth security scheme.
+The code below shows a simple example of the usage of this operation in a user-programmed service.
import org.acme.api.PetApi;
+import org.acme.model.Pet;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+/**
+ * User programmed service.
+ */
+@Path("/petstore")
+public class PetResource {
+
+ /**
+ * Inject the rest client generated by the quarkus-openapi-generator.
+ */
+ @Inject
+ @RestClient
+ PetApi petApi;
+
+ /**
+ * User programmed operation.
+ */
+ @Path("/pet/{id}")
+ @PATCH
+ @Produces(MediaType.APPLICATION_JSON)
+ @Consumes(MediaType.APPLICATION_JSON)
+ public Response customUpdatePet(@PathParam("id") long id, PetData petData) {
+
+ // Create a new instance of the Pet class generated by the quarkus-openapi-generator and
+ // populate accordingly.
+ Pet pet = new Pet();
+ pet.setId(id);
+ applyDataToPet(pet, petData);
+
+ // Execute the rest call using the generated client.
+ // The petstore.json open api spec stays that the "updatePet" operation is secured with the
+ // security scheme "petstore_auth".
+ petApi.updatePet(pet);
+
+ // Do other required things and finally return something.
+ return Response.ok().build();
+ }
+
+ public static class PetData {
+ // Represents the Pet modifiable data sent to the user programmed service.
+ }
+
+ private void applyDataToPet(Pet pet, PetData petData) {
+ // Set the corresponding values to the Pet instance.
+ }
+}Let’s see what happens when the PetResource service customUpdatePet operation is invoked by a third party.
The customUpdatePet operation is invoked.
An authorization token is obtained using the corresponding petstore_auth OidcClient configuration. (for more information see [_oauth2_authentication])
The authorization token is automatically passed along the PetApi updatePet operation execution using an automatically generated request filter, etc.
However, there are scenarios where we want to propagate the authorization token that was initially passed to the PetResource service when the customUpdatePet operation was invoked instead of having to obtain it by using the OidcClient.
The user service customUpdatePet operation is invoked, and an authorization token is passed by the third party typically by using the HTTP Authorization header.
The incoming authorization token is automatically passed along the PetApi updatePet operation execution according to the user-provided configuration.
| + + | +
+When configured, the token propagation applies to all the operations secured with the same securityScheme in the same specification file.
+ |
+
The token propagation can be used with type "oauth2" or "bearer" security schemes. Finally, considering that a given security scheme might be configured on a set of operations in the same specification file when configured, it’ll apply to all these operations.
+| Property Key | +Example | +
|---|---|
|
+
|
+
|
+
|
+
You can define the CircuitBreaker annotation from MicroProfile Fault Tolerance
+in your generated classes by setting the desired configuration in application.properties.
Let’s say you have the following OpenAPI definition:
+{
+ "openapi": "3.0.3",
+ "info": {
+ "title": "Simple API",
+ "version": "1.0.0-SNAPSHOT"
+ },
+ "paths": {
+ "/hello": {
+ "get": {
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/bye": {
+ "get": {
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "text/plain": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}And you want to configure Circuit Breaker for the /bye endpoint, you can do it in the following way:
Add the SmallRye Fault Tolerance extension to your project’s pom.xml file:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
+</dependency>Assuming your Open API spec file is in src/main/openapi/simple-openapi.json, add the following configuration to your application.properties file:
# Note that the file name must have only alphabetic characters or underscores (_).
+quarkus.openapi-generator.codegen.spec.simple_openapi_json.base-package=org.acme.openapi.simple
+# Enables the CircuitBreaker extension for the byeGet method from the DefaultApi class
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/enabled=trueWith the above configuration, your Rest Clients will be created with a code similar to the following:
+package org.acme.openapi.simple.api;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.List;
+import java.util.Map;
+
+import jakarta.ws.rs.*;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("")
+@RegisterRestClient(configKey="simple-openapi_json")
+public interface DefaultApi {
+
+ @GET
+ @Path("/bye")
+ @Produces({ "text/plain" })
+ @org.eclipse.microprofile.faulttolerance.CircuitBreaker
+ public String byeGet();
+
+ @GET
+ @Path("/hello")
+ @Produces({ "text/plain" })
+ public String helloGet();
+
+}You can also override the default Circuit Breaker configuration by setting the properties
+in application.properties just as you would for a traditional MicroProfile application:
org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failOn=java.lang.IllegalArgumentException,java.lang.NullPointerException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/skipOn=java.lang.NumberFormatException
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delay=33
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/delayUnit=MILLIS
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/requestVolumeThreshold=42
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/failureRatio=3.14
+org.acme.openapi.simple.api.DefaultApi/byeGet/CircuitBreaker/successThreshold=22See the module circuit-breaker for an example of how to use this feature.
+By default, the @RegisterRestClient configKey property is the sanitized name of the file containing the OpenAPI spec. For example, if the file name is petstore.json, the configKey will be petstore_json:
/* omitted */
+@RegisterRestClient(configKey="petstore_json")
+public interface DefaultApi { /* omitted */ }If you want to use a different configKey than the default one, you can set the quarkus.openapi-generator.codegen.spec.petstore_json.[config-key] property.
Using the config-key the extension allow you to define all allowed properties with quarkus.openapi-generator.codegen.spec.[my_custom_config_key].* prefix. For example:
quarkus.openapi-generator.codegen.spec.petstore_json.config-key=petstore
+quarkus.openapi-generator.codegen.spec.petstore.additional-api-type-annotations=@org.test.FooWith it, you will have the following result:
+/* omitted */
+@RegisterRestClient(configKey="petstore")
+@org.test.Foo
+public interface DefaultApi { /* omitted */ }| + + | ++If you configure the property config-key, it will override the sanitized file name (will not consider the order of the configurations). For example, having the following configuration: + | +
quarkus.openapi-generator.codegen.spec.petstore_json.config-key=custom_config_key
+quarkus.openapi-generator.codegen.spec.custom_config_key.additional-api-type-annotations=@org.test.Foo
+quarkus.openapi-generator.codegen.spec.petstore_json.additional-api-type-annotations=@org.test.BarThe generated code will be:
+/* omitted */
+@RegisterRestClient(configKey="custom_config_key")
+@org.test.Foo
+public interface DefaultApi { /* omitted */ }Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma-separated list of absolute resource paths to scan recursively for templates. All tree folder from 'resource-paths' will be added as a resource. Unprefixed locations or locations starting with classpath will be processed in the same way. + |
+list of string |
+
|
+
+
+
+
+
+
+Comma-separated of file system paths where freemarker templates are located + |
+list of string |
++ |
+
+
+
+
+
+Set the preferred charset template files are stored in. + |
+string |
++ |
+
+
+
+
+
+Sets how errors will appear. rethrow, debug, html-debug, ignore. + |
+string |
++ |
+
+
+
+
+
+If false, don’t log exceptions inside FreeMarker that it will be thrown at you anyway. + |
+boolean |
++ |
+
+
+
+
+
+Wrap unchecked exceptions thrown during template processing into TemplateException-s. + |
+boolean |
++ |
+
+
+
+
+
+If false, do not fall back to higher scopes when reading a null loop variable. + |
+boolean |
++ |
+
+
+
+
+
+The string value for the boolean |
+string |
++ |
+
+
+
+
+
+Sets the default number format used to convert numbers to strings. + |
+string |
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
+
+
+
+
+
+List of directives to register with format name=classname + |
+
|
++ |
+
+
+
+
+
+If true, the object wrapper will be configured to expose fields. + |
+boolean |
++ |
By default, the extension will process every OpenAPI specification file in the given path.
+To limit code generation to only a specific set of OpenAPI specification files, you can set the quarkus.openapi-generator.codegen.include property.
For instance, if you want to limit code generation for include-openapi.yaml and include-openapi-2.yaml files, you need to define the property like:
quarkus.openapi-generator.codegen.include=include-openapi.yaml,include-openapi-2.yamlIf you prefer to specify which files you want to skip, you can set the quarkus.openapi-generator.codegen.exclude property.
+For instance, if you want to skip code generation for exclude-openapi.yaml and exclude-openapi-2.yaml files, you need to define the property like:
quarkus.openapi-generator.codegen.exclude=exclude-openapi.yaml,exclude-openapi-2.yaml| + + | +
+exclude supersedes include, meaning that if a file is in both property it will NOT be analysed.
+ |
+
See the module integration-tests/ignore for an example of how to use this feature.
Add the following dependency to your project’s pom.xml file:
| + + | ++Version 2.x.x of this extension supports Quarkus 3, and version 1.x.x supports Quarkus 2. We strongly recommend you to use version 2.x.x. No updates are planned for version 1.x.x. + | +
<dependency>
+ <groupId>io.quarkiverse.openapi.generator</groupId>
+ <artifactId>quarkus-openapi-generator</artifactId>
+ <version>3.0.0-SNAPSHOT</version>
+</dependency>You will also need to add or update the quarkus-maven-plugin configuration with the following:
| + + | +
+You probably already have this configuration if you created your application with Code Quarkus. That said, double-check your configuration not to add another plugin entry.
+ |
+
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ <goal>generate-code-tests</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Now, create the directory openapi under your src/main/ path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.
If you want to change the directory where OpenAPI files must be found, use the property quarkus.openapi-generator.codegen.input-base-dir.
+IMPORTANT: it is relative to the project base directory. For example, if you have a project called MyJavaProject and decide to place them in MyJavaProject/openapi-definitions, use the following property:
quarkus.openapi-generator.codegen.input-base-dir=openapi-definitionsTo fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-model-type-annotations=@org.test.Foo;@org.test.BarIf you want to change the base package in which the classes are generated, use the quarkus.openapi-generator.codegen.spec.<filename>.base-package property.
+If a base package is not provided, it will default to org.openapi.quarkus.<filename>. For example, org.openapi.quarkus.petstore_json.
quarkus.openapi-generator.codegen.spec.petstore_json.base-package=org.acmeConfiguring additional-model-type-annotations will add all annotations to the generated model files (extra details can be found in OpenApi Generator Doc).
You can customize the name of generated classes. To do that, you must define the following properties:
+quarkus.openapi-generator.codegen.spec.petstore_json.api-name-suffix=CustomApiSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-suffix=CustomModelSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-prefix=CustomModelPrefixThe same way you can add any additional annotations to the generated api files with additional-api-type-annotations. Given you want to include Foo and Bar annotations, you must define additional-api-type-annotations as:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-api-type-annotations=@org.test.Foo;@org.test.Bar| + + | +
+Note that the file name`petstore_json`is used to configure the specific information for each spec. We follow the Environment Variables Mapping Rules from Microprofile Configuration to sanitize the OpenAPI spec filename. Any non-alphabetic characters are replaced by an underscore _.
+ |
+
Run mvn compile to generate your classes in target/generated-sources/open-api-json path:
- org.acme.openapi
+ - api
+ - PetApi.java
+ - StoreApi.java
+ - UserApi.java
+ - model
+ - Address.java
+ - Category.java
+ - Customer.java
+ - ModelApiResponse.java
+ - Order.java
+ - Pet.java
+ - Tag.java
+ - User.javaYou can reference the generated code in your project, for example:
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.acme.openapi.api.PetApi;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.jboss.resteasy.annotations.jaxrs.PathParam;
+
+@Produces(MediaType.APPLICATION_JSON)
+@Path("/petstore")
+public class PetResource {
+
+ @RestClient
+ @Inject
+ PetApi petApi;
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+Since the most part of this extension work is in the generate-code execution phase of the Quarkus Maven’s plugin, the log configuration must be set in the Maven context. When building your project, add -Dorg.slf4j.simpleLogger.log.org.openapitools=off to the mvn command to reduce the internal generator noise. For example:
mvn clean install -Dorg.slf4j.simpleLogger.log.org.openapitools=offFor more information, see the Maven Logging Configuration and Maven Configuration guides.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Enables the authentication token propagation for this particular securityScheme. +
+
+For example, given a file named petstore.json with a securityScheme named "petstore-auth" the following configuration must be used. +
+
+quarkus.openapi-generator.petstore_json.auth.petstore_auth.token-propagation=true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configures a particular http header attribute from were to take the security token from when the token propagation is enabled. Use this fine-grained configuration in very particular scenarios. +
+
+For example, given a file named petstore.json with a securityScheme named "petstore-auth" the following configuration must be used. +
+
+quarkus.openapi-generator.petstore_json.auth.petstore_auth.header-name=MyParticularHttpHeaderName +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Configures a particular parameter value to be used by any of the different internal authentication filters that processes the different securityScheme definitions. +
+
+For example, given a file named petstore.json with a securityScheme named "petstore-basic-auth", that is of http basic authentication type, the following configuration can establish the user and password to be used. must be used. +
+
+quarkus.openapi-generator.petstore_json.auth.petstore_basic_auth.username=MyUserName quarkus.openapi-generator.petstore_json.auth.petstore_basic_auth.password=MyPassword +
+
+Environment variable: |
+
|
++ |
You can use the quarkus-openapi-generator with REST Client Classic or REST Client Reactive respectively. To do so add either the classic or reactive jackson dependency to your project’s pom.xml file:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-rest-client-jackson</artifactId>
+</dependency>| + + | ++After Version 1.2.1 / 2.1.1 you need to declare the above dependency explicitly! Even if you stay with the REST Client Classic implementation! + | +
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-rest-client-reactive-jackson</artifactId>
+</dependency>To make truly non-blocking calls, you need to also set the mutiny option to true. This
+will wrap all API return types in a io.smallrye.mutiny.Uni.
quarkus.openapi-generator.codegen.spec.my_openapi_yaml.mutiny=trueWhen using RESTEasy Reactive:
+The client must not declare multiple MIME-TYPES with @Consumes
You might need to implement a ParamConverter for each complex type
By default, this extension generates the methods according to their returning models based on the OpenAPI specification Schema Object. If no response model is defined, jakarta.ws.rs.core.Response is returned.
If you want to return jakarta.ws.rs.core.Response in all cases instead, you can set the return-response property to true.
The rest client also supports request with mime-type multipart/form-data and, if the schema of the request body is known in advance, we can also automatically generate the models of the request +bodies.
+| + + | ++RESTEasy Reactive supports multipart/form-data out of the box. Thus, no additional dependency is required. + | +
If you’re using RESTEasy Classic, you need to add the following additional dependency to your pom.xml:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy-multipart</artifactId>
+</dependency>For any multipart/form-data operation a model for the request body will be generated. Each part of the multipart is a field in this model that is annotated with the following annotations:
+jakarta.ws.rs.FormParam, where the value parameter denotes the part name,
PartType, where the parameter is the jax-rs MediaType of the part (see below for details),
and, if the part contains a file, PartFilename, with a generated default parameter that will be passed as the fileName sub-header in the
+Content-Disposition header of the part.
For example, the model for a request that requires a file, a string and some complex object will look like this:
+public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("fileFile")
+ public File file;
+
+ @FormParam("fileName")
+ @PartType(MediaType.TEXT_PLAIN)
+ public String fileName;
+
+ @FormParam("someObject")
+ @PartType(MediaType.APPLICATION_JSON)
+ public MyComplexObject someObject;
+}Then in the client, when using RESTEasy Classic, the org.jboss.resteasy.annotations.providers.multipart.MultipartForm annotation is added in front of the multipart parameter:
@Path("/echo")
+@RegisterRestClient(baseUri="http://my.endpoint.com/api/v1", configKey="multipart-requests_yml")
+public interface MultipartService {
+
+ @POST
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ @Produces(MediaType.TEXT_PLAIN)
+ String sendMultipartData(@MultipartForm MultipartBody data);
+
+}When using RESTEasy Reactive, the jakarta.ws.rs.BeanParam annotation is added in front of the multipart parameter:
@Path("/echo")
+@RegisterRestClient(baseUri="http://my.endpoint.com/api/v1", configKey="multipart-requests_yml")
+public interface MultipartService {
+
+ @POST
+ @Consumes(MediaType.MULTIPART_FORM_DATA)
+ @Produces(MediaType.TEXT_PLAIN)
+ String sendMultipartData(@jakarta.ws.rs.BeanParam MultipartBody data);
+
+}See Quarkus - Using the REST Client with Multipart and +the RESTEasy JAX-RS specifications for more details.
+| + + | +
+MultipartForm is deprecated when using RESTEasy Reactive.
+ |
+
baseURI value of RegisterRestClient annotation is extracted from the servers section of the file, if present. If not, it will be left empty and it is expected you set up the uri to be used in your configuration.
Importantly, if some multipart request bodies contain complex objects (i.e. non-primitives) you need to explicitly tell the Open API generator to create models for these objects by setting
+the skip-form-model property corresponding to your spec in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.skip-form-model=falseSee the module multipart-request for an example of how to use this feature.
+In case the default PartFilename annotation is not required, its generation can be disabled by setting the generate-part-filename property (globally or corresponding to your spec) in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.generate-part-filename=falseBy default, the PartFilename value representing the filename is prefixed by the field name. This can be changed by setting the use-field-name-in-part-filename property (globally or corresponding to your spec) in the application.properties to false, e.g.:
quarkus.openapi-generator.codegen.spec.my_multipart_requests_yml.use-field-name-in-part-filename=falseAnd in case the default PartFilename value is not suitable (e.g. a conversion service only allows/supports specific extensions), the value can be set by using the part-filename-value property (globally or corresponding to your spec) in the application.properties, e.g.:
quarkus.openapi-generator.codegen.spec.my_first_multipart_requests_yml.part-filename-value=".pdf"So for instance, by setting part-filename-value to some.pdf and use-field-name-in-part-filename to false the generated code will look like this:
public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("some.pdf")
+ public File file;
+}And by setting only part-filename-value to .pdf, the generated code will look like this:
public class MultipartBody {
+
+ @FormParam("file")
+ @PartType(MediaType.APPLICATION_OCTET_STREAM)
+ @PartFilename("file.pdf")
+ public File file;
+}See the module part-filename for examples of how to use these features.
+The OAS 3.0 specifies the following default content-types for a multipart:
+If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain
If the property is complex, or an array of complex values, the default Content-Type is application/json
If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream
A different content-type may be defined in your api spec, but this is not yet supported in the code generation. Also, this "annotation-oriented" approach of RestEasy (i.e. using @MultipartForm to
+denote the multipart body parameter) does not seem to properly support the unmarshalling of arrays of the same type (e.g. array of files), in these cases it uses Content-Type equal
+to application/json.
Add the following dependency to your project’s pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.openapi.generator</groupId>
+ <artifactId>quarkus-openapi-generator-server</artifactId>
+ <version>3.0.0-SNAPSHOT</version>
+</dependency>You will also need to add or update the quarkus-maven-plugin configuration with the following:
| + + | +
+You probably already have this configuration if you created your application with Code Quarkus. That said, double-check your configuration not to add another plugin entry.
+ |
+
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ <goal>generate-code-tests</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Now, create the directory openapi under your src/main/resources path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.
To fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
If a base package name is not provided, it will be used the default io.apicurio.api.
You can customize the specification used for code generation with the following property:
+quarkus.openapi.generator.spec=petstore-openapi.jsonquarkus.openapi.generator.base-package=io.petstoreRun mvn compile to generate your classes in target/generated-sources/jaxrs path:
- io.petstore
+ - beans
+ - Address.java
+ - ApiResponse.java
+ - Category.java
+ - Customer.java
+ - Order.java
+ - Pet.java
+ - Tag.java
+ - User.java
+ - PetResource.java
+ - StoreResource.java
+ - UserResource.javaYou can reference the generated code in your project, for example:
+package io.petstore;
+
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import io.petstore.beans.ApiResponse;
+import io.petstore.beans.Pet;
+
+public class PetStoreImpl implements PetResource {
+
+ private static final Map<Long, Pet> PETS = new HashMap<>();
+
+ @Override
+ public Pet updatePet(Pet data) {
+ return PETS.put(data.getId(), data);
+ }
+
+ @Override
+ public Pet addPet(Pet data) {
+ return PETS.put(data.getId(), data);
+ }
+
+ @Override
+ public List<Pet> findPetsByStatus(String status) {
+ return null;
+ }
+
+ @Override
+ public List<Pet> findPetsByTags(List<String> tags) {
+ return null;
+ }
+
+ @Override
+ public Pet getPetById(long petId) {
+ return PETS.get(petId);
+ }
+
+ @Override
+ public void updatePetWithForm(long petId, String name, String status) {
+
+ }
+
+ @Override
+ public void deletePet(String apiKey, long petId) {
+ PETS.remove(petId);
+ }
+
+ @Override
+ public ApiResponse uploadFile(long petId, String additionalMetadata, InputStream data) {
+ return null;
+ }
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+You have the option to swap out the templates used by this extension with your customized versions. To achieve this, place your custom templates under the resources/templates directory. It’s crucial that the filename of each custom template matches that of the original template.
You can find an example of using customized templates in integration-tests/custom-templates.
+| + + | ++While the option to replace templates exists, it’s essential to exercise caution and consider this as a final resort. Prior to altering templates, exhaust all possibilities of achieving your goals through configuration settings. Modifying templates could have broader implications for the extension’s functionality and may introduce complexities. Only resort to template replacement when configuration adjustments prove insufficient for your requirements. + | +
Furthermore, be aware that customizing templates increases the risk of compatibility issues during future upgrades. Therefore, exercise discretion and weigh the benefits against the potential risks before opting for template customization.
+Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.
+This a multipurpose Quarkus' extension for generation of Rest Clients and Server stubs based on OpenAPI specification files.
+Currently, we support two types of code generation:
+Quarkus - OpenAPI Generator - Client: Refer to our documentation on how to generate these clients.
+Quarkus - OpenAPI Generator - Server: Follow our guidelines to generate server stubs using Apicurio.
+| + + | ++Check versions 1.x.x if you’re still using Quarkus 2. But be aware that we no longer support Quarkus 2. That means there are no updates planned for those versions. + | +
This extension is based on the OpenAPI Generator Tool. Please consider donation to help them maintain the +project: https://opencollective.com/openapi_generator/donate
+Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.
+Quarkus' extension for generation of server Stubs based on OpenAPI specification files.
+This extension is based on the Apicurio Codegen tool.
+This extension is for REST code generation for server side only.
+Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples… But first, read this page.
+Add the following dependency to your project’s pom.xml file:
| + + | ++Version 2.x.x of this extension supports Quarkus 3, and version 1.x.x supports Quarkus 2. We strongly recommend you to use version 2.x.x. No updates are planned for version 1.x.x. + | +
<dependency>
+ <groupId>io.quarkiverse.openapi.generator</groupId>
+ <artifactId>quarkus-openapi-generator</artifactId>
+ <version>3.0.0-SNAPSHOT</version>
+</dependency>You will also need to add or update the quarkus-maven-plugin configuration with the following:
| + + | +
+You probably already have this configuration if you created your application with Code Quarkus. That said, double-check your configuration not to add another plugin entry.
+ |
+
<plugin>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-maven-plugin</artifactId>
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>build</goal>
+ <goal>generate-code</goal>
+ <goal>generate-code-tests</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>Now, create the directory openapi under your src/main/ path and add the OpenAPI spec files there. We support JSON, YAML and YML extensions.
If you want to change the directory where OpenAPI files must be found, use the property quarkus.openapi-generator.codegen.input-base-dir.
+IMPORTANT: it is relative to the project base directory. For example, if you have a project called MyJavaProject and decide to place them in MyJavaProject/openapi-definitions, use the following property:
quarkus.openapi-generator.codegen.input-base-dir=openapi-definitionsTo fine tune the configuration for each spec file, add the following entry to your properties file. In this example, our spec file is in src/main/openapi/petstore.json:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-model-type-annotations=@org.test.Foo;@org.test.BarIf you want to change the base package in which the classes are generated, use the quarkus.openapi-generator.codegen.spec.<filename>.base-package property.
+If a base package is not provided, it will default to org.openapi.quarkus.<filename>. For example, org.openapi.quarkus.petstore_json.
quarkus.openapi-generator.codegen.spec.petstore_json.base-package=org.acmeConfiguring additional-model-type-annotations will add all annotations to the generated model files (extra details can be found in OpenApi Generator Doc).
You can customize the name of generated classes. To do that, you must define the following properties:
+quarkus.openapi-generator.codegen.spec.petstore_json.api-name-suffix=CustomApiSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-suffix=CustomModelSuffixquarkus.openapi-generator.codegen.spec.petstore_json.model-name-prefix=CustomModelPrefixThe same way you can add any additional annotations to the generated api files with additional-api-type-annotations. Given you want to include Foo and Bar annotations, you must define additional-api-type-annotations as:
quarkus.openapi-generator.codegen.spec.petstore_json.additional-api-type-annotations=@org.test.Foo;@org.test.Bar| + + | +
+Note that the file name`petstore_json`is used to configure the specific information for each spec. We follow the Environment Variables Mapping Rules from Microprofile Configuration to sanitize the OpenAPI spec filename. Any non-alphabetic characters are replaced by an underscore _.
+ |
+
Run mvn compile to generate your classes in target/generated-sources/open-api-json path:
- org.acme.openapi
+ - api
+ - PetApi.java
+ - StoreApi.java
+ - UserApi.java
+ - model
+ - Address.java
+ - Category.java
+ - Customer.java
+ - ModelApiResponse.java
+ - Order.java
+ - Pet.java
+ - Tag.java
+ - User.javaYou can reference the generated code in your project, for example:
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import org.acme.openapi.api.PetApi;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+import org.jboss.resteasy.annotations.jaxrs.PathParam;
+
+@Produces(MediaType.APPLICATION_JSON)
+@Path("/petstore")
+public class PetResource {
+
+ @RestClient
+ @Inject
+ PetApi petApi;
+}See the integration-tests module for more information of how to use this extension. Please be advised that the extension is on experimental, early development stage.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether tracing spans of client commands are reported. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in 'dev' or 'test' mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the OpenFGA instance managed by Quarkus DevServices is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, DevServices for OpenFGA starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in 'dev' mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared OpenFGA instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the HTTP service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Optional fixed port the gRPC service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Optional fixed port the Playground service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Name of authorization store to create for DevServices. +
+
+Defaults to "dev". +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+JSON formatted authorization model to upload during DevServices initialization. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of JSON formatted authorization model file to upload during DevServices initialization. +
+
+The location can be prefixed with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+JSON formatted authorization tuples to upload during DevServices initialization. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of JSON formatted authorization tuples file to upload during DevServices initialization. +
+
+The location can be prefixed with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenFGA server URL. +
+
+Example: http://openfga:8080 +
+
+Environment variable: |
++ | required |
+
+
+
+
+
+
+Shared authentication key. +
+
+If none provided unauthenticated access will be attempted. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Store id or name for default
+
+If the provided property does not match the OpenFGA store id format (
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Always Treat
+
+If true, the store id will always be resolved at runtime regardless of the format of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Authorization model id for default
+
+If none is provided the default bean will target the default authorization model for the store. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout to establish a connection with OpenFGA. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Request timeout on OpenFGA. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of remote hosts that are not proxied when the client is configured to use a proxy. This list serves the same purpose as the JVM
+
+Entries can use the * wildcard character for pattern matching, e.g *.example.com matches www.example.com. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Allows to bypass certificate validation on TLS communications. +
+
+If true this will allow TLS communications with OpenFGA, without checking the validity of the certificate presented by OpenFGA. This is discouraged in production because it allows man in the middle type of attacks. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Certificate bundle used to validate TLS communications with OpenFGA. +
+
+The path to a pem bundle file, if TLS is required, and trusted certificates are not set through javax.net.ssl.trustStore system property. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
The Quarkus OpenFGA Client extension provides a reactive client for accessing OpenFGA +instances. Additionally, it is the client that powers the +Quarkus Zanzibar - OpenFGA Connector to provide +Find Grained Authorization for Quarkus applications.
+If you want to use this extension, you need to add the io.quarkiverse.openfga:quarkus-openfga-client extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.openfga</groupId>
+ <artifactId>quarkus-openfga-client</artifactId>
+ <version>1.2.0</version>
+</dependency>Or with Gradle, add the dependency to your build.gradle:
implementation("io.quarkiverse.openfga:quarkus-openfga-client:1.2.0")The extension requires two configuration properties to be defined at startup to define what instance and store are
+targeted by the client. The url property selects the scheme, host and, optionally, the port of the OpenFGA instance.
+While store determines which authorization store is targeted; it can be referenced by store id or name.
quarkus.openfga.url=http://localhost:80
+quarkus.openfga.store=my-app-authz
+# Optional authorization model id
+#quarkus.openfga.authorization-model-id=11G22H33I44J55K66L77M88N99The extension supports Quarkus’s DevServices and will start and configure a local OpenFGA in dev and test if no
+url configuration property is provided. Additionally it will automatically create and configure an authorization
+store in the server.
In addition to starting and creating an authorization store, an authorization model can be initialized in the store
+by configuring the quarkus.openfga.devservices.authorization-model or
+quarkus.openfga.devservices.authorization-model.lcation property.
Adding the quarkus-openfga-client extension to your project defines clients beans OpenFGAClient that are configured to access the OpenFGA instance configured in application.properties.
The extension provides three injectable clients for accessing the configured instance and store.
+OpenFGAClientMain client for accessing the OpenFGA instance.
+StoreClientAccess authorization store configured via quarkus.openfga.store-id
AuthorizationModelsClientManage (list, create, delete) authorization models and create AuthorizationModelClient instances for accessing a specific model.
AuthorizationModelClientAccess authorization model configured via quarkus.openfga.authoriztion-model-id or the default model if none is configured.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether tracing spans of client commands are reported. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in 'dev' or 'test' mode. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the OpenFGA instance managed by Quarkus DevServices is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, DevServices for OpenFGA starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in 'dev' mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared OpenFGA instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the HTTP service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Optional fixed port the gRPC service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Optional fixed port the Playground service will be bound to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Name of authorization store to create for DevServices. +
+
+Defaults to "dev". +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+JSON formatted authorization model to upload during DevServices initialization. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of JSON formatted authorization model file to upload during DevServices initialization. +
+
+The location can be prefixed with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+JSON formatted authorization tuples to upload during DevServices initialization. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of JSON formatted authorization tuples file to upload during DevServices initialization. +
+
+The location can be prefixed with
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OpenFGA server URL. +
+
+Example: http://openfga:8080 +
+
+Environment variable: |
++ | required |
+
+
+
+
+
+
+Shared authentication key. +
+
+If none provided unauthenticated access will be attempted. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Store id or name for default
+
+If the provided property does not match the OpenFGA store id format (
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Always Treat
+
+If true, the store id will always be resolved at runtime regardless of the format of the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Authorization model id for default
+
+If none is provided the default bean will target the default authorization model for the store. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Timeout to establish a connection with OpenFGA. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Request timeout on OpenFGA. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of remote hosts that are not proxied when the client is configured to use a proxy. This list serves the same purpose as the JVM
+
+Entries can use the * wildcard character for pattern matching, e.g *.example.com matches www.example.com. +
+
+Environment variable: |
+list of string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Allows to bypass certificate validation on TLS communications. +
+
+If true this will allow TLS communications with OpenFGA, without checking the validity of the certificate presented by OpenFGA. This is discouraged in production because it allows man in the middle type of attacks. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Certificate bundle used to validate TLS communications with OpenFGA. +
+
+The path to a pem bundle file, if TLS is required, and trusted certificates are not set through javax.net.ssl.trustStore system property. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The list of hosts of the OpenSearch servers, when accessing AWS OpenSearch set to AWS endpoint name. Host Example: opensearch-01:9200,opensearch-02:9200 AWS Endpoint Example: search-domain-name-identifier.region.es.amazonaws.com +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The protocol to use when contacting OpenSearch servers. Set to "https" to enable SSL/TLS. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The username for basic HTTP authentication. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for basic HTTP authentication. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The connection timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The connection timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The socket timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of connections to all the OpenSearch servers. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of connections per OpenSearch server. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The number of IO thread. By default, this is the number of locally detected processors. +
+
+Thread counts higher than the number of processors should not be necessary because the I/O threads rely on non-blocking operations, but you may want to use a thread count lower than the number of processors. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+AWS Region +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Set to "es" or "aoss" to use AWS OpenSearch Service. es : Amazon OpenSearch Service aoss : Amazon OpenSearch Serverless +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret Access Key for setting up StaticCredentialsProvider +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret Access Key Secret for setting up StaticCredentialsProvider +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Defines if automatic discovery is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Refresh interval of the node list. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
The quarkus-opensearch extension allows you to connect to an OpenSearch cluster using the clients provided by the OpenSearch project.
+OpenSearch provides three different flavours of clients for connecting to the cluster. This extension has support for all three of them.
+This is the latest implementation of the OpenSearch clients, when starting a new project you should use this client and not bother about the others.
+This will be the only OpenSearch Client supported in the future.
+Just like the OpenSearch REST high-level level, the OpenSearch Java client lets you interact with OpenSearch through Java methods and data structures. In comparison to the REST high-level, it has no dependency to org.opensearch:opensearch and also provides an async client implementation.
| + + | +
+ Deprecation
+
+
+The OpenSearch REST clients are deprecated. Support will be removed in OpenSearch version 3.0.0. +
+
+It is recommended to switch to the Java client. +We will try to support the REST clients as long as possible, but if you start a new project this is not the client you should use anymore. + |
+
The OpenSearch Java high-level REST client lets you interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
+The java client does not have any dependencies on the REST client. All clients are sharing most of the configuration properties.
+The AWS related configuration properties quarkus.opensearch.aws.* are only applicable to this java client.
If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-java-client extension first to your build file.
with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.opensearch</groupId>
+ <artifactId>quarkus-opensearch-java-client</artifactId>
+ <version>1.5.0</version>
+</dependency>The REST High-Level Client depends on the REST client and does not require any additional configuration.
+If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-rest-high-level-client extension first to your build file.
with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.opensearch</groupId>
+ <artifactId>quarkus-opensearch-rest-high-level-client</artifactId>
+ <version>1.5.0</version>
+</dependency>If you want to use this extension, you need to add the io.quarkiverse.opensearch:quarkus-opensearch-rest-client extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.opensearch</groupId>
+ <artifactId>quarkus-opensearch-rest-client</artifactId>
+ <version>1.5.0</version>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The list of hosts of the OpenSearch servers, when accessing AWS OpenSearch set to AWS endpoint name. Host Example: opensearch-01:9200,opensearch-02:9200 AWS Endpoint Example: search-domain-name-identifier.region.es.amazonaws.com +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The protocol to use when contacting OpenSearch servers. Set to "https" to enable SSL/TLS. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The username for basic HTTP authentication. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The password for basic HTTP authentication. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The connection timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The connection timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The socket timeout. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+The maximum number of connections to all the OpenSearch servers. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The maximum number of connections per OpenSearch server. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The number of IO thread. By default, this is the number of locally detected processors. +
+
+Thread counts higher than the number of processors should not be necessary because the I/O threads rely on non-blocking operations, but you may want to use a thread count lower than the number of processors. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+AWS Region +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Set to "es" or "aoss" to use AWS OpenSearch Service. es : Amazon OpenSearch Service aoss : Amazon OpenSearch Serverless +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret Access Key for setting up StaticCredentialsProvider +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+AWS Secret Access Key Secret for setting up StaticCredentialsProvider +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Defines if automatic discovery is enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Refresh interval of the node list. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the operator should check that the CRD is properly deployed and that the associated
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the extension should automatically generate the CRD based on
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether the extension should automatically apply updated CRDs when they change. When running on DEV mode, the CRD changes will always be applied automatically. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Comma-separated list of which CRD versions should be generated. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The directory where the CRDs will be generated, defaults to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the extension should generate all CRDs even if some are not tied to a Reconciler. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the CRDs should be generated in parallel. Please note that this feature is experimental and it may lead to unexpected results. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma-separated list of fully-qualified class names implementing custom resources to exclude from the CRD generation process. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether controllers should only process events if the associated resource generation has increased since last reconciliation, otherwise will process all events. Sets the default value for all controllers. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether Role-Based Access Control (RBAC) resources generated by the Kubernetes extension should be augmented by this extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the operator should be automatically started or not. Mostly useful for testing scenarios. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the injected Kubernetes client should be stopped when the operator is stopped. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the operator should stop if an informer error (such as one caused by missing / improper RBACs) occurs during startup. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to fail or emit a debug-level (warning-level when misalignment is at the minor or above version level) log when the extension detects that there are misaligned versions. +
+
+The following versions are checked for alignment: +
+
+
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The list of profile names for which leader election should be activated. This is mostly useful for testing scenarios where leader election behavior might lead to issues. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The optional Server-Side Apply (SSA) related configuration. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional list of comma-separated watched namespace names that will be used to generate manifests at build time if controllers do NOT specify a value individually. See
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Can be used to disable helm chart generation. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The max number of concurrent dispatches of reconciliation requests to controllers. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Amount of seconds the SDK waits for reconciliation threads to terminate before shutting down. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+An optional list of comma-separated namespace names all controllers will watch if they do not specify their own list. If a controller specifies its own list either via the
+
+If this property is left empty then controllers will watch all namespaces by default (which is equivalent to setting this property to
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The max number of concurrent workflow processing requests. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+How long the operator will wait for informers to finish synchronizing their caches on startup before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the controller should only process events if the associated resource generation has increased since last reconciliation, otherwise will process all events. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+An optional list of comma-separated watched namespace names that will be used to generate manifests at build time. +
+
+Note that this is provided as a means to quickly deploy a specific controller to test it by applying the generated manifests to the target cluster. If empty, no manifests will be generated. The namespace in which the controller will be deployed will be the currently configured namespace as specified by your
+
+As this functionality cannot handle namespaces that are not know until runtime (because the generation happens during build time), we recommend that you use a different mechanism such as OLM or Helm charts to deploy your operator in production. +
+
+This replaces the previous
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Indicates whether the primary resource for the associated controller is unowned, meaning that another controller is the principal controller handling resources of this type. By default, controllers are assumed to own their primary resource but there are cases where this might not be the case, for example, when extra processing of a given resource type is required even though another controller already handles reconciliations of resources of that type. Set this property to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional list of comma-separated namespace names the controller should watch. If this property is left empty then the controller will watch all namespaces. The value can be set to "JOSDK_WATCH_CURRENT" to watch the current (default) namespace from kube config. Constant(s) can be found in at `io.javaoperatorsdk.operator.api.reconciler.Constants`". +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The optional name of the finalizer for the controller. If none is provided, one will be automatically generated. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How many times an operation should be retried before giving up +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The initial interval that the controller waits for before attempting the first retry +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The value by which the initial interval is multiplied by for each retry +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum interval that the controller will wait for before attempting a retry, regardless of all other configuration +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+An optional list of comma-separated label selectors that Custom Resources must match to trigger the controller. See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on selectors. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
This extension integrates the Java Operator SDK project (JOSDK) with Quarkus, making it even easier to use both.
+For an introduction to this project, please read the blog series that we wrote on how to write operators in Java with Quarkus. +Please also refer to the JOSDK documentation for more details.
+Automatically generates a main class, so that the only thing that’s required is to write Reconciler implementation(s)
Automatically makes a Kubernetes/OpenShift client available for CDI injection
+Automatically sets up an Operator instance, also available for CDI injection
Automatically processes the reconcilers' configuration at build time, exposing all the available configuration of JOSDK via application properties
+Automatically registers reconcilers with the Operator and start them
Automatically generates CRDs for all CustomResource implementations used by reconcilers
Automatically generates Kubernetes descriptors
+Automatically generates the bundle manifests for all reconcilers (using the quarkus-operator-sdk-bundle-generator extension)
Integrates with the Dev mode:
+Watches your code for changes and reload automatically your operator if needed without having to hit an endpoint
+Only re-generates the CRDs if a change impacting its generation is detected
+Only re-processes a reconciler’s configuration if needed
+Automatically apply the CRD to the cluster when it has changed
+Supports micrometer registry extensions (adding a Quarkus-supported micrometer registry extension will automatically inject said registry into the operator)
+Automatically adds a SmallRye health check
+Sets up reflection for native binary generation
+[Deprecated] Customize the JSON serialization that the Fabric8 client relies on by providing an ObjectMapperCustomizer implementation, qualified with the @KubernetesClientSerializationCustomizer annotation
The Quarkus kubernetes client extension now provides an official mechanism to do so by implementing the io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer interface instead so this mechanism should be used moving forward.
Dev mode commands:
+Dev commands are automatically accessible from the Dev console after typing : in the Quarkus terminal in Dev mode, under the qosdk name. Two commands currently exist: qosdk api to create a Kubernetes API (hint: type qosdk api -h for more details) and qosdk versions to show which versions are targeted by QOSDK.
CLI command:
+Add the Quarkus CLI command using: quarkus plug add io.quarkiverse.operatorsdk:quarkus-operator-sdk-cli:runner:jar:6.6.3
You can create a Kubernetes API using the quarkus operator-sdk api command, e.g. quarkus operator-sdk api -g halkyon.io -v v1 -k foo
If you want to use this extension, you need to add the quarkus-operator-sdk extension first.
You need to add minimally, the following to your pom.xml file:
<dependency>
+ <groupId>io.quarkiverse.operatorsdk</groupId>
+ <artifactId>quarkus-operator-sdk</artifactId>
+ <version>6.6.3</version>
+</dependency>However, it might be more convenient to use the quarkus-operator-sdk-bom dependency to ensure that all dependency versions are properly aligned:
<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkiverse.operatorsdk</groupId>
+ <artifactId>quarkus-operator-sdk-bom</artifactId>
+ <version>6.6.3</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+
+ <!-- other dependencies as needed by your project -->
+
+ </dependencies>
+ </dependencyManagement>If you do use the BOM, please do make sure to use the same Quarkus version as the one defined in the BOM when configuring the Quarkus plugin as the Quarkus Dev Mode will not work properly otherwise, failing with an error:
+Exception in thread "main" java.lang.RuntimeException: java.lang.RuntimeException: java.lang.IllegalStateException: Hot deployment of the application is not supported when updating the Quarkus version. The application needs to be stopped and dev mode started up again
+ at io.quarkus.deployment.dev.DevModeMain.start(DevModeMain.java:138)
+ at io.quarkus.deployment.dev.DevModeMain.main(DevModeMain.java:62)If you want to use the Bundle generator, you will first need to use Quarkus 2.3.0.Final or above and add the quarkus-operator-sdk-bundle-generator extension first:
<dependency>
+ <groupId>io.quarkiverse.operatorsdk</groupId>
+ <artifactId>quarkus-operator-sdk-bundle-generator</artifactId>
+ <version>6.6.3</version>
+</dependency>This section explains how to deploy your operator using the Operator Lifecycle Manager (OLM) by following the next steps:
+Make sure you have installed the opm command tool and are connected to a Kubernetes cluster on which OLM is installed.
+Quarkus provides several extensions to build the container image.
+For example, the Joke sample uses the Quarkus Jib container image extension to build the image.
+So, you first need to configure one of these extensions as you prefer.
+Then, you need to add the quarkus-operator-sdk-bundle-generator extension:
<dependency>
+ <groupId>io.quarkiverse.operatorsdk</groupId>
+ <artifactId>quarkus-operator-sdk-bundle-generator</artifactId>
+ <version>6.6.3</version>
+</dependency>This extension generates the Operator bundle manifests in the target/bundle directory.
Finally, to generate the operator image and the bundle manifests at once, you simply need to run the next Maven command:
+mvn clean package -Dquarkus.container-image.build=true \
+ -Dquarkus.container-image.push=true \
+ -Dquarkus.container-image.registry=<your container registry. Example: quay.io> \
+ -Dquarkus.container-image.group=<your container registry namespace> \
+ -Dquarkus.kubernetes.namespace=<the kubernetes namespace where you will deploy the operator> \
+ -Dquarkus.operator-sdk.bundle.package-name=<the name of the package that bundle image belongs to> \
+ -Dquarkus.operator-sdk.bundle.channels=<the list of channels that bundle image belongs to>For example, if we want to name the package my-operator and use the alpha channels, we would need to append the properties -Dquarkus.operator-sdk.bundle.package-name=my-operator -Dquarkus.operator-sdk.bundle.channels=alpha.
| + + | +
+
+
+Find more information about channels and packages here. + |
+
| + + | +
+
+
+If you’re using an insecure container registry, you’ll also need to append the next property to the Maven command |
+
| + + | +
+
+
+By default, the bundle generator disables outputting the application’s version as part of the manifests' selectors (equivalent to setting |
+
An Operator Bundle is a container image that stores Kubernetes manifests and metadata associated with an operator.
+You can find more information about this here.
+In the previous step, we generated the bundle manifests at target/bundle which includes a ready-to-use target/bundle/bundle.Dockerfile Dockerfile that you will use to build and push the final Operator Bundle image to your container registry:
MY_BUNDLE_IMAGE=<your container registry>/<your container registry namespace>/<bundle image name>:<tag>
+docker build -t $MY_BUNDLE_IMAGE -f target/bundle/bundle.Dockerfile target/bundle
+docker push $MY_BUNDLE_IMAGEFor example, if we want to name our bundle image as my-manifest-bundle, our container registry is quay.io, our Quay user is myuser and the tag we’re releasing is 1.0, the final MY_BUNDLE_IMAGE property would be quay.io/myuser/my-manifest-bundle:1.0.
OLM uses catalogs to discover and install Operators and their dependencies. +So, a catalog is similar to a repository of operators and their associated versions that can be installed on a cluster. +Moreover, the catalog is also a container image that contains a collection of bundles and channels. +Therefore, we’d need to create a new catalog (or update an existing one if you’re already have one), build/push the catalog image and then install it on our cluster.
+So far, we have already built the Operator bundle image at $MY_BUNDLE_IMAGE (see above) and next, we need to add this Operator bundle image into our catalog.
+For doing this, we’ll use the olm tool as follows:
CATALOG_IMAGE=<catalog container registry>/<catalog container registry namespace>/<catalog name>:<tag>
+opm index add \
+ --bundles $MY_BUNDLE_IMAGE \
+ --tag $CATALOG_IMAGE \
+ --build-tool docker
+docker push $CATALOG_IMAGEFor example, if our catalog name is my-catalog, our container registry for the catalog is quay.io, our Quay user is myuser and the container tag we’re releasing is 59.0, the final CATALOG_IMAGE property would be quay.io/myuser/my-catalog:59.0.
| + + | +
+
+
+If you’re using an insecure registry, you’d need to append the argument |
+
Once we have our catalog image built and pushed at $CATALOG_IMAGE, we need to install it in the same namespace where OLM is running (by default, OLM is running in the operators namespace, we will use the OLM_NAMESPACE property to represent this namespace) on our cluster using the CatalogSource resource by doing the next command:
cat <<EOF | kubectl apply -f -
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+ name: my-catalog-source
+ namespace: $OLM_NAMESPACE
+spec:
+ sourceType: grpc
+ image: $CATALOG_IMAGE
+EOFOnce the catalog is installed, you should see the catalog pod up and running:
+kubectl get pods -n $OLM_NAMESPACE --selector=olm.catalogSource=my-catalog-sourceOLM deploys operators via subscriptions.
+Creating a Subscription will trigger the operator deployment.
+You can simply create the Subscription resource that contains the operator name and channel to install by running the following command:
cat <<EOF | kubectl create -f -
+apiVersion: operators.coreos.com/v1alpha1
+kind: Subscription
+metadata:
+ name: my-subscription
+ namespace: <Kubernetes namespace where your operator will be installed>
+spec:
+ channel: alpha
+ name: my-operator-name
+ source: my-catalog-source
+ sourceNamespace: $OLM_NAMESPACE
+EOF| + + | +
+
+
+We’ll install the operator in the target namespace defined in the metadata object.
+The |
+
Once the subscription is created, you should see your operator pod up and running:
+kubectl get csv -n $OLM_NAMESPACE my-operator-name| + + | ++Remove this section if you don’t have Quarkus configuration properties in your extension. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the operator should check that the CRD is properly deployed and that the associated
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the extension should automatically generate the CRD based on
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Whether the extension should automatically apply updated CRDs when they change. When running on DEV mode, the CRD changes will always be applied automatically. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Comma-separated list of which CRD versions should be generated. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The directory where the CRDs will be generated, defaults to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Whether the extension should generate all CRDs even if some are not tied to a Reconciler. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the CRDs should be generated in parallel. Please note that this feature is experimental and it may lead to unexpected results. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+A comma-separated list of fully-qualified class names implementing custom resources to exclude from the CRD generation process. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Whether controllers should only process events if the associated resource generation has increased since last reconciliation, otherwise will process all events. Sets the default value for all controllers. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether Role-Based Access Control (RBAC) resources generated by the Kubernetes extension should be augmented by this extension. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the operator should be automatically started or not. Mostly useful for testing scenarios. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the injected Kubernetes client should be stopped when the operator is stopped. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether the operator should stop if an informer error (such as one caused by missing / improper RBACs) occurs during startup. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to fail or emit a debug-level (warning-level when misalignment is at the minor or above version level) log when the extension detects that there are misaligned versions. +
+
+The following versions are checked for alignment: +
+
+
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The list of profile names for which leader election should be activated. This is mostly useful for testing scenarios where leader election behavior might lead to issues. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The optional Server-Side Apply (SSA) related configuration. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional list of comma-separated watched namespace names that will be used to generate manifests at build time if controllers do NOT specify a value individually. See
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Can be used to disable helm chart generation. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The max number of concurrent dispatches of reconciliation requests to controllers. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Amount of seconds the SDK waits for reconciliation threads to terminate before shutting down. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+An optional list of comma-separated namespace names all controllers will watch if they do not specify their own list. If a controller specifies its own list either via the
+
+If this property is left empty then controllers will watch all namespaces by default (which is equivalent to setting this property to
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The max number of concurrent workflow processing requests. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+How long the operator will wait for informers to finish synchronizing their caches on startup before timing out. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Whether the controller should only process events if the associated resource generation has increased since last reconciliation, otherwise will process all events. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+An optional list of comma-separated watched namespace names that will be used to generate manifests at build time. +
+
+Note that this is provided as a means to quickly deploy a specific controller to test it by applying the generated manifests to the target cluster. If empty, no manifests will be generated. The namespace in which the controller will be deployed will be the currently configured namespace as specified by your
+
+As this functionality cannot handle namespaces that are not know until runtime (because the generation happens during build time), we recommend that you use a different mechanism such as OLM or Helm charts to deploy your operator in production. +
+
+This replaces the previous
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Indicates whether the primary resource for the associated controller is unowned, meaning that another controller is the principal controller handling resources of this type. By default, controllers are assumed to own their primary resource but there are cases where this might not be the case, for example, when extra processing of a given resource type is required even though another controller already handles reconciliations of resources of that type. Set this property to
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+An optional list of comma-separated namespace names the controller should watch. If this property is left empty then the controller will watch all namespaces. The value can be set to "JOSDK_WATCH_CURRENT" to watch the current (default) namespace from kube config. Constant(s) can be found in at `io.javaoperatorsdk.operator.api.reconciler.Constants`". +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+The optional name of the finalizer for the controller. If none is provided, one will be automatically generated. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+How many times an operation should be retried before giving up +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The initial interval that the controller waits for before attempting the first retry +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+The value by which the initial interval is multiplied by for each retry +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+The maximum interval that the controller will wait for before attempting a retry, regardless of all other configuration +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+An optional list of comma-separated label selectors that Custom Resources must match to trigger the controller. See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on selectors. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
This extension ensures Pact consumer libraries works well with Quarkus applications, including with continuous testing. +It is based on version 4.3.17 of the Pact JVM JUnit 5 library.
+To use this extension, add the io.quarkiverse:quarkus-pact-consumer extension first to your build file.
+Choose a 1.x version for Quarkus 3, and a 0.x version for Quarkus 2.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkus-pact-consumer</artifactId>
+ <version>0.2.1</version>
+ <scope>provided</scope>
+</dependency>Note the provided scope, rather than test or default. This is needed for the tests to pass in continuous testing mode.
Use Pact as you normally would. +Remember that your consumer tests should be testing your application’s code, not the behaviour of the Pact-provided mock.
+For example, a simple consumer test for REST endpoints would look like this:
+(1)
+@ExtendWith(PactConsumerTestExt.class)
+@PactTestFor(providerName = "farm", port = "8085")
+@PactDirectory("target/pacts")
+@QuarkusTest (2)
+public class ConsumerTest {
+
+ (3)
+ @Inject
+ Knitter knitter;
+
+ @Pact(provider = "farm", consumer = "knitter")
+ public V4Pact createPact(PactDslWithProvider builder) {
+ Map<String, String> headers = new HashMap<>();
+ headers.put("Content-Type", "application/json");
+
+ return builder.given("test GET") (4)
+ .uponReceiving("GET REQUEST")
+ .path("/alpaca")
+ .method("GET")
+ .willRespondWith()
+ .status(200)
+ .headers(headers)
+ .body(" {\n" + (5)
+ " \"colour\": \"black\",\n" +
+ " \"name\": \"floppy\"\n" +
+ " }")
+ .toPact(V4Pact.class);
+ }
+
+ @Test
+ public void testConsumption() { (6)
+ String knitted = knitter.knit("irrelevant"); (7)
+ assertEquals("a nice striped sweater", knitted);
+ }
+}| 1 | +Add @Consumer annotations to the class, along with metadata about who the consumer is, and what provider is being used. |
+
| 2 | +Needed to enable dependency injection of the rest client. | +
| 3 | +The consumer under test. | +
| 4 | +We use the Pact DSL to define what the provider should return, given the request. | +
| 5 | +Here we define our mock, which is also our expectations for the provider. +There is no need to verify these in this test; instead, the provider test will verify them. | +
| 6 | +This test is realistic (in a simplified way) of how a consumer test might look. | +
| 7 | +We have hardcoded the mock response, so the colour parameter we pass in is irrelevant (for this particular test) It tests how the consumer under test uses what the mock passes back, not the mock itself. | +
For the moment, Pact needs to be configured by the normal Pact system properties.
+If continuous testing is being used, the dependency scope cannot be test. The provided scope is a good alternative.
@TestProfile does not work in dev mode (GitHub issue)
A harmless java.lang.NoClassDefFoundError: org/apache/hc/client5/http/fluent/Request message will be produced if Pact tracking is enabled (GitHub issue)
How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+Pact is a polyglot contract testing framework. +This set of extensions ensures Pact JVM libraries works well with Quarkus applications, including with continuous testing. +They are based on version 4.3.17 of the Pact JVM JUnit 5 library.
+You can find the full set of extensions and documentation for each of them in the navigation on the left.
+This extension ensures Pact provider libraries works well with Quarkus applications, including with continuous testing. +It is based on version 4.3.17 of the Pact JVM JUnit 5 library.
+To use this extension, add the io.quarkiverse:quarkus-pact-provider extension first to your build file.
+Choose a 1.x version for Quarkus 3, and a 0.x version for Quarkus 2.
<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkus-pact-provider</artifactId>
+ <version>0.2.1</version>
+ <scope>provided</scope>
+</dependency>Note the provided scope, rather than test or default. This is needed for the tests to pass in continuous testing mode.
Use Pact as you normally would. +For example, a simple provider test for REST endpoints would look like this:
+@Provider("Farm") (1)
+@PactFolder("pacts")
+@QuarkusTest
+public class SimpleContractTest {
+
+ (2)
+ @ConfigProperty(name = "quarkus.http.test-port")
+ int quarkusPort;
+
+ @BeforeEach
+ void before(PactVerificationContext context) {
+ context.setTarget(new HttpTestTarget("localhost", quarkusPort)); (3)
+ }
+
+ @TestTemplate (4)
+ @ExtendWith(PactVerificationInvocationContextProvider.class)
+ void pactVerificationTestTemplate(PactVerificationContext context) {
+ context.verifyInteraction();
+ }
+}| 1 | +Add @Provider annotations to the class, along with instructions where to find the pacts (a folder or a broker). |
+
| 2 | +We inject Quarkus configuration. | +
| 3 | +With the injected configuration, we can tell the Pact verifier where to look for our endpoints. | +
| 4 | +Standard Pact provider boilerplate, to create a series of templated tests which run the Pact verifications. | +
For the moment, Pact needs to be configured by the normal Pact system properties.
+If continuous testing is being used, the dependency scope cannot be test. The provided scope is a good alternative.ps
@State methods do not not have access to the CDI context (GitHub issue)
When changing the code of classes with a @TestTemplate, continuous testing may not automatically retrigger (Fix PR)
@TestProfile does not work in dev mode (GitHub issue)
A harmless java.lang.NoClassDefFoundError: org/apache/hc/client5/http/fluent/Request message will be produced if Pact tracking is enabled (GitHub issue)
How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+This extension ensures Pact consumer libraries works well with Quarkus applications, including with continuous testing. +It is based on version 4.6.7 of the Pact JVM JUnit 5 library.
+To use this extension, add the io.quarkiverse:quarkus-pact-consumer extension first to your build file.
+Choose a 1.x version for Quarkus 3, and a 0.x version for Quarkus 2.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkus-pact-consumer</artifactId>
+ <version>1.3.0</version>
+ <scope>test</scope>
+</dependency>Use Pact as you normally would. +Remember that your consumer tests should be testing your application’s code, not the behaviour of the Pact-provided mock.
+For example, a simple consumer test for REST endpoints would look like this:
+(1)
+@ExtendWith(PactConsumerTestExt.class)
+@PactTestFor(providerName = "farm", port = "8085")
+@PactDirectory("target/pacts")
+@QuarkusTest // Needed to enable dependency injection of the rest client
+public class ConsumerTest {
+
+ (2)
+ @Inject
+ Knitter knitter;
+
+ @Pact(provider = "farm", consumer = "knitter")
+ public V4Pact createPact(PactDslWithProvider builder) {
+ Map<String, String> headers = new HashMap<>();
+ headers.put("Content-Type", "application/json");
+
+ var requestBody = newJsonBody(body -> body.stringType("colour").numberType("orderNumber")).build(); (3)
+
+ var woolResponseBody = newJsonBody(body -> body.stringValue("colour", "white")).build(); (4)
+
+ (5)
+ return builder.uponReceiving("post request").path("/wool/order").headers(headers).method(HttpMethod.POST)
+ .body(requestBody).willRespondWith().status(Status.OK.getStatusCode()).headers(headers).body(woolResponseBody)
+ .toPact(V4Pact.class);
+
+ }
+
+ @Test
+ public void testConsumption() { (6)
+ String knitted = knitter.knit("irrelevant"); (7)
+ assertEquals("a nice striped sweater", knitted);
+ }
+}| 1 | +Add @Consumer annotations to the class, along with metadata about who the consumer is, and what provider is being used. |
+
| 2 | +The consumer under test. | +
| 3 | +This defines what the body of the request could look like; we are generic and say it can be anything that meets the schema. +We could be stricter and put more expectations on what the consumer sends. | +
| 4 | +We use the Pact DSL to define what the provider should return, given the request. | +
| 5 | +Here we define our mock, which is also our expectations for the provider. +There is no need to verify these in this test; instead, the provider test will verify them. | +
| 6 | +This test is realistic (in a simplified way) of how a consumer test might look. | +
| 7 | +We have hardcoded the mock response, so the colour parameter we pass in is irrelevant (for this particular test) It tests how the consumer under test uses what the mock passes back, not the mock itself. | +
For the moment, Pact needs to be configured by the normal Pact system properties.
+Consumer tests cannot directly access the Pact MockServer when continuous testing is being used (GitHub issue)
@TestProfile does not work in dev mode (GitHub issue)
How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+Pact is a polyglot contract testing framework. +This set of extensions ensures Pact JVM libraries works well with Quarkus applications, including with continuous testing. +They are based on version 4.6.7 of the Pact JVM JUnit 5 library.
+You can find the full set of extensions and documentation for each of them in the navigation on the left.
+This extension ensures Pact provider libraries works well with Quarkus applications, including with continuous testing. +It is based on version 4.6.7 of the Pact JVM JUnit 5 library.
+To use this extension, add the io.quarkiverse:quarkus-pact-provider extension first to your build file.
+Choose a 1.x version for Quarkus 3, and a 0.x version for Quarkus 2.
<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkus-pact-provider</artifactId>
+ <version>1.3.0</version>
+ <scope>test</scope>
+</dependency>Use Pact as you normally would. +For example, a simple provider test for REST endpoints would look like this:
+@Provider("Farm") (1)
+@PactFolder("pacts")
+@QuarkusTest
+public class SimpleContractTest {
+
+ (2)
+ @ConfigProperty(name = "quarkus.http.test-port")
+ int quarkusPort;
+
+ @BeforeEach
+ void before(PactVerificationContext context) {
+ context.setTarget(new HttpTestTarget("localhost", quarkusPort)); (3)
+ }
+
+ @TestTemplate (4)
+ @ExtendWith(PactVerificationInvocationContextProvider.class)
+ void pactVerificationTestTemplate(PactVerificationContext context) {
+ context.verifyInteraction();
+ }
+}| 1 | +Add @Provider annotations to the class, along with instructions where to find the pacts (a folder or a broker). |
+
| 2 | +We inject Quarkus configuration. | +
| 3 | +With the injected configuration, we can tell the Pact verifier where to look for our endpoints. | +
| 4 | +Standard Pact provider boilerplate, to create a series of templated tests which run the Pact verifications. | +
For the moment, Pact needs to be configured by the normal Pact system properties.
+@State methods do not not have access to the CDI context (GitHub issue)
When changing the code of classes with a @TestTemplate, continuous testing may not automatically retrigger (Fix PR)
@TestProfile does not work in dev mode (GitHub issue)
How to use Pact’s Java library
+Eric Deandrea and Holly Cummins +recently spoke about contract testing with Pact. Watch the replay and view the slides if you’d like to learn more about contract testing and see the Pact extensions in action.
+The Quarkus Superheroes sample includes Pact tests
+This extension provides support for Apache PDFBox. +It allows you to create and manipulate PDF documents and forms programmatically and compile to native code with GraalVM.
+If you want to use this extension, you need to add the io.quarkiverse.pdfbox:quarkus-pdfbox extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.pdfbox</groupId>
+ <artifactId>quarkus-pdfbox</artifactId>
+ <version>1.0.0</version>
+</dependency>Easily create effective cross-browsers e2e tests for your Quarkus web-app using Playwright (Qute, Quinoa, Renarde, Web-Bundler, …):
+If you want to use this extension, you need to add the io.quarkiverse.playwright:quarkus-playwright extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.playwright</groupId>
+ <artifactId>quarkus-playwright</artifactId>
+ <version>0.0.1</version>
+ <scope>test</scope>
+</dependency>@QuarkusTest
+@WithPlaywright
+public class WithDefaultPlaywrightTest {
+
+ @InjectPlaywright
+ BrowserContext context;
+
+ @TestHTTPResource("/")
+ URL index;
+
+ @Test
+ public void testIndex() {
+ final Page page = context.newPage();
+ Response response = page.navigate(index.toString());
+ Assertions.assertEquals("OK", response.statusText());
+
+ page.waitForLoadState();
+
+ String title = page.title();
+ Assertions.assertEquals("My Awesome App", title);
+
+ // Make sure the web app is loaded and hits the backend
+ final ElementHandle quinoaEl = page.waitForSelector(".toast-body.received");
+ String greeting = quinoaEl.innerText();
+ Assertions.assertEquals("Hello from RESTEasy Reactive", greeting);
+ }
+}Use the annotation @WithPlaywright() to change the browser (Chromium, Firefox, Webkit), headless, enable debug, logs and other options.
This extension enables you to use Apache POI in your Quarkus application.
+Apache POI is a Java API for Microsoft Documents. It allows Java programs to read and write files in Microsoft Office formats, such as Word, Excel and PowerPoint. It also allows programs to create new files in these formats. It is an open source project and is available under the Apache License.
+If you want to use this extension, you need to add the io.quarkiverse.poi:quarkus-poi extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.poi</groupId>
+ <artifactId>quarkus-poi</artifactId>
+ <version>1.0.6</version>
+</dependency>This extension enables you to use Apache POI in your Quarkus application.
+Apache POI is a Java API for Microsoft Documents. It allows Java programs to read and write files in Microsoft Office formats, such as Word, Excel and PowerPoint. It also allows programs to create new files in these formats. It is an open source project and is available under the Apache License.
+If you want to use this extension, you need to add the io.quarkiverse.poi:quarkus-poi extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.poi</groupId>
+ <artifactId>quarkus-poi</artifactId>
+ <version>2.0.5</version>
+</dependency>When building native images in Docker using the standard Quarkus Docker configuration files some additional features need to be
+installed to support Apache POI. Specifically font information is not included in Red Hat’s ubi-minimal images. To install it
+simply add these lines to your DockerFile.native file:
FROM registry.access.redhat.com/ubi8/ubi-minimal:8.7
+
+######################### Set up environment for POI ##########################
+RUN microdnf update && microdnf install freetype fontconfig && microdnf clean all
+######################### Set up environment for POI ##########################
+
+WORKDIR /work/
+RUN chown 1001 /work \
+ && chmod "g+rwX" /work \
+ && chown 1001:root /work
+COPY --chown=1001:root target/*-runner /work/application
+
+EXPOSE 8080
+USER 1001
+
+CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable pooling capabilities for JMS connections. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to enable
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Determines the maximum number of Connections the pool maintains in a single Connection pool (defaults to one). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The idle timeout (default 30 seconds) controls how long a Connection that hasn’t been or currently isn’t loaned out to any client will remain idle in the Connection pool before it is eligible to be closed and discarded. To disable idle timeouts the value should be set to 0 or a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+used to establish a periodic check for expired Connections which will close all Connection that have exceeded the set expiration value. This value is set to 0ms by default and only activates if set to a positive non-zero value. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+by default the JMS pool will use it’s own generic JMSContext classes to wrap a Connection borrowed from the pool instead of using the JMSContext functionality of the JMS ConnectionFactory that was configured. This generic JMSContext implementation may be limited compared to the Provider version and if that functionality is critical to the application this option can be enabled to force the pool to use the Provider JMSContext implementation. When enabled the JMSContext API is then not part of the Connections that are pooled by this JMS Connection pooling library. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+For each Connection in the pool there can be a configured maximum number of Sessions that the pooled Connection will loan out before either blocking or throwing an error (based on configuration). By default this value is 500 meaning that each provider Connection is limited to 500 sessions, this limit can be disabled by setting the value to a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+When true (default) a call to createSession on a Connection from the pool will block until another previously created and loaned out session is closed an thereby becomes available. When false a call to createSession when no Session is available will throw an IllegalStateException to indicate that the Connection is not able to provide a new Session at that time. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When the blockIfSessionPoolIsFull option is enabled and this value is set then a call to createSession that has blocked awaiting a Session will wait for the specified number of milliseconds before throwing an IllegalStateException. By default this value is set to -1 indicating that the createSession call should block forever if configured to wait. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+By default a Session that has been loaned out on a call to createSession will use a single anonymous JMS MessageProducer as the underlying producer for all calls to createProducer. In some rare cases this is not desirable and this feature can be disabled using this option, when disabled every call to createProducer will result in a new MessageProducer instance being created. +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus extension for a JMS Connection pool and transaction manager integration for messaging applications supporting JMS 1.1 and 2.0 clients.
+If you want to use this extension, you need to add the io.quarkiverse.messaginghub:quarkus-pooled-jms extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.messaginghub</groupId>
+ <artifactId>quarkus-pooled-jms</artifactId>
+</dependency>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable pooling capabilities for JMS connections. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to enable
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Determines the maximum number of Connections the pool maintains in a single Connection pool (defaults to one). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The idle timeout (default 30 seconds) controls how long a Connection that hasn’t been or currently isn’t loaned out to any client will remain idle in the Connection pool before it is eligible to be closed and discarded. To disable idle timeouts the value should be set to 0 or a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+used to establish a periodic check for expired Connections which will close all Connection that have exceeded the set expiration value. This value is set to 0ms by default and only activates if set to a positive non-zero value. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+by default the JMS pool will use it’s own generic JMSContext classes to wrap a Connection borrowed from the pool instead of using the JMSContext functionality of the JMS ConnectionFactory that was configured. This generic JMSContext implementation may be limited compared to the Provider version and if that functionality is critical to the application this option can be enabled to force the pool to use the Provider JMSContext implementation. When enabled the JMSContext API is then not part of the Connections that are pooled by this JMS Connection pooling library. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+For each Connection in the pool there can be a configured maximum number of Sessions that the pooled Connection will loan out before either blocking or throwing an error (based on configuration). By default this value is 500 meaning that each provider Connection is limited to 500 sessions, this limit can be disabled by setting the value to a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+When true (default) a call to createSession on a Connection from the pool will block until another previously created and loaned out session is closed an thereby becomes available. When false a call to createSession when no Session is available will throw an IllegalStateException to indicate that the Connection is not able to provide a new Session at that time. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When the blockIfSessionPoolIsFull option is enabled and this value is set then a call to createSession that has blocked awaiting a Session will wait for the specified number of milliseconds before throwing an IllegalStateException. By default this value is set to -1 indicating that the createSession call should block forever if configured to wait. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+By default a Session that has been loaned out on a call to createSession will use a single anonymous JMS MessageProducer as the underlying producer for all calls to createProducer. In some rare cases this is not desirable and this feature can be disabled using this option, when disabled every call to createProducer will result in a new MessageProducer instance being created. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable pooling capabilities for JMS connections. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to enable
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Determines the maximum number of Connections the pool maintains in a single Connection pool (defaults to one). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The idle timeout (default 30 seconds) controls how long a Connection that hasn’t been or currently isn’t loaned out to any client will remain idle in the Connection pool before it is eligible to be closed and discarded. To disable idle timeouts the value should be set to 0 or a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+used to establish a periodic check for expired Connections which will close all Connection that have exceeded the set expiration value. This value is set to 0ms by default and only activates if set to a positive non-zero value. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+by default the JMS pool will use it’s own generic JMSContext classes to wrap a Connection borrowed from the pool instead of using the JMSContext functionality of the JMS ConnectionFactory that was configured. This generic JMSContext implementation may be limited compared to the Provider version and if that functionality is critical to the application this option can be enabled to force the pool to use the Provider JMSContext implementation. When enabled the JMSContext API is then not part of the Connections that are pooled by this JMS Connection pooling library. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+For each Connection in the pool there can be a configured maximum number of Sessions that the pooled Connection will loan out before either blocking or throwing an error (based on configuration). By default this value is 500 meaning that each provider Connection is limited to 500 sessions, this limit can be disabled by setting the value to a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+When true (default) a call to createSession on a Connection from the pool will block until another previously created and loaned out session is closed an thereby becomes available. When false a call to createSession when no Session is available will throw an IllegalStateException to indicate that the Connection is not able to provide a new Session at that time. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When the blockIfSessionPoolIsFull option is enabled and this value is set then a call to createSession that has blocked awaiting a Session will wait for the specified number of milliseconds before throwing an IllegalStateException. By default this value is set to -1 indicating that the createSession call should block forever if configured to wait. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+By default a Session that has been loaned out on a call to createSession will use a single anonymous JMS MessageProducer as the underlying producer for all calls to createProducer. In some rare cases this is not desirable and this feature can be disabled using this option, when disabled every call to createProducer will result in a new MessageProducer instance being created. +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus extension for a JMS Connection pool and transaction manager integration for messaging applications supporting JMS 1.1 and 2.0 clients.
+If you want to use this extension, you need to add the io.quarkiverse.messaginghub:quarkus-pooled-jms extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.messaginghub</groupId>
+ <artifactId>quarkus-pooled-jms</artifactId>
+ <version>2.3.1</version>
+</dependency>It is enabled by default. And we test for quarkus-artemis and quarkus-qpid-jms
| + + | +
+
+
+
|
+
It needs to add quarkus-narayana-jta extension:
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-narayana-jta</artifactId>
+</dependency>and add the following configuration to your application.properties:
quarkus.pooled-jms.transaction=xa
+quarkus.transaction-manager.enable-recovery=trueXA support is only available with quarkus-artemis-jms.
For those messaging drivers which do not have quarkus extension, such as ibmmq-client. You need to create a custom ConnectionFactory and wrap it by yourself. Here is an example:
@Produces
+public ConnectionFactory createXAConnectionFactory(PooledJmsWrapper wrapper) {
+ MQXAConnectionFactory mq = new MQXAConnectionFactory();
+ try {
+ mq.setHostName(ConfigProvider.getConfig().getValue("ibm.mq.host", String.class));
+ mq.setPort(ConfigProvider.getConfig().getValue("ibm.mq.port", Integer.class));
+ mq.setChannel(ConfigProvider.getConfig().getValue("ibm.mq.channel", String.class));
+ mq.setQueueManager(ConfigProvider.getConfig().getValue("ibm.mq.queueManagerName", String.class));
+ mq.setTransportType(WMQConstants.WMQ_CM_CLIENT);
+ mq.setStringProperty(WMQConstants.USERID,
+ ConfigProvider.getConfig().getValue("ibm.mq.user", String.class));
+ mq.setStringProperty(WMQConstants.PASSWORD,
+ ConfigProvider.getConfig().getValue("ibm.mq.password", String.class));
+ } catch (Exception e) {
+ throw new RuntimeException("Unable to create new IBM MQ connection factory", e);
+ }
+ return wrapper.wrapConnectionFactory(mq);
+}| + + | +
+
+
+If you use
+
+
+
+
+
+it may be ignored and can be assumed that MQ has discarded the transaction’s work. + |
+
It needs to set the following configuration:
+quarkus.pooled-jms.transaction=enabledand if it is running in a transaction, it can mark the session with SESSION_TRANSACTED and commit or rollback the session according to the outcome of the globe transaction. The example like sending message:
@Transactional
+protected void send(String body, ConnectionFactory factory, String queueName) {
+ try (JMSContext context = factory.createContext()) {
+ JMSProducer producer = context.createProducer();
+ producer.send(ActiveMQDestination.createQueue(queueName), body);
+
+ log.info("send {}", body);
+ }
+}| + + | +
+
+
+It is different from the XA support. So if there is any issue happening during the session committing, the transaction will not be rollbacked. + |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable pooling capabilities for JMS connections. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to enable
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Determines the maximum number of Connections the pool maintains in a single Connection pool (defaults to one). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+The idle timeout (default 30 seconds) controls how long a Connection that hasn’t been or currently isn’t loaned out to any client will remain idle in the Connection pool before it is eligible to be closed and discarded. To disable idle timeouts the value should be set to 0 or a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+used to establish a periodic check for expired Connections which will close all Connection that have exceeded the set expiration value. This value is set to 0ms by default and only activates if set to a positive non-zero value. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+by default the JMS pool will use it’s own generic JMSContext classes to wrap a Connection borrowed from the pool instead of using the JMSContext functionality of the JMS ConnectionFactory that was configured. This generic JMSContext implementation may be limited compared to the Provider version and if that functionality is critical to the application this option can be enabled to force the pool to use the Provider JMSContext implementation. When enabled the JMSContext API is then not part of the Connections that are pooled by this JMS Connection pooling library. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+For each Connection in the pool there can be a configured maximum number of Sessions that the pooled Connection will loan out before either blocking or throwing an error (based on configuration). By default this value is 500 meaning that each provider Connection is limited to 500 sessions, this limit can be disabled by setting the value to a negative number. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+When true (default) a call to createSession on a Connection from the pool will block until another previously created and loaned out session is closed an thereby becomes available. When false a call to createSession when no Session is available will throw an IllegalStateException to indicate that the Connection is not able to provide a new Session at that time. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When the blockIfSessionPoolIsFull option is enabled and this value is set then a call to createSession that has blocked awaiting a Session will wait for the specified number of milliseconds before throwing an IllegalStateException. By default this value is set to -1 indicating that the createSession call should block forever if configured to wait. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+By default a Session that has been loaned out on a call to createSession will use a single anonymous JMS MessageProducer as the underlying producer for all calls to createProducer. In some rare cases this is not desirable and this feature can be disabled using this option, when disabled every call to createProducer will result in a new MessageProducer instance being created. +
+
+Environment variable: |
+boolean |
+
|
+
PrettyTime is an OpenSource time formatting library. It creates human readable, relative timestamps.
+If you want to use this extension, you need to add the io.quarkiverse.prettytime:quarkus-prettytime extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.prettytime</groupId>
+ <artifactId>quarkus-prettytime</artifactId>
+ <version>2.0.1</version>
+</dependency>A singleton org.ocpsoft.prettytime.PrettyTime can be injected anywhere.
// Inject PrettyTime using the default locale
+@Inject PrettyTime prettyTime;Important: Be aware that any changes to the injected PrettyTime object (as in calling setLocale or setReference) will reflect on the singleton and its usage in your entire application. In cases where you need to format to a specific locale we recommend you to create a new PrettyTime object instead.
The singleton may be referenced by the name prettyTime when used in a non-typesafe environment such as templates. For example, if used together with the Qute templating engine:
<table>
+ {#for label in labels}
+ <tr>
+ <td>{label.name}</td>
+ <td>Created {inject:prettyTime.format(label.created)}</td>
+ </tr>
+ {/for}
+</table>A Quarkus extension that lets you utilize PrimeFaces and PrimeFaces Extensions make JSF development so much easier!
+If you want to use this extension, you need to add the io.quarkiverse.primefaces:quarkus-primefaces extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.primefaces</groupId>
+ <artifactId>quarkus-primefaces</artifactId>
+ <version>3.13.10</version>
+</dependency>
+<dependency>
+ <groupId>io.quarkiverse.primefaces</groupId>
+ <artifactId>quarkus-primefaces-extensions</artifactId>
+ <version>3.13.10</version>
+</dependency>When creating a GraalVM Native image you may need to change some of your code to be native friendly and some features may not be available to use in Native mode.
+| + + | ++FeedReader not supported. Rome library uses JDOM XML parsing and we did not spend the time to investigate for a lightly used component. + | +
| + + | ++EL expressions which use reflection may run into issues with things like List size() or Enum name() as they are not bean compliant method names. You might need to change your EL expression or add helper code to achieve what you want. + | +
The versioning of this extension will follow the pattern [quarkus.version].[primefaces.version].[patch]. For example:
| Version | +Explanation | +
|---|---|
2.12.1 |
+Quarkus 2 (EE8), PrimeFaces 12, Revision 1 |
+
3.12.0 |
+Quarkus 3 (EEE10), PrimeFaces 12, Revision 0 |
+
Add a build script in the package.json to generate your web application index.html, scripts and assets (styles, images, …) in some build directory (configurable Build Dir).
"scripts": {
+ "start": "[start the Web UI live coding server]",
+ "build": "[build the Web UI]",
+ "test": "[test the Web UI]"
+ },| + + | +
+The build directory will automatically be moved by Quinoa to target/quinoa-build when using Maven (build/quinoa-build with Gradle) in order to be served.
+ |
+
You can differentiate development from production builds using the environment variable NODE_ENV (production/development). by-node-env can help you if you have different build commands:
"scripts": {
+ "build": "by-node-env",
+ "build:development": "...",
+ "build:production": "...",
+},
+"devDependencies": {
+ "by-node-env": "~2.0.1"
+}Quinoa can be configured to install NodeJS and NPM in the project directory:
+quarkus.quinoa.package-manager-install=true (1)
+quarkus.quinoa.package-manager-install.node-version=20.10.0 (2)
+quarkus.quinoa.package-manager-install.npm-version=10.2.3 (3)| 1 | +Enable package manager install | +
| 2 | +Define the version of NodeJS to install | +
| 3 | +Define the version of NPM to install | +
| + + | +
+By default, NodeJS and NPM will be installed in {project-dir}/.quinoa/ (can be configured). If not specified, it will use the NPM version provided by NodeJS.
+ |
+
If NodeJS and NPM are not installed by Quinoa, it is possible to override the package manager (NPM, Yarn or PNPM), otherwise, it will be auto-detected depending on the project lockfile (NPM is the fallback):
+Use quarkus.quinoa.package-manager if present
Else if yarn.lock then Yarn
Else if pnpm-lock.yaml then PNPM
Else NPM
+| + + | ++By default, Quinoa is configured with the commands to call depending on the chosen package manager (to always keep the same behavior and make it easy to switch). + | +
By default, Quinoa will call the appropriate package manager install command (before building or starting) only if the node_modules directory doesn’t exist.
You may force a new installation using -Dquarkus.quinoa.force-install=true.
| + + | +
+Quinoa will use the appropriate package manager frozen-lockfile command when installing, if the environment CI=true, or if quarkus.quinoa.frozen-lockfile=true. In this mode, the lockfile have to be present in the project.
+ |
+
By default, the following commands and environment variables are used in the different faces for each of the supported package managers.
+Install:
+npm install (npm ci if quarkus.quinoa.frozen-lockfile=true).
pnpm install (pnpm install --frozen-lockfile if quarkus.quinoa.frozen-lockfile=true).
yarn install (yarn install --frozen-lockfile if quarkus.quinoa.frozen-lockfile=true).
Build:
+(npm|pnpm|yarn) run build, with environment MODE=${mode} (dev, test or prod)
Test:
+(npm|pnpm|yarn) test, with environment CI=true
Dev:
+(npm|pnpm|yarn) start, with environment BROWSER=none
By default, Quinoa uses sensible default commands when executing the different phases, install, build, test, dev.
+It is possible to override one or more of them from the package manager command configuration:
quarkus.quinoa.package-manager-command.install=npm ci --cache $CACHE_DIR/.npm --prefer-offline (1)
+quarkus.quinoa.package-manager-command.build-env.BUILD=value (2)| 1 | +This makes npm ci --cache $CACHE_DIR/.npm --prefer-offline the command executed in the install phase.
+(overriding quarkus.quinoa.package-manager and quarkus.quinoa.frozen-lockfile=true). |
+
| 2 | +set environment variable BUILD with value value. Environment variables set in config can be added to the listed commands. |
+
| + + | +
+Using custom commands will override quarkus.quinoa.package-manager and quarkus.quinoa.frozen-lockfile.
+ |
+
| + + | +
+if NodeJS is installed by Quinoa, you need to enable: quarkus.quinoa.package-manager-command.prepend-binary and adapt the command to only specify the arguments (the binary to call will be prepended by Quinoa).
+ |
+
Quinoa provides two options for live-coding:
+Delegate to the UI live-coding dev server (proxy mode). To enable it, configure the port of the UI server. By convention Quinoa will call the start script from the package.json to start the UI server process. Then it will transparently proxy relevant requests to the given port.
Quarkus watches the files and Quinoa triggers a new Web UI build on changes (you can configure different builds for dev and prod).
+To enable the UI live-coding dev server, set a start script and set the port in the app config. Quinoa will transparently proxy relevant requests to the given port:
quarkus.quinoa.dev-server.port=3000| + + | ++Quinoa relies on the dev server returning a 404 when the file is not found (See How it works). This is not the case on some dev servers configured with SPA routing. Make sure it is disabled in the dev server configuration (for React Create App, see #91). Another option, when possible, is to use Ignored Path Prefixes. + | +
Client-side/Browser/SPA routing is the internal handling of a route from the javascript in the browser. It uses the HTML5 History API
+When enabled, to allow SPA routing, all relevant requests will be internally re-routed to index.html, this way the javascript can take care of the route inside the web-application.
+To enable Single Page application routing:
+quarkus.quinoa.enable-spa-routing=true| + + | +
+By default, Quinoa will ignore quarkus.resteasy-reactive.path, quarkus.resteasy.path and quarkus.http.non-application-root-path path prefixes. You can specify different path prefixes to ignore using quarkus.quinoa.ignored-path-prefixes.
+ |
+
| + + | ++Currently, for technical reasons, the Quinoa SPA routing configuration won’t work with RESTEasy Classic. Instead, you may use a workaround (if your app has all the rest resources under the same path prefix): + | +
@ApplicationScoped
+public class SPARouting {
+ // Vite in dev mode requests /@vite/client and /@reactrefresh so add "/@" if you use Vite
+ private static final String[] PATH_PREFIXES = {"/q/", "/api/", "/@"};
+ private static final Predicate<String> FILE_NAME_PREDICATE = Pattern.compile(".+\\.[a-zA-Z0-9]+$").asMatchPredicate();
+
+ public void init(@Observes Router router) {
+ router.get("/*").handler(rc -> {
+ final String path = rc.normalizedPath();
+ if (!path.equals("/")
+ && Stream.of(PATH_PREFIXES).noneMatch(path::startsWith)
+ && !FILE_NAME_PREDICATE.test(path)) {
+ rc.reroute("/");
+ } else {
+ rc.next();
+ }
+ });
+ }
+}It’s very common to set up headers for caching on static resources, for example React proposes this configuration:
+To configure Quarkus with those headers :
+quarkus.http.filter.others.header.Cache-Control=no-cache
+quarkus.http.filter.others.matches=/.*
+quarkus.http.filter.others.methods=GET
+quarkus.http.filter.others.order=0
+quarkus.http.filter.static.header.Cache-Control=max-age=31536000
+quarkus.http.filter.static.matches=/static/.+
+quarkus.http.filter.static.methods=GET
+quarkus.http.filter.static.order=1To enable server Http compression:
+quarkus.http.enable-compression=trueMany Quinoa projects commonly utilize REST services, specifying their requirements with OpenAPI support in Quarkus. If you wish to streamline the process of generating TypeScript code for your React/Vue/Angular web application using the OpenAPI spec, you can now achieve it effortlessly in a single step.
+Start by configuring OpenAPI to consistently generate code in the designated directory, such as /src/main/webui, where your Quinoa UI is intended to reside.
quarkus.smallrye-openapi.store-schema-directory=src/main/webui/Whenever you execute mvn quarkus:dev, it automatically produces the openapi.json in the specified directory. Following this, it is essential to notify your JavaScript application about the changes and facilitate the automatic generation of new TypeScript code from your OpenAPI. A solution like Orval can be incredibly helpful in this scenario!
+"scripts": {
+ "dev": "orval --config ./orval.config.ts && vite",
+ "build": "orval --config ./orval.config.ts && vite build",
+},
+"devDependencies": {
+ "orval": "6.24.0",
+}Most CI images already include NodeJS. if they don’t, just make sure to install it alongside Maven/Gradle (and Yarn/PNPM if needed). Then you can use it like any Maven/Gradle project.
+Quinoa can be configured to install packages with a frozen lockfile.
+On compatible CIs, don’t forget to enable the Maven/Gradle and NPM/Yarn repository caching.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+Indicate if the extension should be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicate if Quinoa should just do the build part. If true, Quinoa will NOT serve the Web UI built resources. This is handy when the output of the build is used to be served via something else (nginx, cdn, …) Quinoa put the built files in 'target/quinoa/build' (or 'build/quinoa/build with Gradle). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to the Web UI (NodeJS) root directory (relative to the project root). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This the Web UI internal build system (webpack, …) output directory. After the build, Quinoa will take the files from this directory, move them to 'target/quinoa/build' (or build/quinoa/build with Gradle) and serve them at runtime. The path is relative to the Web UI path. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the package manager binary. Only npm, pnpm and yarn are supported for the moment. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable Package Manager Installation. This will override "package-manager" config. Set "quarkus.quinoa.package-manager-command.prepend-binary=true" when using with custom commands +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory where NodeJS should be installed (relative to the project root), It will be installed in a 'node/' subdirectory of this. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The NodeJS Version to install locally to the project. Required when package-manager-install is enabled. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The NPM version to install and use. By default, the version is provided by NodeJS. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Where to download NPM from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download NodeJS from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Install and use Yarn as package manager with this version. This is ignored if the npm-version is defined. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download YARN from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Install and use PNPM as package manager with this version. This is ignored if the npm-version or the yarn-version is defined. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download PNPM from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The basic authentication username to use for node download. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The basic authentication password to use for node download. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Custom command for installing all packages. e.g. «ci --cache $CACHE_DIR/.npm --prefer-offline» +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for installing all the packages without generating a lockfile (frozen lockfile) and failing if an update is needed (useful in CI). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for building the application. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for running tests for the application. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for starting the application in development mode. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the index page. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicate if the Web UI should also be tested during the build phase (i.e: npm test). To be used in a
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Install the packages without generating a lockfile (frozen lockfile) and failing if an update is needed (useful in CI). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Force install packages before building. It will install packages only if the node_modules directory is absent or when the package.json is modified in dev-mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When true, the UI Framework will be auto-detected if possible +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable SPA (Single Page Application) routing, all relevant requests will be re-routed to the index page. Currently, for technical reasons, the Quinoa SPA routing configuration won’t work with RESTEasy Classic. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+List of path prefixes to be ignored by Quinoa. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable external dev server (live coding). If the "dev-server.port" config is not detected or defined it will be disabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When set to true, Quinoa will manage the Web UI dev server When set to false, the Web UI dev server have to be started before running Quarkus dev +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Port of the server to forward requests to. The dev server process (i.e npm start) is managed like a dev service by Quarkus. If the external server responds with a 404, it is ignored by Quinoa and processed like any other backend request. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Host of the server to forward requests to. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+After start, Quinoa wait for the external dev server. by sending GET requests to this path waiting for a 200 status. If forced empty, Quinoa will not check if the dev server is up. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+By default, Quinoa will handle request upgrade to websocket and act as proxy with the dev server. If set to false, Quinoa will pass websocket upgrade request to the next Vert.x route handler. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Timeout in ms for the dev server to be up and running. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable external dev server live coding logs. This is not enabled by default because most dev servers display compilation errors directly in the browser. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Set this value if the index page is different for the dev-server +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Quinoa deals with SPA routing by itself (see quarkus.quinoa.enable-spa-routing), some dev-server have this feature enabled by default. This is a problem for proxying as it prevents other Quarkus resources (REST, …) to answer. By default, Quinoa will try to detect when the dev server is answering with a html page for non-existing resources (SPA-Routing) in which case it will instead allow other Quarkus resources (REST, …) to answer. Set this to true (direct) when the other Quarkus resources use a specific path prefix (and marked as ignored by Quinoa) or if the dev-server is configured without SPA routing. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Environment variables for install command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for ci command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for build command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for test command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for development command execution. +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+
+
+Indicate if the extension should be enabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Indicate if Quinoa should just do the build part. If true, Quinoa will NOT serve the Web UI built resources. This is handy when the output of the build is used to be served via something else (nginx, cdn, …) Quinoa put the built files in 'target/quinoa/build' (or 'build/quinoa/build with Gradle). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to the Web UI (NodeJS) root directory (relative to the project root). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This the Web UI internal build system (webpack, …) output directory. After the build, Quinoa will take the files from this directory, move them to 'target/quinoa/build' (or build/quinoa/build with Gradle) and serve them at runtime. The path is relative to the Web UI path. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the package manager binary. Only npm, pnpm and yarn are supported for the moment. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Enable Package Manager Installation. This will override "package-manager" config. Set "quarkus.quinoa.package-manager-command.prepend-binary=true" when using with custom commands +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory where NodeJS should be installed (relative to the project root), It will be installed in a 'node/' subdirectory of this. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The NodeJS Version to install locally to the project. Required when package-manager-install is enabled. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The NPM version to install and use. By default, the version is provided by NodeJS. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Where to download NPM from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download NodeJS from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Install and use Yarn as package manager with this version. This is ignored if the npm-version is defined. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download YARN from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Install and use PNPM as package manager with this version. This is ignored if the npm-version or the yarn-version is defined. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Where to download PNPM from. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The basic authentication username to use for node download. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The basic authentication password to use for node download. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Custom command for installing all packages. e.g. «ci --cache $CACHE_DIR/.npm --prefer-offline» +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for installing all the packages without generating a lockfile (frozen lockfile) and failing if an update is needed (useful in CI). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for building the application. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for running tests for the application. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Custom command for starting the application in development mode. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Name of the index page. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicate if the Web UI should also be tested during the build phase (i.e: npm test). To be used in a
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Install the packages without generating a lockfile (frozen lockfile) and failing if an update is needed (useful in CI). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Force install packages before building. It will install packages only if the node_modules directory is absent or when the package.json is modified in dev-mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When true, the UI Framework will be auto-detected if possible +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable SPA (Single Page Application) routing, all relevant requests will be re-routed to the index page. Currently, for technical reasons, the Quinoa SPA routing configuration won’t work with RESTEasy Classic. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+List of path prefixes to be ignored by Quinoa. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable external dev server (live coding). If the "dev-server.port" config is not detected or defined it will be disabled. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When set to true, Quinoa will manage the Web UI dev server When set to false, the Web UI dev server have to be started before running Quarkus dev +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Port of the server to forward requests to. The dev server process (i.e npm start) is managed like a dev service by Quarkus. If the external server responds with a 404, it is ignored by Quinoa and processed like any other backend request. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Host of the server to forward requests to. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+After start, Quinoa wait for the external dev server. by sending GET requests to this path waiting for a 200 status. If forced empty, Quinoa will not check if the dev server is up. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+By default, Quinoa will handle request upgrade to websocket and act as proxy with the dev server. If set to false, Quinoa will pass websocket upgrade request to the next Vert.x route handler. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Timeout in ms for the dev server to be up and running. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Enable external dev server live coding logs. This is not enabled by default because most dev servers display compilation errors directly in the browser. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Set this value if the index page is different for the dev-server +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Quinoa deals with SPA routing by itself (see quarkus.quinoa.enable-spa-routing), some dev-server have this feature enabled by default. This is a problem for proxying as it prevents other Quarkus resources (REST, …) to answer. By default, Quinoa will try to detect when the dev server is answering with a html page for non-existing resources (SPA-Routing) in which case it will instead allow other Quarkus resources (REST, …) to answer. Set this to true (direct) when the other Quarkus resources use a specific path prefix (and marked as ignored by Quinoa) or if the dev-server is configured without SPA routing. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Environment variables for install command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for ci command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for build command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for test command execution. +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Environment variables for development command execution. +
+
+Environment variable: |
+
|
++ |
Quinoa is a Quarkus extension which eases the development, the build and serving single page apps or web components (built with NodeJS : React, Angular, Vue, Lit, Svelte, Astro, SolidJS …) alongside other Quarkus services (REST, GraphQL, Security, Events, …).
+Live code the backend and frontend together with close to no configuration. When enabled in development mode, Quinoa will start the UI live coding server provided by the target framework and forward relevant requests to it. In production mode, Quinoa will run the build and process the generated files to serve them at runtime.
+Create or use an existing Quarkus application
+Add the Quinoa extension
+Install NodeJS (https://nodejs.org/) or make sure Quinoa is configured to install it, see the following example.
+quarkus.quinoa.package-manager-install.node-version=20.10.0 +quarkus.quinoa.package-manager-install.npm-version=10.2.3+
Create a new Quinoa project (with a base Quinoa starter code):
+With code.quarkus.io
+With the Quarkus CLI:
+quarkus create app quinoa-app -x=io.quarkiverse.quinoa:quarkus-quinoa+
Then start the live-coding:
+quarkus devAnd navigate to http://0.0.0.0:8080/quinoa.html
+You could also just add the extension (but you won’t get the starter code):
+With the Quarkus CLI:
+quarkus ext add io.quarkiverse.quinoa:quarkus-quinoa+
In your pom.xml file, add this dependency:
<dependency>
+ <groupId>io.quarkiverse.quinoa</groupId>
+ <artifactId>quarkus-quinoa</artifactId>
+ <version>2.3.4</version>
+</dependency>If not yet created by the tooling, you will need a Web UI directory in src/main/webui. This directory will contain your NodeJS Web application code with a package.json.
| + + | ++The location is configurable, the directory could be outside the Quarkus project as long as the files are available at build time. + | +
You may use an existing Web UI or generate a starter application from any existing Node based Web Framework. Some Web Frameworks are detected and preconfigured with sensible defaults. If your Web Framework is not part of the detected frameworks or if you changed the configuration, you can always configure Quinoa to work with it.
+The key points for Quinoa are:
+the package.json scripts: build, optionally start/dev and test
the directory where the web files (index.html, scripts, …) are generated: dist, build, …
+the port used by the dev-server
+quarkus.quinoa.dev-server.port=3000
+quarkus.quinoa.build-dir=distStart the Quarkus live coding:
+$ quarkus devBuild your app:
+$ quarkus build
+$ java -jar target/quarkus-app/quarkus-run.jarIt’s done! The web application is now built alongside Quarkus, dev-mode is available, and the generated files will be automatically copied to the right place and be served by Quinoa if you hit http://localhost:8080
+| + + | +
+With Quinoa, you don’t need to manually copy the files to META-INF/resources. Quinoa has its own system and will provide another Vert.x route for it. If you have conflicting files with META-INF/resources, Quinoa will have priority over them.
+ |
+
+| + + | +
+packages are installed by Quinoa before the build when needed (i.e npm install). See Packages installation. Quinoa is pre-configured to work with your favorite package manager (npm, yarn or pnpm).
+ |
+
Quinoa (using Quarkus live-coding watch feature) will watch the Web UI directory and trigger a new build on changes. It works the same as the production mode. This option is perfect for small/fast builds.
+| + + | ++You can differentiate the build for dev mode. e.g to disable minification. + | +
By default, the Web UI is not build/served in @QuarkusTest. The goal is to be able to test your api without having to wait for the Web UI build.
Quinoa features a testing library to make it easier to test your Web UI (it also includes Quarkus Playwright) :
+
+
+<dependency>
+ <groupId>io.quarkiverse.quinoa</groupId>
+ <artifactId>quarkus-quinoa-testing</artifactId>
+ <version>2.3.4</version>
+ <scope>test</scope>
+</dependency>In order to enable the Web UI (build and serve) in a particular test, you can use the Enable test profile:
@QuarkusTest
+@TestProfile(QuinoaTestProfiles.Enable.class)
+public class MyWebUITest {
+ @Test
+ public void someTest() {
+ // your test logic here
+ }
+}If you also want to run the tests included in your Web UI (i.e npm test) alongside this class, you can use the EnableAndRunTests test profile:
@QuarkusTest
+@TestProfile(QuinoaTestProfiles.EnableAndRunTests.class)
+public class AllWebUITest {
+ @Test
+ public void runTest() {
+ // you don't need anything here, it will run your package.json "test"
+ }
+}The library also brings a very elegant way to do e2e testing using Quarkus Playwright:
+import com.microsoft.playwright.BrowserContext;
+import com.microsoft.playwright.Page;
+import com.microsoft.playwright.Response;
+import io.quarkiverse.playwright.WithPlaywright;
+import io.quarkiverse.playwright.InjectPlaywright;
+import io.quarkus.test.common.http.TestHTTPResource;
+import io.quarkus.test.junit.QuarkusTest;
+import io.quarkus.test.junit.TestProfile;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.net.URL;
+
+@QuarkusTest
+@TestProfile(QuinoaTestProfiles.Enable.class)
+@WithPlaywright
+public class MyWebUITest {
+ @InjectPlaywright
+ BrowserContext context;
+
+ @TestHTTPResource("/")
+ URL url;
+
+ @Test
+ void name() {
+ final Page page = context.newPage();
+ Response response = page.navigate(url.toString());
+ Assertions.assertEquals("OK", response.statusText());
+
+ page.waitForLoadState();
+
+ String title = page.title();
+ Assertions.assertEquals("My App", title);
+
+ // Make sure the app content is ok
+ String greeting = page.innerText(".quinoa");
+ Assertions.assertEquals("Hello World", greeting);
+ }
+}Quinoa attempts to automatically determine which framework you are using by reading your package.json file and auto-configure settings for that framework. When possible, if some changes are required in the Web UI, it will try to help you configure it.
+For developers, this provides more "convention over configuration" approach for a smoother experience.
+| Name | +Preconfigured | +Starter | +Guides | +Config | +
|---|---|---|---|---|
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓* |
+
+
+
+ |
+
+
|
++ |
| + | ~ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ~ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+
+
+
+ |
+
+
|
++ |
| + | ✓ |
+No |
+
+
|
++ |
If you want to use the Angular tests (instead of Playwright from the @QuarkusTest):
+ browsers: ['Chrome', 'ChromeHeadless', 'ChromeHeadlessCI'],
+ customLaunchers: {
+ ChromeHeadlessCI: {
+ base: 'ChromeHeadless',
+ flags: ['--no-sandbox']
+ }
+},This will configure the build to export the static files: +.package.json:
+ "scripts": {
+ ...
+ "build": "next build",
+ }In Next.js 14+ you need to add the following property in next.config.js file:
const nextConfig = {
+ output: 'export',
+}
+Configure vite.config.ts file with the following changes:
export default defineConfig({
+ // depending on your application, base can also be "/"
+ base: '',
+ plugins: [react(), viteTsconfigPaths()],
+ server: {
+ // this ensures that the browser opens upon server start
+ open: true,
+ // this sets a default port to 3000, you can change this
+ port: 3000,
+ },
+})SvelteKit needs to be configured to create a single page application. +You will not be able to use any of its server-side only functionality. +See also SvelteKit documentation on Single-page apps.
+Disable server side rendering at the root layout (src/routes/+layout.js):
export const ssr = false;Install Svelte Static adapter:
+npm i -D @sveltejs/adapter-staticConfigure svelte.config.js file with the following changes:
import adapter from '@sveltejs/adapter-static';
+
+// In projects using Sveltekit v1
+import { vitePreprocess } from '@sveltejs/kit/vite';
+
+// In projects using SvelteKit v2
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+ preprocess: vitePreprocess(),
+ kit: {
+ adapter: adapter({
+ fallback: 'index.html'
+ }),
+ // Mark path non-relative, otherwise SvelteKit assumes it works in a sub-directory
+ paths: {
+ relative: false
+ }
+ }
+};
+
+export default config;In application.properties add:
quarkus.quinoa.build-dir=build
+quarkus.quinoa.enable-spa-routing=true
+%dev.quarkus.quinoa.dev-server.index-page=/| + + | ++Currently, for technical reasons, the Quinoa SPA routing configuration won’t work with RESTEasy Classic. See SPA routing for a workaround. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The root path. All templates will be served relative to this path which is relative to the HTTP root path. +
+
+If the template name ends with a suffix listed in the
+
+For example, a template located in
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The directory from which the templates are served. The path is relative to a template root directroy, i.e. relative to
+
+
+By default, the templates located in the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This regular expression is used to hide template files from the web templates path. Hidden templates are not exposed. +
+
+All template file paths are matched, including the versions without suffixes. The matched input is the file path relative
+from the web templates path (for example
+
+By default, no templates are hidden. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The order of the route which handles the templates. +
+
+By default, the route is executed before the default routes (static resources, etc.). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
+
|
+
The goal of this extension is to expose Qute templates located in the src/main/resource/templates/pub directory via HTTP.
+Automatically, no controllers needed.
+For example, the template src/main/resource/templates/pub/foo.html will be served from the paths /foo and /foo.html by default.
| + + | +
+The index.html and index.qute.html pages are handled specifically, i.e. they are also served as a "default page" of the containing directory. For example, the template src/main/resource/templates/pub/index.html will be served from the paths /index, /index.html and / by default.
+ |
+
If you want to use this extension, you need to add the io.quarkiverse.qute.web:quarkus-qute-web extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.qute.web</groupId>
+ <artifactId>quarkus-qute-web</artifactId>
+ <version>3.0.1</version>
+</dependency>In a template you can access:
+@Named CDI beans; similar to EL; e.g. {cdi:myBean.findItems()}
static members of a class annotated with @TemplateData
enums annotated with @TemplateEnum
Namespace Extension Methods in general
+the current io.vertx.core.http.HttpServerRequest via the http: namespace, e.g. {http:request.path}
the query parameters via the http: namespace, e.g. {http:param('name')} and {http:param('name','Foo')}
If the HTTP compression support is enabled by means of quarkus.http.enable-compression=true then the response body is compressed if the Content-Type header derived from the template file name is a compressed media type as configured via quarkus.http.compress-media-types.
It is possible to specify the template fragment via the frag query param.
+For example, if there is a template foo.html that defines a fragment with id bar then the fragment is served from the path /foo?frag=bar.
This extension attempts to serve the appropriate template and set the HTTP Content-type header based on the selected template variant and the value of Accept header.
+For example, if there are templates src/main/resource/templates/pub/foo.html and src/main/resource/templates/pub/foo.txt and the client sends the Accept: text/html, text/plain;q=0.9 header then foo.html is rendeder and the Content-type: text/html header is set.
http: NamespaceSome useful template extension methods that handle the http namespace are registered automatically.
| Name | +Description | +Example | +
|---|---|---|
|
+Returns the current |
+
|
+
|
+Returns the first HTTP request query param value with the specified name |
+
|
+
|
+Return the first HTTP request header value with the specified name |
+
|
+
|
+Makes it possible to access HTTP header values like properties |
+
|
+
| + + | ++HTTP header names are case-insensitive. + | +
| + + | +
+If you need to obtain all values of a specific HTTP header then you can use something similar to {http:request.headers.getAll('My-Header')}.
+ |
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The root path. All templates will be served relative to this path which is relative to the HTTP root path. +
+
+If the template name ends with a suffix listed in the
+
+For example, a template located in
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The directory from which the templates are served. The path is relative to a template root directroy, i.e. relative to
+
+
+By default, the templates located in the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+This regular expression is used to hide template files from the web templates path. Hidden templates are not exposed. +
+
+All template file paths are matched, including the versions without suffixes. The matched input is the file path relative
+from the web templates path (for example
+
+By default, no templates are hidden. +
+
+Environment variable: |
++ | + |
+
+
+
+
+
+The order of the route which handles the templates. +
+
+By default, the route is executed before the default routes (static resources, etc.). +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+If set to
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Disables health check +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Disables metrics +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Disable the client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+URI for connecting, formatted as amqp://userName:password@hostName:portNumber/virtualHost +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Password for authentication +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Hostname for connecting +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Virtual host +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Port number for connecting +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Connection timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Connection close timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Heartbeat interval in seconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Handshake timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Shutdown timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Maximum number of channels per connection +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Maximum frame size +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Network recovery interval in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Channel RPC timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Validate channel RPC response type +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Recover connection on failure +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Recover topology on failure +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+SASL authentication mechanisms +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Client properties +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Hostname for connecting +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+
+Port number for connecting +
+
+Environment variable: |
+int |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Enables TLS +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+TLS Algorithm to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Trust store type +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store algorithm +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store type +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Key store algorithm +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Validate server certificate +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Verify hostname +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Enables non blocking IO +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Read buffer size in bytes +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write buffer size in bytes +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Number of non blocking IO threads +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write enqueuing timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write queue capacity. +
+
+Environment variable: |
+int |
+
|
+
RabbitMQ is a popular message broker. This Quarkus extension provides a client for RabbitMQ which is configurable using the application.properties.
If you want to use this extension, you need to add the quarkus-rabbitmq-client extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse</groupId>
+ <artifactId>quarkus-rabbitmq-client</artifactId>
+ <version>3.0.1</version>
+</dependency>Assuming you have RabbitMQ running on localhost:5672 you should add the following properties to your application.properties and fill in the values for <username> and <password>.
quarkus.rabbitmqclient.virtual-host=/
+quarkus.rabbitmqclient.username=<username>
+quarkus.rabbitmqclient.password=<password>
+quarkus.rabbitmqclient.hostname=localhost
+quarkus.rabbitmqclient.port=5672Once you have configured the properties, you can start using the RabbitMQ client.
+package org.acme.rabbitmqclient;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+
+import com.rabbitmq.client.*;
+import io.quarkiverse.rabbitmqclient.RabbitMQClient;
+import io.quarkus.runtime.StartupEvent;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@ApplicationScoped
+public class MessageService {
+ private static final Logger log = LoggerFactory.getLogger(MessageService.class);
+ @Inject
+ RabbitMQClient rabbitMQClient;
+ private Channel channel;
+ public void onApplicationStart(@Observes StartupEvent event) {
+ // on application start prepare the queus and message listener
+ setupQueues();
+ setupReceiving();
+ }
+
+ private void setupQueues() {
+ try {
+ // create a connection
+ Connection connection = rabbitMQClient.connect();
+ // create a channel
+ channel = connection.createChannel();
+ // declare exchanges and queues
+ channel.exchangeDeclare("test", BuiltinExchangeType.TOPIC, true);
+ channel.queueDeclare("sample.queue", true, false, false, null);
+ channel.queueBind("sample.queue", "test", "#");
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+
+ private void setupReceiving() {
+ try {
+ // register a consumer for messages
+ channel.basicConsume("sample.queue", true, new DefaultConsumer(channel) {
+ @Override
+ public void handleDelivery(String consumerTag, Envelope envelope, AMQP.BasicProperties properties, byte[] body) throws IOException {
+ // just print the received message.
+ log.info("Received: " + new String(body, StandardCharsets.UTF_8));
+ }
+ });
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+
+ public void send(String message) {
+ try {
+ // send a message to the exchange
+ channel.basicPublish("test", "#", null, message.getBytes(StandardCharsets.UTF_8));
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+}You do not need to worry about closing connections as the RabbitMQClient will close them for you on application shutdown.
The extension supports having multiple RabbitMQ clients. You can add named RabbitMQ clients as follows.
+quarkus.rabbitmqclient.<name>.virtual-host=/
+quarkus.rabbitmqclient.<name>.username=<username>
+quarkus.rabbitmqclient.<name>.password=<password>
+quarkus.rabbitmqclient.<name>.hostname=localhost
+quarkus.rabbitmqclient.<name>.port=5672All configuration options that are available on the default non named RabbitMQ client are available. Injecting a named RabbitMQ client, e.g. foo, can be achieved as follows.
+@ApplicationScoped
+public class MessageService {
+
+ @Inject
+ @NamedRabbitMQClient("foo")
+ RabbitMQClient fooClient;
+}It is possible to use multiple RabbitMQ clients in the same class as long as they are all named, or in combination with the default client. The name default is reserved for the default client and if used will trigger a deployment exception.
Both Micrometer and SmallRye Metrics are supported and enabled by default if the quarkus-micrometer or quarkus-smallrye-metrics dependency is included in the project. If both are present micrometer will be used.
Metrics are gathered on a per-client basis and tagged with name=<client-name> of the client. The default clients is tagged with name=default and are all prefixed with rabbitmq.
It is possible to opt-out of metrics by specifying quarkus.rabbitmqclient.metrics.enabled=false. This will disable all metrics gathering.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Disables health check +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Disables metrics +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Disable the client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+URI for connecting, formatted as amqp://userName:password@hostName:portNumber/virtualHost +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Username for authentication +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Password for authentication +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Hostname for connecting +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Virtual host +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Port number for connecting +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Connection timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Connection close timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Heartbeat interval in seconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Handshake timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Shutdown timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Maximum number of channels per connection +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Maximum frame size +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Network recovery interval in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Channel RPC timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Validate channel RPC response type +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Recover connection on failure +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Recover topology on failure +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+SASL authentication mechanisms +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+
+Client properties +
+
+Environment variable: |
+
|
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+
+Hostname for connecting +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+
+Port number for connecting +
+
+Environment variable: |
+int |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Enables TLS +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+TLS Algorithm to use +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Trust store type +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store algorithm +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Trust store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store password +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+
+Key store type +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Key store algorithm +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+
+Validate server certificate +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Verify hostname +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+
+Enables non blocking IO +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+
+Read buffer size in bytes +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write buffer size in bytes +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Number of non blocking IO threads +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write enqueuing timeout in milliseconds +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+
+Write queue capacity. +
+
+Environment variable: |
+int |
+
|
+
Quarkus Reactive Messaging HTTP is a Quarkus extension that brings in +support for HTTP and WebSocket for Reactive Messaging.
+If you want to use this extension, you need to add the io.quarkiverse.reactive-messaging-http:quarkus-reactive-messaging-http extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.reactive-messaging-http</groupId>
+ <artifactId>quarkus-reactive-messaging-http</artifactId>
+ <version>2.2.0</version>
+</dependency>This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to +consume and produce HTTP messages.
+To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+GraalVM, Docker or Podman installed if you want to run in native mode.
+In this guide we will implement a service, namely CostConverter that consumes HTTP messages
+with costs in multiple currencies and converts each cost to its value in Euro.
To let a user easily try out the service, we will implement an HTTP resource summing up the costs
+(CostCollector), and a simple web page to add new costs and watch the sum.
We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the reactive-messaging-http-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=reactive-messaging-http-quickstart \
+ -Dextensions="reactive-messaging-http,reasteasy-reactive-jackson" \
+ -DnoCode
+cd reactive-messaging-http-quickstartThis command generates a Maven project, importing the Reactive Messaging and HTTP connector extensions.
+Create the src/main/java/org/acme/reactivehttp/CostConverter.java file, with the following content:
package org.acme.reactivehttp;
+
+import org.eclipse.microprofile.reactive.messaging.Incoming;
+import org.eclipse.microprofile.reactive.messaging.Outgoing;
+import org.jboss.logging.Logger;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * A bean consuming costs in multiple currencies and producing prices in EUR from them
+ */
+@ApplicationScoped
+public class CostConverter {
+
+ private static final Logger log = Logger.getLogger(CostConverter.class);
+
+ private static final Map<String, Double> conversionRatios = new HashMap<>();
+
+ static {
+ conversionRatios.put("CHF", 0.93);
+ conversionRatios.put("USD", 0.84);
+ conversionRatios.put("PLN", 0.22);
+ conversionRatios.put("EUR", 1.);
+ }
+
+ @Incoming("incoming-costs") (1)
+ @Outgoing("outgoing-costs") (2)
+ double convert(Cost cost) { (3)
+ Double conversionRatio = conversionRatios.get(cost.getCurrency().toUpperCase());
+ if (conversionRatio == null) {
+ return 0.;
+ }
+ return conversionRatio * cost.getValue();
+ }
+}| 1 | +Consume messages from the incoming-costs stream. |
+
| 2 | +Dispatch returned values to the outgoing-costs stream. |
+
| 3 | +Consume an event with payload of type Cost and produce a double.
+In the case of consuming an arbitrary object, the reactive-messaging-http extension will attempt
+to deserialize the request body as a JSON object. |
+
Let’s define the Cost class:
package org.acme.reactivehttp;
+
+public class Cost {
+ private double value;
+ private String currency;
+
+ public double getValue() {
+ return value;
+ }
+
+ public void setValue(double value) {
+ this.value = value;
+ }
+
+ public String getCurrency() {
+ return currency;
+ }
+
+ public void setCurrency(String currency) {
+ this.currency = currency;
+ }
+}In the next step, we will create configurations for both streams in the application.properties file.
We need to configure the HTTP connector. This is done in the application.properties file.
+The keys are structured as follows:
mp.messaging.[outgoing|incoming].<channel-name>.<property}=value
The channel-name segment must match the value set in the @Incoming and @Outgoing annotation:
incoming-costs → a source that receives costs
outgoing-costs → a sink that receives converted costs
mp.messaging.outgoing.outgoing-costs.connector=quarkus-http
+
+# here we are using a URL pointing to an endpoint
+# you can use e.g. an environment variable to change it
+mp.messaging.outgoing.outgoing-costs.url=http://localhost:${quarkus.http.port}/cost-collector
+
+# we need to use a different port for tests:
+%test.mp.messaging.outgoing.outgoing-costs.url=http://localhost:${quarkus.http.test-port}/cost-collector
+
+# POST is the default method. Another possibility is PUT
+mp.messaging.outgoing.outgoing-costs.method=POST
+
+
+mp.messaging.incoming.incoming-costs.connector=quarkus-http
+
+# the incoming-costs channel will be fed via an endpoint on the `/costs` path
+mp.messaging.incoming.incoming-costs.path=/costs
+
+# POST is the default method. Another possibility is PUT
+mp.messaging.incoming.incoming-costs.method=POSTIn case single channel should deliver message to multiple subscribers (methods annotated with @Incoming)
+then additional property needs to be set
mp.messaging.incoming.incoming-costs.broadcast=trueThis will allow to deliver single message to all subscribers of that channel.
+To illustrate that converting messages and passing them through works, let’s add an endpoint that will +receive the outgoing costs and sum them up. +This is a usual JAX-RS endpoint.
+package org.acme.reactivehttp;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+@Path("/cost-collector")
+@ApplicationScoped
+public class CostCollector {
+
+ private double sum = 0;
+
+ @POST
+ public void consumeCost(String valueAsString) {
+ sum += Double.parseDouble(valueAsString);
+ }
+
+ @GET
+ public double getSum() {
+ return sum;
+ }
+
+}To conveniently interact with the application, let’s create a simple web page.
+The page will provide a form to add costs, and an info of the current sum of costs.
+The page periodically updates the sum by requesting the current sum from /cost-collector.
Create the src/main/resources/META-INF/resources/index.html file, with the following content:
<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Costs</title>
+
+ <link rel="stylesheet" type="text/css"
+ href="https://cdnjs.cloudflare.com/ajax/libs/patternfly/3.24.0/css/patternfly.min.css">
+ <link rel="stylesheet" type="text/css"
+ href="https://cdnjs.cloudflare.com/ajax/libs/patternfly/3.24.0/css/patternfly-additions.min.css">
+</head>
+<body>
+<div class="container">
+
+ <h2>Add a cost</h2>
+ <div>
+ <div>
+ <label for="value">Value</label>
+ <input type="text" id="value">
+ </div>
+ <div>
+ <label for="currency">Currency</label>
+ <select id="currency">
+ <option value="CHF">Swiss franc</option>
+ <option value="USD">United States dollar</option>
+ <option value="CHF">Polish złoty</option>
+ </select>
+ </div>
+ <input type="button" onclick="add()" value="Add">
+ </div>
+
+
+ <h2>Last cost</h2>
+ <div class="row">
+ <p class="col-md-12">The total cost is <strong><span id="content">N/A</span> €</strong>.</p>
+ </div>
+</div>
+</body>
+<script>
+ add = function() {
+ var value = document.getElementById('value').value;
+ var currency = document.getElementById('currency').value;
+
+ var cost = {
+ value: document.getElementById('value').value,
+ currency: document.getElementById('currency').value
+ };
+
+ fetch('costs', { method: 'POST', body: JSON.stringify(cost) });
+ }
+
+ updateCost = function() {
+ fetch('cost-collector').then(response => response.text()).then(sum =>
+ document.getElementById('content').textContent=sum
+ );
+ }
+
+ window.setInterval(updateCost, 500);
+</script>
+</html>Run the application using:
+./mvnw quarkus:devOpen http://localhost:8080/index.html in your browser.
You can build the native executable with:
+./mvnw package -PnativeAll quarkus-http connector options:
# OUTGOING
+
+# The target URL
+mp.messaging.outgoing.<channelName>.url=http://localhost:8213
+
+# Message payload serializer, optional, implementation of `io.quarkus.reactivemessaging.http.runtime.serializers.Serializer`
+mp.messaging.outgoing.<channelName>.serializer=com.example.MySerializer
+
+# The number of attempts to make for sending a request to a remote endpoint. Must not be less than zero
+# Zero by default
+mp.messaging.outgoing.<channelName>.maxRetries=3
+
+# Configures the random factor when using back-off with maxRetries > 0. 0.5 by default
+mp.messaging.outgoing.<channelName>.jitter=0.3
+
+# Configures a back-off delay between attempts to send a request.
+# A random factor (jitter) is applied to increase the delay when several failures happen.
+mp.messaging.outgoing.<channelName>.delay=1s
+
+#The HTTP method (either `POST` or `PUT`), `POST` by default
+mp.messaging.outgoing.<channelName>.method=PUT
+
+#INCOMING
+# The HTTP method (either `POST` or `PUT`, `POST` by default
+mp.messaging.incoming.<channelName>.method=POST
+
+# The path of the endpoint
+mp.messaging.incoming.<channelName>.path=/my-reactive-ws-endpoint
+
+# HTTP endpoint buffers messages if a consumer is not able to keep up. This setting specifies the size of the buffer.
+# 8 by default.
+mp.messaging.incoming.<channelName>.buffer-size=13The HTTP connector supports binary-mode [cloud event] messages through Metadata.
+If incoming HTTP request contains headers of the form ce- or ce_, a CloudEventMetadata instance is included in the Message metadata
If outgoing Message metadata includes a CloudEventMetadata instance, the information contained there will be added as headers prefixed with ce- in the outgoing HTTP request.
This extension utilizes SmallRye Reactive Messaging to build data streaming applications.
+If you want to go further check the documentation of SmallRye Reactive Messaging, the implementation used in Quarkus.
+This guide demonstrates how your Quarkus application can utilize SmallRye Reactive Messaging to
+consume and produce messages via WebSockets.
+WebSockets support is a part of the Reactive Messaging HTTP extension (quarkus-reactive-messaging-http).
To complete this guide, you need:
+less than 15 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+GraalVM, Docker or Podman installed if you want to run in native mode.
+In this guide we will implement a service, namely CostConverter that consumes messages
+with costs in multiple currencies and converts each cost to its value in Euro.
To let a user easily try out the service, we will implement an HTTP resource summing up the costs
+(CostCollector), and a simple web page to add new costs and watch the sum.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the reactive-messaging-websockets-quickstart directory.
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus:quarkus-maven-plugin:3.8.0:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=reactive-messaging-websockets-quickstart \
+ -Dextensions="reactive-messaging-http,resteasy-reactive-jackson" \
+ -DnoCode
+cd reactive-messaging-websockets-quickstartThis command generates a Maven project with Reactive Messaging HTTP connector and RESTEasy Reactive with Jackson support extensions.
+Create the src/main/java/org/acme/reactivews/CostConverter.java file, with the following content:
package org.acme.reactivews;
+
+import org.eclipse.microprofile.reactive.messaging.Incoming;
+import org.eclipse.microprofile.reactive.messaging.Outgoing;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * A bean consuming costs in multiple currencies and producing prices in EUR from them
+ */
+@ApplicationScoped
+public class CostConverter {
+
+ private static final Map<String, Double> conversionRatios = new HashMap<>();
+
+ static {
+ conversionRatios.put("CHF", 0.93);
+ conversionRatios.put("USD", 0.84);
+ conversionRatios.put("PLN", 0.22);
+ conversionRatios.put("EUR", 1.0);
+ }
+
+ @Incoming("incoming-costs") (1)
+ @Outgoing("outgoing-costs") (2)
+ Cost convert(Cost cost) { (3)
+ Double conversionRatio = conversionRatios.get(cost.getCurrency().toUpperCase());
+ if (conversionRatio == null) {
+ return cost;
+ }
+ return new Cost(conversionRatio * cost.getValue(), "EUR");
+ }
+}| 1 | +Consume messages from the incoming-costs stream. |
+
| 2 | +Dispatch returned values to the outgoing-costs stream. |
+
| 3 | +Consume an event with payload of type Cost and produce another Cost, with value converted
+to Euro if we know the conversion ratio.
+In the case of consuming an arbitrary object, the reactive-messaging-http extension will attempt
+to deserialize the request body as a JSON object. |
+
| + + | ++Unlike the outbound HTTP connector, the outbound WebSocket connector does not check if the message is +consumed by the remote endpoint. It may happen that a failure to receive a message is not reported, +e.g. if the remote side closes the WebSocket connection in a crucial moment. + | +
Let’s define the Cost class:
package org.acme.reactivews;
+
+public class Cost {
+ private double value;
+ private String currency;
+
+ public Cost(double value, String currency) {
+ this.value = value;
+ this.currency = currency;
+ }
+
+ public Cost() {
+ }
+
+ public void setValue(double value) {
+ this.value = value;
+ }
+
+ public void setCurrency(String currency) {
+ this.currency = currency;
+ }
+
+ public double getValue() {
+ return value;
+ }
+
+ public String getCurrency() {
+ return currency;
+ }
+}In the next step, we will create configurations for both streams in the application.properties file.
We need to configure the Web Socket connector. This is done in the application.properties file.
+The keys are structured as follows:
mp.messaging.[outgoing|incoming].{channel-name}.{property}=value
The channel-name segment must match the value set in the @Incoming and @Outgoing annotation:
incoming-costs → an inbound WebSocket that receives costs
outgoing-costs → an outbound WebSocket that pushes converted costs
mp.messaging.outgoing.outgoing-costs.connector=quarkus-websocket
+
+# the WebSockets are exposed on the same port as HTTP
+# for non-test profiles, it is quarkus.http.port...
+mp.messaging.outgoing.outgoing-costs.url=ws://localhost:${quarkus.http.port}/cost-collector
+
+# for the test profile it is quarkus.http.test-port
+%test.mp.messaging.outgoing.outgoing-costs.url=ws://localhost:${quarkus.http.test-port}/cost-collector
+
+
+mp.messaging.incoming.incoming-costs.connector=quarkus-websocket
+# the incoming-costs channel will be fed via a Web Socket endpoint on the `/costs` path
+mp.messaging.incoming.incoming-costs.path=/costs
+
+mp.messaging.incoming.collector.path=/cost-collector
+mp.messaging.incoming.collector.connector=quarkus-websocketTo illustrate that converting messages and passing them through works, let’s add a CostCollector class that consumes the Web Socket messages and exposes information about the sum of collected costs via REST:
package org.acme.reactivews;
+
+import org.eclipse.microprofile.reactive.messaging.Incoming;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+
+@Path("/collected-costs")
+@ApplicationScoped
+public class CostCollector {
+ private double sum;
+
+ @GET
+ // expose the sum of the collected costs
+ public synchronized double getCosts() {
+ return sum;
+ }
+
+ @Incoming("collector")
+ // consume costs from collector channel
+ synchronized void collect(Cost cost) {
+ if ("EUR".equals(cost.getCurrency())) {
+ sum += cost.getValue();
+ }
+ }
+}One more thing we have to do is to configure the collector channel in application.properties:
mp.messaging.incoming.collector.path=/cost-collector
+mp.messaging.incoming.collector.connector=quarkus-websocketTo conveniently interact with the application, let’s create a simple web page.
+The page will provide a form to add costs, and an info of the current sum of costs.
+The page periodically updates the sum by requesting the current sum from /cost-collector.
Change the src/main/resources/META-INF/resources/index.html file, with the following content:
<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Costs</title>
+
+ <link rel="stylesheet" type="text/css"
+ href="https://cdnjs.cloudflare.com/ajax/libs/patternfly/3.24.0/css/patternfly.min.css">
+ <link rel="stylesheet" type="text/css"
+ href="https://cdnjs.cloudflare.com/ajax/libs/patternfly/3.24.0/css/patternfly-additions.min.css">
+</head>
+<body>
+<div class="container">
+
+ <h2>Add a cost</h2>
+ <div>
+ <div>
+ <label for="value">Value</label>
+ <input type="text" id="value">
+ </div>
+ <div>
+ <label for="currency">Currency</label>
+ <select id="currency">
+ <option value="CHF">Swiss franc</option>
+ <option value="USD">United States dollar</option>
+ <option value="PLN">Polish złoty</option>
+ <option value="EUR">Euro</option>
+ </select>
+ </div>
+ <input type="button" onclick="add()" value="Add">
+ </div>
+
+
+ <h2>Summary</h2>
+ <div class="row">
+ <p class="col-md-12">The total cost is <strong><span id="content">N/A</span> €</strong>.</p>
+ </div>
+</div>
+</body>
+<script>
+ var webSocket = new WebSocket(`ws://${document.location.host}/costs`);
+ add = function() {
+ const cost = {
+ value: document.getElementById('value').value,
+ currency: document.getElementById('currency').value
+ };
+
+ webSocket.send(JSON.stringify(cost));
+ }
+
+ updateCost = function() {
+ fetch('collected-costs').then(response => response.text()).then(sum =>
+ document.getElementById('content').textContent=sum
+ );
+ }
+
+ window.setInterval(updateCost, 500);
+</script>
+</html>Run the application using:
+./mvnw quarkus:devOpen http://localhost:8080/index.html in your browser.
You can build the native executable with:
+./mvnw package -PnativeAll quarkus-websocket connector options:
# OUTGOING
+
+# The target URL
+mp.messaging.outgoing.<channelName>.url=ws://localhost:8234/
+
+# Message serializer, optional, implementation of `io.quarkus.reactivemessaging.http.runtime.serializers.Serializer`
+mp.messaging.outgoing.<channelName>.serializer=com.example.MySerializer
+
+# The number of retries to make for sending a message to a remote websocket endpoint.
+# A value greater than 0 is advised. Otherwise, a web socket timeout can result in a dropped message
+# The default value is 1
+mp.messaging.outgoing.<channelName>.maxRetries=1
+
+# Configures the random factor when using back-off with maxAttempts > 1, 0.5 by default
+mp.messaging.outgoing.<channelName>.jitter=0.7
+
+# Configures a back-off delay between attempts to send a request.
+# A random factor (jitter) is applied to increase the delay when several failures happen.
+mp.messaging.outgoing.<channelName>.delay=2s
+
+
+# INCOMING
+
+# The path of the endpoint
+mp.messaging.incoming.<channelName>.path=/my-ws-endpoint
+
+# Web socket endpoint buffers messages if a consumer is not able to keep up.
+# This setting specifies the size of the buffer. 8 by default
+mp.messaging.incoming.<channelName>.buffer-size=3This extension utilizes SmallRye Reactive Messaging to build data streaming applications.
+If you want to go further check the documentation of SmallRye Reactive Messaging, the implementation used in Quarkus.
+This extension allow usage of NATS JetStream inside a Quarkus App, in JVM and Native mode.
+The extension implements a new connector type quarkus-jetstream in SmallRye Reactive Messaging that will use the NATS client.
+If you want to use this extension, you need to add the io.quarkiverse.reactivemessaging.nats-jetstream:quarkus-reactive-messsaging-nats-jetstream extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.reactivemessaging.nats-jetstream</groupId>
+ <artifactId>quarkus-reactive-messsaging-nats-jetstream</artifactId>
+ <version>1.4.0</version>
+</dependency>Then configure your application by adding the NATS JetStream connector type:
+# Inbound +mp.messaging.incoming.[channel-name].connector=quarkus-jetstream + +# Outbound +mp.messaging.outgoing.[channel-name].connector=quarkus-jetstream+
Let’s imagine you have a NATS JetStream broker running, and accessible using the localhost:4242 address. Configure your application to receive NATS messages on the data channel from the stream named: test and the subject named: data as follows:
+quarkus.reactive-messaging.nats.servers=nats://localhost:4242 +quarkus.reactive-messaging.nats.username=guest +quarkus.reactive-messaging.nats.password=guest +quarkus.reactive-messaging.nats.ssl-enabled=false + +# Streams and subjects are auto-created by default based on channel configuration +quarkus.reactive-messaging.nats.jet-stream.auto-configure=true + +mp.messaging.incoming.data.connector=quarkus-jetstream +mp.messaging.incoming.data.stream=test +mp.messaging.incoming.data.subject=data+
Then, your application receives Message<Data>. You can consumes the payload directly:
+package inbound;
+
+import org.eclipse.microprofile.reactive.messaging.Incoming;
+
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class DataConsumer {
+
+ @Incoming("data")
+ public void consume(Data data) {
+ // process your data.
+ }
+
+}
+If you want more examples, please take a look at the tests of the extension.
+quarkus.reactive-messaging.nats.servers |
+A comma-separated list of URI’s nats://{host}:{port} to use for establishing the initial connection to the NATS cluster. |
+
quarkus.reactive-messaging.nats.username |
+The username to connect to the NATS server |
+
quarkus.reactive-messaging.nats.password |
+The password to connect to the NATS server |
+
quarkus.reactive-messaging.nats.ssl-enabled |
+Whether to enable SSL/TLS secure connections to the NATS server |
+
quarkus.reactive-messaging.nats.max-reconnects |
+The maximum number of reconnect attempts |
+
quarkus.reactive-messaging.nats.connection-timeout |
+The connection timeout in milliseconds |
+
quarkus.reactive-messaging.nats.error-listener |
+The classname for the error listener |
+
quarkus.reactive-messaging.nats.buffer-size |
+The size in bytes to make buffers for connections |
+
quarkus.reactive-messaging.nats.jet-stream.auto-configure |
+Autoconfigure stream and subjects based on channel configuration |
+
quarkus.reactive-messaging.nats.jet-stream.replicas |
+The number of replicas a message must be stored. Default value is 1 |
+
quarkus.reactive-messaging.nats.jet-stream.storage-type |
+The storage type for stream data (File or Memory) |
+
quarkus.reactive-messaging.nats.jet-stream.retention-policy |
+Declares the retention policy for the stream (Limits or Interest) |
+
mp.messaging.outgoing.[channel-name].stream |
+The stream to subscribe messages to |
+
mp.messaging.outgoing.[channel-name].subject |
+The subject to subscribe messages to |
+
mp.messaging.outgoing.[channel-name].trace-enabled |
+Enable traces for subscriber |
+
mp.messaging.outgoing.[channel-name].auto-configure |
+Auto configure subject on NATS |
+
mp.messaging.incoming.[channel-name].stream |
+The stream to publish messages from |
+
mp.messaging.incoming.[channel-name].subject |
+The subject to publish messages from |
+
mp.messaging.incoming.[channel-name].trace-enabled |
+Enable traces for publisher |
+
mp.messaging.incoming.[channel-name].auto-configure |
+Auto configure subject on NATS |
+
mp.messaging.incoming.[channel-name].ordered |
+Flag indicating whether this subscription should be ordered |
+
mp.messaging.incoming.[channel-name].deliver-group |
+The optional deliver group to join |
+
mp.messaging.incoming.[channel-name].durable |
+Sets the durable name for the consumer |
+
mp.messaging.incoming.[channel-name].max-deliver |
+The maximum number of times a specific message delivery will be attempted |
+
mp.messaging.incoming.[channel-name].back-off |
+The timing of re-deliveries as a comma-separated list of durations |
+
mp.messaging.incoming.[channel-name].payload-type |
+The class name of the payload type |
+
mp.messaging.incoming.[channel-name].pull |
+The subscription type |
+
mp.messaging.incoming.[channel-name].pull.batch-size |
+The size of batch of messages to be pulled in pull mode |
+
mp.messaging.incoming.[channel-name].pull.repull-at |
+The point in the current batch to tell the server to start the next batch |
+
mp.messaging.incoming.[channel-name].pull.poll-timeout |
+The poll timeout in milliseconds |
+
use 0 to wait indefinitely |
+mp.messaging.incoming.[channel-name].retry-backoff |
+
The retry backoff in milliseconds for retry publishing messages |
+mp.messaging.incoming.[channel-name].exponential-backoff |
+
calculation a exponential backoff using deliveredCount metadata (NB back-off must undefined to work properly) |
+mp.messaging.incoming.[channel-name].exponential-backoff-max-duration |
+
This extension utilizes the NATS JetStream client to connect to a NATS JetStream broker.
+This extension utilizes SmallRye Reactive Messaging to build data streaming applications.
+If you want to go further check the documentation of SmallRye Reactive Messaging, the implementation used in Quarkus.
+
Web Framework
+Renarde is a server-side Web Framework based on Quarkus, Qute,
+Hibernate and RESTEasy Reactive.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde</artifactId>
+ <version>1.0.5</version>
+</dependency>Let’s see how you can quickly build a Web Application with Renarde. Let’s start with a Controller:
+package rest;
+
+import javax.ws.rs.Path;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+}A Controller is the logic class that binds URIs to actions and views. They are almost like regular
+JAX-RS endpoints,
+but you opt-in to special magic by extending the Controller class, which gives you nice methods,
+but also super friendly behaviour.
In this Controller we declare a Qute template, and map the / to it.
We can then define the main page in src/main/resources/templates/Application/index.html:
<!DOCTYPE html>
+<html lang="en">
+ <body>
+ Hello, World!
+ </body>
+</html>Now if you navigate to your application at http://localhost:8080 you will see Hello, World! rendered.
By convention, you can place your model classes in the model package, but anywhere else works just as well. We
+recommend using Hibernate ORM with Panache. Here’s an example entity for our sample Todo application:
package model;
+
+import java.util.Date;
+import java.util.List;
+
+import javax.persistence.Entity;
+import javax.persistence.ManyToOne;
+
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+public class Todo extends PanacheEntity {
+
+ @ManyToOne
+ public User owner;
+
+ public String task;
+
+ public boolean done;
+
+ public Date doneDate;
+
+ public static List<Todo> findByOwner(User user) {
+ return find("owner = ?1 ORDER BY id", user).list();
+ }
+}By convention, you can place your controllers in the rest package, but anywhere else works just as well. You
+have to extend the Controller class in order to benefit from extra easy endpoint declarations and reverse-routing,
+but that superclass also gives you useful methods. We usually have one controller per model class, so we tend to use
+the plural entity name for the corresponding controller:
package rest;
+
+import java.util.Date;
+import java.util.List;
+
+import javax.validation.constraints.NotBlank;
+import javax.ws.rs.POST;
+
+import org.jboss.resteasy.reactive.RestForm;
+import org.jboss.resteasy.reactive.RestPath;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import model.Todo;
+
+public class Todos extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index(List<Todo> todos);
+ }
+
+ public TemplateInstance index() {
+ // list every todo
+ List<Todo> todos = Todo.listAll();
+ // render the index template
+ return Templates.index(todos);
+ }
+
+ @POST
+ public void delete(@RestPath Long id) {
+ // find the Todo
+ Todo todo = Todo.findById(id);
+ notFoundIfNull(todo);
+ // delete it
+ todo.delete();
+ // send loving message
+ flash("message", "Task deleted");
+ // redirect to index page
+ index();
+ }
+
+ @POST
+ public void done(@RestPath Long id) {
+ // find the Todo
+ Todo todo = Todo.findById(id);
+ notFoundIfNull(todo);
+ // switch its done state
+ todo.done = !todo.done;
+ if(todo.done)
+ todo.doneDate = new Date();
+ // send loving message
+ flash("message", "Task updated");
+ // redirect to index page
+ index();
+ }
+
+ @POST
+ public void add(@NotBlank @RestForm String task) {
+ // check if there are validation issues
+ if(validationFailed()) {
+ // go back to the index page
+ index();
+ }
+ // create a new Todo
+ Todo todo = new Todo();
+ todo.task = task;
+ todo.persist();
+ // send loving message
+ flash("message", "Task added");
+ // redirect to index page
+ index();
+ }
+}Every public method is a valid endpoint. If it has no HTTP method annotation (@GET, @HEAD, @POST, @PUT, @DELETE) then
+it is assumed to be a @GET method.
Most @GET methods will typically return a TemplateInstance for rendering an HTML server-side template, and should not
+modify application state.
Controller methods annotated with @POST, @PUT and @DELETE will typically return void and trigger a redirect to a @GET
+method after they do their action. This is not mandatory, you can also return a TemplateInstance if you want, but it is good form
+to use a redirect to avoid involuntary actions when browsers reload the page. Those methods also get an implicit @Transactional
+annotation so you don’t need to add it.
If your controller is not annotated with @Path it will default to a path using the class name. If your controller method is not
+annotated with @Path it will default to a path using the method name. The exception is if you have a @Path annotation on the
+method with an absolute path, in which case the class path part will be ignored. Here’s a list of example annotations and how they
+result:
| Class declaration | +Method declaration | +URI | +
|---|---|---|
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
Furthermore, if you specify path parameters that are not present in your path annotations, they will be automatically +appended to your path:
+public class Orders extends Controller {
+
+ // The URI will be Orders/get/{owner}/{id}
+ public TemplateInstance get(@RestPath String owner, @RestPath Long id) {
+ }
+
+ // The URI will be /orders/{owner}/{id}
+ @Path("/orders")
+ public TemplateInstance otherGet(@RestPath String owner, @RestPath Long id) {
+ }
+}You can place your Qute views in the src/main/resources/templates folder,
+using the {className}/{methodName}.html naming convention.
Every controller that has views should declare them with a nested static class annotated with @CheckedTemplate:
public class Todos extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index(List<Todo> todos);
+ }
+
+ public TemplateInstance index() {
+ // list every todo
+ List<Todo> todos = Todo.listAll();
+ // render the index template
+ return Templates.index(todos);
+ }
+}Here we’re declaring the Todos/index.html template, specifying that it takes a todos parameter of type
+List<Todo> which allows us to validate the template at build-time.
Templates are written in Qute, and you can also declare imported templates in order to validate them using a
+toplevel class, such as the main.html template:
package rest;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+
+@CheckedTemplate
+public class Templates {
+ public static native TemplateInstance main();
+}Typical web applications will have a main template for their layout and use composition in every method. For example, we
+can declare the following main template in main.html:
<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <title>{#insert title /}</title>
+ <meta charset="UTF-8">
+ <link rel="stylesheet" media="screen" href="/stylesheets/main.css">
+ {#insert moreStyles /}
+ <script src="/javascripts/main.js" type="text/javascript" charset="UTF-8"></script>
+ {#insert moreScripts /}
+ </head>
+ <body>
+ {#insert /}
+ </body>
+</html>And then use it in our Todos/index.html template to list the todo items:
{#include main.html }
+{#title}Todos{/title}
+
+<table class="table">
+ <thead>
+ <tr>
+ <th>#</th>
+ <th>Task</th>
+ </tr>
+ </thead>
+ <tbody>
+ {#for todo in todos}
+ <tr>
+ <th>{todo.id}</th>
+ <td>{todo.task}</td>
+ </tr>
+ {/for}
+ </tbody>
+</table>
+
+{/include}| Tag | +Description | +
|---|---|
| + | Iterate over collections |
+
| + | Conditional statement |
+
| + | Switch statement |
+
| + | Adds value members to the local scope |
+
| + | Declare local variables |
+
| + | Template composition |
+
If you want to declare additional tags in order to be able to repeat them in your templates, simply place them in the
+templates/tags folder. For example, here is our user.html tag:
<span class="user-link" title="{it.userName}">
+{#if img??}
+{#gravatar it.email size=size.or(20) default='mm' /}
+{/if}
+{it.userName}</span>Which allows us to use it in every template:
+{#if inject:user}
+ {#if inject:user.isAdmin}<span class="bi-star-fill" title="You are an administrator"></span>{/if}
+ {#user inject:user img=true size=20/}
+{/if}You can pass parameters to your template with name=value pairs, and the first unnamed parameter value becomes available
+as the it parameter.
See the Qute documentation for more information.
+Renarde comes with a few extra tags to make your life easier:
+| Tag | +Description | +
|---|---|
|
+Generate a hidden HTML form element containing a CRSF token to be matched in the next request. |
+
|
+Inserts the error message for the given field name |
+
|
+Generates an HTML form for the given |
+
|
+Inserts a gravatar image for the given |
+
|
+Conditional statement executed if there is an error for the given field |
+
If you need additional methods to be registered to be used on your template expressions, you can declare static methods in
+a class annotated with @TemplateExtension:
package util;
+
+import java.util.Calendar;
+import java.util.Date;
+import java.util.GregorianCalendar;
+
+import io.quarkus.qute.TemplateExtension;
+
+@TemplateExtension
+public class JavaExtensions {
+
+ public static boolean isRecent(Date date){
+ Date now = new Date();
+ Calendar cal = new GregorianCalendar();
+ cal.add(Calendar.MONTH, -6);
+ Date sixMonthsAgo = cal.getTime();
+ return date.before(now) && date.after(sixMonthsAgo);
+ }
+
+}This one declares an additional method on the Date type, allowing you to test whether a date is recent or not:
{#if todo.done && todo.doneDate.isRecent()}
+ This was done recently!
+{/if}| Target type | +Method | +Description | +
|---|---|---|
|
+
|
+Formats the date to the |
+
|
+
|
+Formats the date to the |
+
|
+
|
+Returns |
+
|
+
|
+Formats the date in terms of |
+
|
+
|
+Returns an MD5 hash of the given string |
+
|
+
|
+Returns true if the given object is exactly of the specified class name |
+
You can use webjars to provide third-party JavaScript or CSS. For example, here is how you can import Bootstrap
+and Bootstrap-icons in your pom.xml:
<dependency>
+ <groupId>org.webjars</groupId>
+ <artifactId>bootstrap</artifactId>
+ <version>5.1.3</version>
+</dependency>
+<dependency>
+ <groupId>org.webjars.npm</groupId>
+ <artifactId>bootstrap-icons</artifactId>
+ <version>1.7.0</version>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-webjars-locator</artifactId>
+</dependency>After that, you can include them in your Qute templates with:
+<head>
+ <link rel="stylesheet" media="screen" href="/webjars/bootstrap/css/bootstrap.min.css">
+ <link rel="stylesheet" media="screen" href="/webjars/bootstrap-icons/font/bootstrap-icons.css">
+ <script src="/webjars/bootstrap/js/bootstrap.min.js" type="text/javascript" charset="UTF-8"></script>
+</head>Look at https://mvnrepository.com/artifact/org.webjars for the list of available options.
+A lot of the time, you need to send data from the browser to your endpoints, which is often done with forms.
+Creating forms in Renarde is easy: let’s see an example of how to do it in Qute:
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName"/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName"/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}Here we’re defining a form whose action will go to Register.complete(newUser.confirmationCode) and
+which contains several form elements, which are just tags to make composition easier. For example formElement is
+a custom Qute tag for Bootstrap which defines layout for the form element and displays any associated error:
<div class="mb-3">
+ <label class="form-label" for="{name}">{label}</label>
+ {nested-content}
+ {#ifError name}
+ <span class="invalid-feedback">{#error name/}</span>
+ {/ifError}
+</div>The input user tag is also designed for Bootstrap as an abstraction:
<input name="{name}"
+ type="{type ?: 'text'}"
+ placeholder="{placeholder ?: ''}"
+ class="form-control {#ifError name}is-invalid{/ifError}"
+ maxlength="{global:VARCHAR_SIZE}"
+ value="{inject:flash.get(name)}"/>As you can see, we have default values for certain attributes, a special error class if there is a validation +error, and we default the value to the one preserved in the flash scope, which is filled whenever validation +fails, so that the user can see the validation error without losing their form values.
+As for the form Renarde tag, it is also fairly simple, and only includes an authenticity token for CRSF protection.
<form action="{it}" method="{method ?: 'POST'}" class="{klass ?: ''}">
+ {#authenticityToken/}
+ {nested-content}
+</form>Most forms will be a @POST endpoint, with each form element having a corresponding parameter annotated with @RestForm.
@POST
+public void complete(@RestQuery String confirmationCode,
+ @RestForm String userName,
+ @RestForm String password,
+ @RestForm String password2,
+ @RestForm String firstName,
+ @RestForm String lastName) {
+ // do something with the form parameters
+}You can also group parameters in a POJO, but for now you have to add a special
+@Consumes(MediaType.MULTIPART_FORM_DATA) annotation:
@Consumes(MediaType.MULTIPART_FORM_DATA)
+@POST
+public void complete(@RestQuery String confirmationCode,
+ FormData form) {
+ // do something with the form parameters
+}
+
+public static class FormData {
+ @RestForm String userName;
+ @RestForm String password;
+ @RestForm String password2;
+ @RestForm String firstName;
+ @RestForm String lastName;
+}Check out the RESTEasy Reactive documentation +for more information about form parameters and multi-part.
+You can place your usual Hibernate Validation annotations on the controller methods that receive user data, but +keep in mind that you have to check for validation errors in your method before you do any action that modifies your state. +This allows you to check more things than you can do with just annotations, with richer logic:
+@POST
+public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String userName,
+ @RestForm @NotBlank @Length(min = 8, max = Util.VARCHAR_SIZE) String password,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String password2,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String firstName,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String lastName) {
+ // Find the user for this confirmation code
+ User user = User.findForContirmation(confirmationCode);
+ if(user == null){
+ validation.addError("confirmationCode", "Invalid confirmation code");
+ }
+
+ // Make sure the passwords match
+ validation.equals("password", password, password2);
+
+ // Make sure the username is free
+ if(User.findByUserName(userName) != null){
+ validation.addError("userName", "User name already taken");
+ }
+
+ // If validation failed, redirect to the confirm page
+ if(validationFailed()){
+ confirm(confirmationCode);
+ }
+
+ // Now proceed to complete user registration
+ ...
+}You can use the validation object to trigger additional validation logic and collect errors.
Those errors are then placed in the flash scope by a call to validationFailed() if there
+are any errors, and thus preserved when you redirect from your action method to the @GET method
+that holds the submitted form, which you can then access in your views using the {#ifError field}{/ifError}
+conditional tag, or the {#error field/} tag which accesses the error message for the given field.
We have seen how to declare endpoints and how URIs map to them, but very often we need to map from endpoints to +URIs, which Renarde makes easy.
+When handling a @POST, @PUT or @DELETE endpoint, it’s good form to redirect to a @GET endpoint after
+the action has been done, in order to allow the user to reload the page without triggering the action a second
+time, and such redirects are simply done by calling the corresponding @GET endpoint. In reality, the endpoint
+will not be called and will be replaced by a redirect that points to the endpoint in question.
package rest;
+
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the index page
+ index();
+ }
+}If there are any parameters that form the URI, you must pass them along:
+package rest;
+
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+
+import org.jboss.resteasy.reactive.RestPath;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+
+ public TemplateInstance somePage(@RestPath String id, @RestQuery String q) {
+ // do something with the id and q
+ return Templates.index();
+ }
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the somePage page
+ somePage("foo", "bar");
+ }
+}If you want to redirect to another controller, you can use the redirect(Class) method:
package rest;
+
+import javax.ws.rs.POST;
+
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the Todos.index() endpoint
+ redirect(Todos.class).index();
+ }
+}If you don’t want a redirect but need a URI to a given endpoint, you can use the Router.getURI
+or Router.getAbsoluteURI methods, by
+passing them a method reference to the endpoint you want and the required parameters:
package rest;
+
+import java.net.URI;
+
+import org.jboss.resteasy.reactive.RestPath;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+import io.quarkiverse.renarde.router.Router;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance somePage();
+ public static native TemplateInstance otherPage(URI uri);
+ }
+
+ public TemplateInstance somePage(@RestPath String foo, @RestQuery Long bar) {
+ return Templates.somePage();
+ }
+
+ public TemplateInstance otherPage() {
+ // Obtain a URI to somePage
+ URI uri = Router.getURI(Login::somePage, "something", 23l);
+ // pass it on to our view
+ return Templates.otherPage(uri);
+ }
+}| + + | +
+If you plan on using Response.seeOther or Controller.seeOther, make sure to use the Router.getAbsoluteURI
+variant, especially if you use the quarkus.http.root-path configuration, otherwise your URIs contain that prefix twice.
+ |
+
If you want a URI to an endpoint in a Qute view, you can use the uri and uriabs namespace with a
+call to the endpoint you want to point to:
<a class="navbar-brand" href="{uri:Application.index()}">Todo</a>Naturally, you can also pass any required parameters.
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-mailer</artifactId>
+</dependency>Often you will need your actions to send email notifications. You can use Qute for this too, by declaring your
+emails in an Emails class:
package email;
+
+import io.quarkus.mailer.MailTemplate.MailTemplateInstance;
+import io.quarkus.qute.CheckedTemplate;
+import model.User;
+
+public class Emails {
+
+ private static final String FROM = "Todos <todos@example.com>";
+ private static final String SUBJECT_PREFIX = "[Todos] ";
+
+ @CheckedTemplate
+ static class Templates {
+ public static native MailTemplateInstance confirm(User user);
+ }
+
+ public static void confirm(User user) {
+ Templates.confirm(user)
+ .subject(SUBJECT_PREFIX + "Please confirm your email address")
+ .to(user.email)
+ .from(FROM)
+ .send().await().indefinitely();
+ }
+}You can then send the email from your endpoint by calling Emails.confirm(user).
You can use composition for emails too, by having a pair of base templates for HTML in
+src/main/resources/templates/email.html:
<!DOCTYPE html>
+
+<html>
+ <head>
+ <meta charset="UTF-8">
+ </head>
+ <body>
+ {#insert /}
+ <p>
+ This is an automated email, you should not reply to it: your mail will be ignored.
+ </p>
+ </body>
+</html>And for text in src/main/resources/templates/email.txt:
{#insert /}
+
+This is an automated email, you should not reply to it: your mail will be ignored.You can then use those templates in your emails in src/main/resources/templates/Emails/confirm.html:
{#include email.html }
+
+<p>
+ Welcome to Todos.
+</p>
+
+<p>
+ You received this email because someone (hopefully you) wants to register on Todos.
+</p>
+
+<p>
+ If you don't want to register, you can safely ignore this email.
+</p>
+
+<p>
+ If you want to register, <a href="{uriabs:Login.confirm(user.confirmationCode)}">complete your registration</a>.
+</p>
+{/include}And for text in src/main/resources/templates/Emails/confirm.txt:
{#include email.txt}
+
+Welcome to Todos.
+
+You received this email because someone (hopefully you) wants to register on Todos.
+
+If you don't want to register, you can safely ignore this email.
+
+If you want to register, complete your registration by going to the following address:
+
+{uriabs:Login.confirm(user.confirmationCode)}
+{/include}Note that in emails you will want to use the uriabs namespace for absolute URIs and not relative ones,
+otherwise the links won’t work for your email recipients.
You can find more information in the Quarkus mailer documentation.
+You can declare your default language and supported languages in src/main/resources/application.properties:
# This is the default locale for your application
+quarkus.default-locale=en
+# These are the supported locales (should include the default locale, but order is not important)
+quarkus.locales=en,frNext, you can declare your default language messages in the src/main/resources/message.properties file:
# A simple message
+hello=Hello World
+# A parameterised message for your view
+views_Application_index_greet=Hello %sDeclare your other language translations in the src/main/resources/message_fr.properties file:
hello=Bonjour Monde
+views_Application_index_greet=Salut %sNow you can use these translated messages in your controller:
+public static class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance index(String name);
+ }
+
+ public TemplateInstance index() {
+ return Templates.index("Stef");
+ }
+
+ public String hello() {
+ return i18n.formatMessage("hello");
+ }
+}Or in your template:
+With no parameter:
+{m:hello}
+With parameters:
+{m:views_Application_index_greet(name)}The current language for a request will depend on the following (in order):
+The _renarde_language cookie, if set
The Accept-Language HTTP header, if set,
+which defines an ordered list of languages by user preference. We will select a best matching language from the set
+of quarkus.locales.
If nothing else, we default to the default language as set by quarkus.default-locale, which defaults to en_US.
You can override the user’s language with a cookie by calling i18n.set(language):
public static class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ public void index() {
+ return Templates.index();
+ }
+
+ @POST
+ public void french() {
+ i18n.set("fr");
+ index();
+ }
+
+ @POST
+ public void english() {
+ i18n.set("en");
+ index();
+ }
+}If you need to pass values from one endpoint to another request after a redirect, you can use the Flash scope.
+Usually this is done in a @POST endpoint, by filling the Flash scope with either errors or messages,
+before trigerring a redirect to the right @GET endpoint.
You can push values in the Flash scope in an endpoint using the flash(name, value) method, or using the
+Flash injectable component.
You can read values from the Flash scope in your Qute views using the {flash:name} namespace.
The Flash scope only lasts from one request to the next and is cleared at each request.
+ Web Framework Security guideRenarde can help you deal with security and user registration, either manually, using OIDC, or
+a mix of both.
In order to handle your own authentication by storing users in your database, you can use JWT tokens.
+Start with importing the renarde-security module:
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-security</artifactId>
+ <version>1.0.5</version>
+</dependency>And set those configuration values:
+# Must be set to get proper error reporting
+quarkus.http.auth.proactive=falseYour entity should extend RenardeUser and can look like this:
package model;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.EnumType;
+import javax.persistence.Enumerated;
+import javax.persistence.Table;
+
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+@Table(name = "user_table")
+public class User extends PanacheEntity implements RenardeUser {
+
+ @Column(nullable = false)
+ public String email;
+ @Column(unique = true)
+ public String userName;
+ public String password;
+ public String firstName;
+ public String lastName;
+ public boolean isAdmin;
+
+ @Column(unique = true)
+ public String confirmationCode;
+
+ @Column(nullable = false)
+ @Enumerated(EnumType.STRING)
+ public UserStatus status;
+
+ public boolean isRegistered(){
+ return status == UserStatus.REGISTERED;
+ }
+
+ @Override
+ public Set<String> getRoles() {
+ Set<String> roles = new HashSet<>();
+ if(isAdmin) {
+ roles.add("admin");
+ }
+ return roles;
+ }
+
+ @Override
+ public String getUserId() {
+ return userName;
+ }
+
+ //
+ // Helpers
+
+ public static User findUnconfirmedByEmail(String email) {
+ return find("LOWER(email) = ?1 AND status = ?2", email.toLowerCase(), UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+
+ public static User findRegisteredByUserName(String username) {
+ return find("LOWER(userName) = ?1 AND status = ?2", username.toLowerCase(), UserStatus.REGISTERED).firstResult();
+ }
+
+ public static User findByUserName(String username) {
+ return find("LOWER(userName) = ?1", username.toLowerCase()).firstResult();
+ }
+
+ public static User findForContirmation(String confirmationCode) {
+ return find("confirmationCode = ?1 AND status = ?2", confirmationCode, UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+}Now tell Renarde how to map the JWT cookies to your user model by implementing RenardeUserProvider:
package util;
+
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkiverse.renarde.security.RenardeUserProvider;
+import model.User;
+
+@ApplicationScoped
+public class MySecuritySetup implements RenardeUserProvider {
+
+ @Inject
+ RenardeSecurity security;
+
+ @Override
+ public RenardeUser findUser(String tenantId, String id) {
+ return User.findByUserName(id);
+ }
+}With this, Renarde will make sure that we produce a user named bean containing the current user if there is a
+logged-in user. You can then use it in your views with inject:user or by injecting it in
+your endpoints.
Renarde also provides a ControllerWithUser class which you can extend to access the current user for all controllers
+that need a user.
Now you can write your login and registration page like this:
+{#include main.html }
+{#title}Login{/title}
+
+<div class="row">
+ <div class="col-md-5">
+ {#form uri:Login.manualLogin()}
+ <fieldset>
+ <legend>Login</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName"/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Login</button>
+ </fieldset>
+ {/form}
+ </div>
+ <div class="col-md-5">
+ {#form uri:Login.register()}
+ <fieldset>
+ <legend>Register</legend>
+ {#formElement name="email" label="Email"}
+ {#input name="email"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Register</button>
+ </fieldset>
+ {/form}
+ </div>
+</div>
+
+{/include}As for your registration page, it can look like this:
+{#include main.html }
+{#title}Complete registration{/title}
+
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName" value=newUser.userName/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName" value=newUser.firstName/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName" value=newUser.lastName/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}
+{/include}And your login and registration endpoint can look like this to handle user registration and login:
+package rest;
+
+import java.util.UUID;
+
+import javax.inject.Inject;
+import javax.validation.constraints.Email;
+import javax.validation.constraints.NotBlank;
+import javax.ws.rs.POST;
+import javax.ws.rs.core.NewCookie;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.ResponseBuilder;
+
+import org.hibernate.validator.constraints.Length;
+import org.jboss.resteasy.reactive.RestForm;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import email.Emails;
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.router.Router;
+import io.quarkiverse.renarde.util.StringUtils;
+import io.quarkus.elytron.security.common.BcryptUtil;
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkus.security.Authenticated;
+import model.User;
+import model.UserStatus;
+
+public class Login extends ControllerWithUser<User> {
+
+ @Inject
+ RenardeSecurity security;
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance login();
+ public static native TemplateInstance register(String email);
+ public static native TemplateInstance confirm(User newUser);
+ public static native TemplateInstance logoutFirst();
+ public static native TemplateInstance welcome();
+ }
+
+ /**
+ * Login page
+ */
+ public TemplateInstance login() {
+ return Templates.login();
+ }
+
+ /**
+ * Welcome page at the end of registration
+ */
+ @Authenticated
+ public TemplateInstance welcome() {
+ return Templates.welcome();
+ }
+
+ /**
+ * Manual login form
+ */
+ @POST
+ public Response manualLogin(@NotBlank @RestForm String userName,
+ @NotBlank @RestForm String password) {
+ if(validationFailed()) {
+ login();
+ }
+ User user = User.findRegisteredByUserName(userName);
+ if(user == null
+ || !BcryptUtil.matches(password, user.password)) {
+ validation.addError("userName", "Invalid username/pasword");
+ prepareForErrorRedirect();
+ login();
+ }
+ NewCookie cookie = security.makeUserCookie(user);
+ return Response.seeOther(Router.getURI(Application::index)).cookie(cookie).build();
+ }
+
+
+ /**
+ * Manual registration form, sends confirmation email
+ */
+ @POST
+ public TemplateInstance register(@RestForm @NotBlank @Email String email) {
+ if(validationFailed())
+ login();
+ User newUser = User.findUnconfirmedByEmail(email);
+ if(newUser == null) {
+ newUser = new User();
+ newUser.email = email;
+ newUser.status = UserStatus.CONFIRMATION_REQUIRED;
+ newUser.confirmationCode = UUID.randomUUID().toString();
+ newUser.persist();
+ }
+ // send the confirmation code again
+ Emails.confirm(newUser);
+ return Templates.register(email);
+ }
+
+
+ /**
+ * Confirmation form, once email is verified, to add user info
+ */
+ public TemplateInstance confirm(@RestQuery String confirmationCode){
+ checkLogoutFirst();
+ User newUser = checkConfirmationCode(confirmationCode);
+ return Templates.confirm(newUser);
+ }
+
+ private void checkLogoutFirst() {
+ if(getUser() != null) {
+ logoutFirst();
+ }
+ }
+
+ /**
+ * Link to logout page
+ */
+ public TemplateInstance logoutFirst() {
+ return Templates.logoutFirst();
+ }
+
+ private User checkConfirmationCode(String confirmationCode) {
+ // can't use error reporting as those are query parameters and not form fields
+ if(StringUtils.isEmpty(confirmationCode)){
+ flash("message", "Missing confirmation code");
+ flash("messageType", "error");
+ redirect(Application.class).index();
+ }
+ User user = User.findForContirmation(confirmationCode);
+ if(user == null){
+ flash("message", "Invalid confirmation code");
+ flash("messageType", "error");
+ redirect(Application.class).index();
+ }
+ return user;
+ }
+
+ @POST
+ public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank String userName,
+ @RestForm @Length(min = 8) String password,
+ @RestForm @Length(min = 8) String password2,
+ @RestForm @NotBlank String firstName,
+ @RestForm @NotBlank String lastName) {
+ checkLogoutFirst();
+ User user = checkConfirmationCode(confirmationCode);
+
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ validation.required("password", password);
+ validation.required("password2", password2);
+ validation.equals("password", password, password2);
+
+ if(User.findRegisteredByUserName(userName) != null)
+ validation.addError("userName", "User name already taken");
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ user.userName = userName;
+ user.password = BcryptUtil.bcryptHash(password);
+ user.firstName = firstName;
+ user.lastName = lastName;
+ user.confirmationCode = null;
+ user.status = UserStatus.REGISTERED;
+
+ ResponseBuilder responseBuilder = Response.seeOther(Router.getURI(Login::welcome));
+ NewCookie cookie = security.makeUserCookie(user);
+ responseBuilder.cookie(cookie);
+ return responseBuilder.build();
+ }
+}You can now use the @Authenticated and @RolesAllowed("admin") annotations on your endpoints.
In DEV mode, your private/public keys will be generated for you at startup if they do not exist and +are not specified. Cleaning your project will remove those keys, so previous JWT tokens won’t be valid +anymore on restart.
+In production environments you will need to generate and specify your private and public keys using the following +commands:
+$ openssl genrsa -out rsaPrivateKey.pem 2048
+$ openssl rsa -pubout -in rsaPrivateKey.pem -out src/main/resources/publicKey.pem
+$ openssl pkcs8 -topk8 -nocrypt -inform pem -in rsaPrivateKey.pem -outform pem -out src/main/resources/privateKey.pemYou can then point to those files in your application.properties Quarkus configuration:
mp.jwt.verify.publickey.location=publicKey.pem
+mp.jwt.decrypt.key.location=privateKey.pem
+smallrye.jwt.sign.key.location=privateKey.pem
+smallrye.jwt.encrypt.key.location=publicKey.pem
+
+quarkus.native.resources.includes=publicKey.pem
+quarkus.native.resources.includes=privateKey.pemOIDC (Open ID Connect) is a way to delegate user login to external services, such as:
+If you use OIDC, you can skip the email validation phase, and avoid storing passwords for your users, but you may +likely still need to store a user representation in your data store, and associate it to the external identity provider +using the provider name and its own ID.
+The recommended set up is to place each provider in its own tenant, and disable the default tenant if you want to leave +it free for the manual user registration and authentication we already covered:
+# Google
+quarkus.oidc.google.provider=google
+quarkus.oidc.google.client-id=SECRET
+quarkus.oidc.google.credentials.secret=SECRET
+
+# Github
+quarkus.oidc.github.provider=github
+quarkus.oidc.github.client-id=SECRET
+quarkus.oidc.github.credentials.secret=SECRET
+
+# Manual context
+quarkus.oidc.manual.tenant-enabled=false
+
+# Default is just disabled
+quarkus.oidc.tenant-enabled=false
+
+# Get rid of keycloak dev services
+quarkus.keycloak.devservices.enabled=false
+
+# Must be set to get proper error reporting
+quarkus.http.auth.proactive=falseMake sure you import the renarde-oidc module in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-oidc</artifactId>
+ <version>1.0.5</version>
+</dependency>We first adapt our User model to handle OIDC users by adding tenantId and authId fields:
package model;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.EnumType;
+import javax.persistence.Enumerated;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+@Table(name = "user_table", uniqueConstraints = @UniqueConstraint(columnNames = {"tenantId", "authId"}))
+public class User extends PanacheEntity implements RenardeUser {
+
+ @Column(nullable = false)
+ public String email;
+ @Column(unique = true)
+ public String userName;
+ public String password;
+ public String firstName;
+ public String lastName;
+ public boolean isAdmin;
+
+ @Column(unique = true)
+ public String confirmationCode;
+
+ public String tenantId;
+ public String authId;
+
+ @Column(nullable = false)
+ @Enumerated(EnumType.STRING)
+ public UserStatus status;
+
+ public boolean isRegistered(){
+ return status == UserStatus.REGISTERED;
+ }
+
+ @Override
+ public Set<String> getRoles() {
+ Set<String> roles = new HashSet<>();
+ if(isAdmin) {
+ roles.add("admin");
+ }
+ return roles;
+ }
+
+ @Override
+ public String getUserId() {
+ return userName;
+ }
+
+ public boolean isOidc() {
+ return tenantId != null;
+ }
+
+ //
+ // Helpers
+
+ public static User findUnconfirmedByEmail(String email) {
+ return find("LOWER(email) = ?1 AND status = ?2", email.toLowerCase(), UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+
+ public static User findRegisteredByUserName(String username) {
+ return find("LOWER(userName) = ?1 AND status = ?2", username.toLowerCase(), UserStatus.REGISTERED).firstResult();
+ }
+
+ public static User findByUserName(String username) {
+ return find("LOWER(userName) = ?1", username.toLowerCase()).firstResult();
+ }
+
+ public static User findByAuthId(String tenantId, String authId) {
+ return find("tenantId = ?1 AND authId = ?2", tenantId, authId).firstResult();
+ }
+
+ public static User findForContirmation(String confirmationCode) {
+ return find("confirmationCode = ?1 AND status = ?2", confirmationCode, UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+}Now you need to provide implementations of RenardeUserProvider and RenardeOidcHandler which you can group:
package util;
+
+import java.net.URI;
+import java.util.UUID;
+
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+import javax.transaction.Transactional;
+import javax.ws.rs.core.Response;
+
+import io.quarkiverse.renarde.oidc.RenardeOidcHandler;
+import io.quarkiverse.renarde.oidc.RenardeOidcSecurity;
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkiverse.renarde.security.RenardeUserProvider;
+import io.quarkiverse.renarde.router.Router;
+import io.quarkiverse.renarde.util.Flash;
+import io.quarkiverse.renarde.util.RedirectException;
+import model.User;
+import model.UserStatus;
+import rest.Application;
+import rest.Login;
+
+@ApplicationScoped
+public class MySecuritySetup implements RenardeUserProvider, RenardeOidcHandler {
+
+ @Inject
+ RenardeSecurity security;
+
+ @Inject
+ RenardeOidcSecurity oidcSecurity;
+
+ @Inject
+ Flash flash;
+
+ /**
+ * This allows us to map tenant/id to our users: manually or via OIDC
+ */
+ @Override
+ public RenardeUser findUser(String tenantId, String id) {
+ if(tenantId == null || tenantId.equals("manual")) {
+ return User.findByUserName(id);
+ } else {
+ return User.findByAuthId(tenantId, id);
+ }
+ }
+
+ /**
+ * This will be called on every successful OIDC authentication,
+ * be it a first-time user registration, or existing user login
+ */
+ @Transactional
+ @Override
+ public void oidcSuccess(String tenantId, String authId) {
+ User user = User.findByAuthId(tenantId, authId);
+ URI uri;
+ if(user == null) {
+ // registration
+ user = new User();
+ user.tenantId = tenantId;
+ user.authId = authId;
+
+ user.email = oidcSecurity.getOidcEmail();
+ user.firstName = oidcSecurity.getOidcFirstName();
+ user.lastName = oidcSecurity.getOidcLastName();
+ user.userName = oidcSecurity.getOidcUserName();
+
+ user.status = UserStatus.CONFIRMATION_REQUIRED;
+ user.confirmationCode = UUID.randomUUID().toString();
+ user.persist();
+
+ // go to registration
+ uri = Router.getURI(Login::confirm, user.confirmationCode);
+ } else if(!user.isRegistered()) {
+ // user exists, but not fully registered yet
+ // go to registration
+ uri = Router.getURI(Login::confirm, user.confirmationCode);
+ } else {
+ // regular login
+ uri = Router.getURI(Application::index);
+ }
+ throw new RedirectException(Response.seeOther(uri).build());
+ }
+
+ /**
+ * This will be called if the existing user has a valid OIDC session,
+ * and attemps to login again, so we check if the user exists, and is
+ * fully registered.
+ */
+ @Override
+ public void loginWithOidcSession(String tenantId, String authId) {
+ RenardeUser user = findUser(tenantId, authId);
+ // old cookie, no such user
+ if(user == null) {
+ flash.flash("message", "Invalid user: "+authId);
+ throw new RedirectException(security.makeLogoutResponse());
+ }
+ // redirect to registration
+ URI uri;
+ if(!user.isRegistered()) {
+ uri = Router.getURI(Login::confirm, ((User)user).confirmationCode);
+ } else {
+ flash.flash("message", "Already logged in");
+ uri = Router.getURI(Application::index);
+ }
+ throw new RedirectException(Response.seeOther(uri).build());
+ }
+}We have to adapt our registration page to account for users coming in from OIDC, by skipping the password +if the user is an OIDC user:
+{#include main.html }
+{#title}Complete registration{/title}
+
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName" value=newUser.userName/}
+ {/formElement}
+ {#if !newUser.authId}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {/if}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName" value=newUser.firstName/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName" value=newUser.lastName/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}
+{/include}And the corresponding controller:
+ @POST
+ public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank String userName,
+ @RestForm @Length(min = 8) String password,
+ @RestForm @Length(min = 8) String password2,
+ @RestForm @NotBlank String firstName,
+ @RestForm @NotBlank String lastName) {
+ checkLogoutFirst();
+ User user = checkConfirmationCode(confirmationCode);
+
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ // is it OIDC?
+ if(!user.isOidc()) {
+ validation.required("password", password);
+ validation.required("password2", password2);
+ validation.equals("password", password, password2);
+ }
+
+ if(User.findRegisteredByUserName(userName) != null)
+ validation.addError("userName", "User name already taken");
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ user.userName = userName;
+ if(!user.isOidc()) {
+ user.password = BcryptUtil.bcryptHash(password);
+ }
+ user.firstName = firstName;
+ user.lastName = lastName;
+ user.confirmationCode = null;
+ user.status = UserStatus.REGISTERED;
+
+ ResponseBuilder responseBuilder = Response.seeOther(Router.getURI(Login::welcome));
+ if(!user.isOidc()) {
+ NewCookie cookie = security.makeUserCookie(user);
+ responseBuilder.cookie(cookie);
+ }
+ return responseBuilder.build();
+ }And finally we can add the OIDC login options to the login page:
+{#include main.html }
+{#title}Login{/title}
+
+<div class="row">
+ <div class="col-md-2">
+ <fieldset>
+ <legend>Login/Register</legend>
+ <div class="d-grid gap-2">
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('github')}" role="button"><img src="/images/signin-github.svg" height="16px" style="vertical-align: text-top"/> GitHub</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('google')}" role="button"><img src="/images/signin-google.svg" height="16px" style="vertical-align: text-top"/> Google</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('microsoft')}" role="button"><img src="/images/signin-microsoft.svg" height="16px" style="vertical-align: text-top"/> Microsoft</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('facebook')}" role="button"><img src="/images/signin-facebook.svg" height="16px" style="vertical-align: text-top"/> Facebook</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('apple')}" role="button"><img src="/images/signin-apple.svg" height="16px" style="vertical-align: text-top"/> Apple</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeSecurityController.loginUsingOidc('twitter')}" role="button"><img src="/images/signin-twitter.svg" height="16px" style="vertical-align: text-top"/> Twitter</a>
+ </div>
+ </fieldset>
+ </div>
+ <-- ... Manual login and registration ... -->
+</div>
+
+{/include}In order to set up OIDC for Github you need to create a new OAuth application in your GitHub developer settings:
+
+Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to http://localhost:8080/_renarde/security/github-success
+(if you intend to test this using the Quarkus DEV mode).
Now click on Register application and you’ll be shown your application page:
+You need to click on Generate a new client secret, confirm your credentials, and write down
+your Client ID and Client secret (especially that one, because you will not be able to see it again
+later from that page, but you can always recreate one, do don’t worry too much):
+Now add the following configuration to your application.properties:
quarkus.oidc.github.provider=github
+quarkus.oidc.github.client-id=<Client ID>
+quarkus.oidc.github.credentials.secret=<Secret>In order to set up OIDC for Google you need to create a new project in your Google Cloud Platform console:
+Pick a project name and click on CREATE.
+Now make sure you select your project in the top selector, and click on the left-hand bar menu on APIs and Services > OAuth consent screen:
+Select External to authorise any Google user to log in to your application and press CREATE:
+Now you can fill in your application name, your support email, your developer contact information and press SAVE AND CONTINUE:
+Do not add any scopes on the next page, and press SAVE AND CONTINUE:
+Do not add any test user on the next page, and press SAVE AND CONTINUE:
+Click on the top menu CREATE CREDENTIALS > OAuth client ID:
+Select Web application as Application type, and add http://localhost:8080/_renarde/security/oidc-success in
+the Authorised redirect URIs list, then press CREATE:
+Copy your Client ID and Client Secret:
+
+You can now configure your application.properties:
quarkus.oidc.google.provider=google
+quarkus.oidc.google.client-id=<Client ID>
+quarkus.oidc.google.credentials.secret=<Secret>In order to set up OIDC for Microsoft you need to go to your Microsoft Azure Portal,
+and search for Azure Active Directory, then click on it:
+Once there, on the left side under Manage, click on App registrations then click on New registration:
+Fill in your application name, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) to allow anyone to log in, and add a Web Redirect URI as http://localhost:8080/_renarde/security/oidc-success,
+then click on Register:
+On that resulting page, copy the Client Id (under Application (client) ID, then click on Add a certificate or secret:
+Now, under Client secrets (0), click on New client secret:
+Click on Add in that dialog without changing anything:
+On the resulting page, copy your Secret ID:
+You can now configure your application.properties:
quarkus.oidc.microsoft.provider=microsoft
+quarkus.oidc.microsoft.client-id=<Client ID>
+quarkus.oidc.microsoft.credentials.secret=<Secret>In order to set up OIDC for Apple you need to create a developer account, and sign up for the 99€/year program, but you cannot test your application on localhost like most other OIDC providers:
+you will need to run it over https and make it publicly accessible, so for development purposes
+you may want to use a service such as https://ngrok.com.
Go to Create a new identifier and press +
+Dont touch anything, keep App IDs selected, and press Continue:
+Dont touch anything, keep App selected, and press Continue:
+Enter a description and a Bundle ID (use your application package name):
+
+Then scroll down to find the Sign in with Apple Capability, select it, and press Continue:
+Write down your App ID Prefix, then press Register:
+Back on the Identifiers page, press +:
+Select Service IDs and press Continue:
+Enter a description and Bundle ID (use your application package name), then press Continue:
+Now press Register:
+Back on the service list, click on your newly created service:
+
+Enable Sign in with Apple and press Configure:
+Add your domain and return URL (set to <host>/_renarde/security/oidc-success) and press Next:
+Now press Done:
+Now press Continue:
+And now press Save:
+Go to the Keys page on the left menu, and press +:
+Fill in a key name, enable Sign in with Apple, and press Configure:
+Select your Primary App ID and press Save:
+Back on the key page, press Continue:
+Now press Register:
+Write down your Key ID, download your key and save it to your Quarkus application in src/main/resources/AuthKey_<KEYID>.p8:
+You can now configure your your application.properties:
quarkus.oidc.apple.provider=apple
+quarkus.oidc.apple.client-id=<Bundle ID>
+quarkus.oidc.apple.credentials.jwt.key-file=AuthKey_<Key ID>.p8
+quarkus.oidc.apple.credentials.jwt.token-key-id=<Key ID>
+quarkus.oidc.apple.credentials.jwt.issuer=<App ID Prefix>
+quarkus.oidc.apple.credentials.jwt.subject=<Bundle ID}Facebook you will not be let you test your application on localhost like most other OIDC providers:
+you will need to run it over https and make it publicly accessible, so for development purposes
+you may want to use a service such as https://ngrok.com.
In order to set up OIDC for Facebook start by Creating an application, select None as an app type, and press Next:
+Now enter an application name, and contact email, and press Create app:
+On the app page, click Set up on the Facebook login product:
+Quick the Quickstarts page and click on Facebook login > Settings on the left menu:
+Enter your Redirect URIs (set to <host>/_renarde/security/oidc-success) and press Save changes:
+Now go to Settings > Basic on the left hand menu, and write down your App ID and App secret:
+You can now configure your your application.properties:
quarkus.oidc.facebook.provider=facebook
+quarkus.oidc.facebook.client-id=<App ID>
+quarkus.oidc.facebook.credentials.secret=<App secret>You can use Twitter for OIDC login, but at the moment, it restricts access to the user’s email, which means you +will have to obtain it and verify it yourself.
+In order to set up OIDC for Twitter start by Creating a project, enter a project name, and press Next:
+Enter a use case, and press Next:
+Enter a project description, and press Next:
+Now enter an application name, and press Next:
+Write down your keys, because they will not be displayed again, and press App Settings:
+Navigate down to the User authentication settings section and press Set up:
+Check the OAuth 2.0 check box:
+Select Web App as application type, then fill in your application details (use <host>/_renarde/security/twitter-success
+for the Callback URI).
| + + | +
+Twitter doesn’t require https usage in practice, but won’t accept your Website URL without it, so
+you can still use ngrok for it.
+ |
+
Now press Save:
+You can now copy your Client ID and Client Secret and press Done:
+You can now configure your your application.properties:
quarkus.oidc.twitter.provider=twitter
+quarkus.oidc.twitter.client-id=<Client ID>
+quarkus.oidc.twitter.credentials.secret=<Client Secret>A lot of the time, you need to send data from the browser to your endpoints, which is often done with forms.
+Creating forms in Renarde is easy: let’s see an example of how to do it in Qute:
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName"/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName"/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}Here we’re defining a form whose action will go to Register.complete(newUser.confirmationCode) and
+which contains several form elements, which are just tags to make composition easier. For example formElement is
+a custom Qute tag for Bootstrap which defines layout for the form element and displays any associated error:
<div class="mb-3">
+ <label class="form-label" for="{name}">{label}</label>
+ {nested-content}
+ {#ifError name}
+ <span class="invalid-feedback">{#error name/}</span>
+ {/ifError}
+</div>The input user tag is also designed for Bootstrap as an abstraction:
<input name="{name}"
+ type="{type ?: 'text'}"
+ placeholder="{placeholder ?: ''}"
+ class="form-control {#ifError name}is-invalid{/ifError}"
+ maxlength="{global:VARCHAR_SIZE}"
+ value="{inject:flash.get(name)}"/>As you can see, we have default values for certain attributes, a special error class if there is a validation +error, and we default the value to the one preserved in the flash scope, which is filled whenever validation +fails, so that the user can see the validation error without losing their form values.
+As for the form Renarde tag, it is also fairly simple, and only includes an authenticity token for CSRF protection.
<form action="{it}" method="{method ?: 'POST'}" class="{klass ?: ''}">
+ {#authenticityToken/}
+ {nested-content}
+</form>Most forms will be a @POST endpoint, with each form element having a corresponding parameter annotated with @RestForm.
@POST
+public void complete(@RestQuery String confirmationCode,
+ @RestForm String userName,
+ @RestForm String password,
+ @RestForm String password2,
+ @RestForm String firstName,
+ @RestForm String lastName) {
+ // do something with the form parameters
+}You can also group parameters in a POJO, but for now you have to add a special
+@Consumes(MediaType.MULTIPART_FORM_DATA) annotation:
@Consumes(MediaType.MULTIPART_FORM_DATA)
+@POST
+public void complete(@RestQuery String confirmationCode,
+ FormData form) {
+ // do something with the form parameters
+}
+
+public static class FormData {
+ @RestForm String userName;
+ @RestForm String password;
+ @RestForm String password2;
+ @RestForm String firstName;
+ @RestForm String lastName;
+}Check out the RESTEasy Reactive documentation +for more information about form parameters and multi-part.
+You can place your usual Hibernate Validation annotations on the controller methods that receive user data, but +keep in mind that you have to check for validation errors in your method before you do any action that modifies your state. +This allows you to check more things than you can do with just annotations, with richer logic:
+@POST
+public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String userName,
+ @RestForm @NotBlank @Length(min = 8, max = Util.VARCHAR_SIZE) String password,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String password2,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String firstName,
+ @RestForm @NotBlank @Length(max = Util.VARCHAR_SIZE) String lastName) {
+ // Find the user for this confirmation code
+ User user = User.findForContirmation(confirmationCode);
+ if(user == null){
+ validation.addError("confirmationCode", "Invalid confirmation code");
+ }
+
+ // Make sure the passwords match
+ validation.equals("password", password, password2);
+
+ // Make sure the username is free
+ if(User.findByUserName(userName) != null){
+ validation.addError("userName", "User name already taken");
+ }
+
+ // If validation failed, redirect to the confirm page
+ if(validationFailed()){
+ confirm(confirmationCode);
+ }
+
+ // Now proceed to complete user registration
+ ...
+}You can use the validation object to trigger additional validation logic and collect errors.
Those errors are then placed in the flash scope by a call to validationFailed() if there
+are any errors, and thus preserved when you redirect from your action method to the @GET method
+that holds the submitted form, which you can then access in your views using the {#ifError field}{/ifError}
+conditional tag, or the {#error field/} tag which accesses the error message for the given field.
We have seen how to declare endpoints and how URIs map to them, but very often we need to map from endpoints to +URIs, which Renarde makes easy.
+When handling a @POST, @PUT or @DELETE endpoint, it’s good form to redirect to a @GET endpoint after
+the action has been done, in order to allow the user to reload the page without triggering the action a second
+time, and such redirects are simply done by calling the corresponding @GET endpoint. In reality, the endpoint
+will not be called and will be replaced by a redirect that points to the endpoint in question.
package rest;
+
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the index page
+ index();
+ }
+}If there are any parameters that form the URI, you must pass them along:
+package rest;
+
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+
+import org.jboss.resteasy.reactive.RestPath;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+
+ public TemplateInstance somePage(@RestPath String id, @RestQuery String q) {
+ // do something with the id and q
+ return Templates.index();
+ }
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the somePage page
+ somePage("foo", "bar");
+ }
+}If you want to redirect to another controller, you can use the redirect(Class) method:
package rest;
+
+import jakarta.ws.rs.POST;
+
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @POST
+ public void someAction() {
+ // do something
+ ...
+ // redirect to the Todos.index() endpoint
+ redirect(Todos.class).index();
+ }
+}If you don’t want a redirect but need a URI to a given endpoint, you can use the Router.getURI
+or Router.getAbsoluteURI methods, by
+passing them a method reference to the endpoint you want and the required parameters:
package rest;
+
+import java.net.URI;
+
+import org.jboss.resteasy.reactive.RestPath;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+import io.quarkiverse.renarde.router.Router;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance somePage();
+ public static native TemplateInstance otherPage(URI uri);
+ }
+
+ public TemplateInstance somePage(@RestPath String foo, @RestQuery Long bar) {
+ return Templates.somePage();
+ }
+
+ public TemplateInstance otherPage() {
+ // Obtain a URI to somePage
+ URI uri = Router.getURI(Login::somePage, "something", 23l);
+ // pass it on to our view
+ return Templates.otherPage(uri);
+ }
+}| + + | +
+If you plan on using Response.seeOther or Controller.seeOther, make sure to use the Router.getAbsoluteURI
+variant, especially if you use the quarkus.http.root-path configuration, otherwise your URIs contain that prefix twice.
+ |
+
If you want a URI to an endpoint in a Qute view, you can use the uri and uriabs namespace with a
+call to the endpoint you want to point to:
<a class="navbar-brand" href="{uri:Application.index()}">Todo</a>Naturally, you can also pass any required parameters.
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-mailer</artifactId>
+</dependency>Often you will need your actions to send email notifications.You can use Qute for this too, by declaring your
+emails in an Emails class:
package email;
+
+import io.quarkus.mailer.MailTemplate.MailTemplateInstance;
+import io.quarkus.qute.CheckedTemplate;
+import model.User;
+
+public class Emails {
+
+ private static final String FROM = "Todos <todos@example.com>";
+ private static final String SUBJECT_PREFIX = "[Todos] ";
+
+ @CheckedTemplate
+ static class Templates {
+ public static native MailTemplateInstance confirm(User user);
+ }
+
+ public static void confirm(User user) {
+ Templates.confirm(user)
+ .subject(SUBJECT_PREFIX + "Please confirm your email address")
+ .to(user.email)
+ .from(FROM)
+ .send().await().indefinitely();
+ }
+}You can then send the email from your endpoint by calling Emails.confirm(user).
You can use composition for emails too, by having a pair of base templates for HTML in
+src/main/resources/templates/email.html:
<!DOCTYPE html>
+
+<html>
+ <head>
+ <meta charset="UTF-8">
+ </head>
+ <body>
+ {#insert /}
+ <p>
+ This is an automated email, you should not reply to it: your mail will be ignored.
+ </p>
+ </body>
+</html>And for text in src/main/resources/templates/email.txt:
{#insert /}
+
+This is an automated email, you should not reply to it: your mail will be ignored.You can then use those templates in your emails in src/main/resources/templates/Emails/confirm.html:
{#include email.html }
+
+<p>
+ Welcome to Todos.
+</p>
+
+<p>
+ You received this email because someone (hopefully you) wants to register on Todos.
+</p>
+
+<p>
+ If you don't want to register, you can safely ignore this email.
+</p>
+
+<p>
+ If you want to register, <a href="{uriabs:Login.confirm(user.confirmationCode)}">complete your registration</a>.
+</p>
+{/include}And for text in src/main/resources/templates/Emails/confirm.txt:
{#include email.txt}
+
+Welcome to Todos.
+
+You received this email because someone (hopefully you) wants to register on Todos.
+
+If you don't want to register, you can safely ignore this email.
+
+If you want to register, complete your registration by going to the following address:
+
+{uriabs:Login.confirm(user.confirmationCode)}
+{/include}Note that in emails you will want to use the uriabs namespace for absolute URIs and not relative ones,
+otherwise the links won’t work for your email recipients.
You can find more information in the Quarkus mailer documentation.
+You can declare your default language and supported languages in src/main/resources/application.properties:
# This is the default locale for your application
+quarkus.default-locale=en
+# These are the supported locales (should include the default locale, but order is not important)
+quarkus.locales=en,frNext, you can declare your default language messages in the src/main/resources/messages.properties file:
# A simple message
+hello=Hello World
+# A parameterised message for your view
+views_Application_index_greet=Hello %sDeclare your other language translations in the src/main/resources/messages_fr.properties file:
hello=Bonjour Monde
+views_Application_index_greet=Salut %sNow you can use these translated messages in your controller:
+public static class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance index(String name);
+ }
+
+ public TemplateInstance index() {
+ return Templates.index("Stef");
+ }
+
+ public String hello() {
+ return i18n.formatMessage("hello");
+ }
+}Or in your template:
+With no parameter:
+{m:hello}
+With parameters:
+{m:views_Application_index_greet(name)}The current language for a request will depend on the following (in order):
+The _renarde_locale cookie, if set
The Accept-Language HTTP header, if set,
+which defines an ordered list of languages by user preference. We will select a best matching language from the set
+of quarkus.locales.
If nothing else, we default to the default language as set by quarkus.default-locale, which defaults to en_US.
You can override the user’s language with a cookie by calling i18n.set(locale):
public static class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ public void index() {
+ return Templates.index();
+ }
+
+ @POST
+ public void french() {
+ i18n.set("fr");
+ index();
+ }
+
+ @POST
+ public void english() {
+ i18n.set("en");
+ index();
+ }
+}If you need to pass values from one endpoint to another request after a redirect, you can use the Flash scope.
+Usually this is done in a @POST endpoint, by filling the Flash scope with either errors or messages,
+before trigerring a redirect to the right @GET endpoint.
You can push values in the Flash scope in an endpoint using the flash(name, value) method, or using the
+Flash injectable component.
You can read values from the Flash scope in your Qute views using the {flash:name} namespace.
The Flash scope only lasts from one request to the next and is cleared at each request.
+If you want to use htmx with Renarde, we added an extra layer to make things more convenient:
+public class Application extends HxController {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance foo(int a, int b);
+ public static native TemplateInstance foo$sectionA(int a); (1)
+ public static native TemplateInstance foo$sectionB(int b); (1)
+
+ public static native TemplateInstance bar();
+ }
+
+ public TemplateInstance foo() {
+ if (isHxRequest()) { (2)
+ return concatTemplates( (3)
+ Templates.foo$sectionA(1),
+ Templates.foo$sectionB(2)
+ );
+ }
+ return Templates.foo(1, 2);
+ }
+
+ public TemplateInstance bar() {
+ onlyHxRequest(); (4)
+ this.hx(HxResponseHeader.TRIGGER, "refresh"); (5)
+ return Templates.bar();
+ }
+}| 1 | +Qute fragments declarations | +
| 2 | +Check if this is a htmx request by looking for the HX-Request header or using flash data for redirects |
+
| 3 | +Out of band swap with different templates or fragments | +
| 4 | +Only Hx requests are allowed, else it will fail with a BAD_REQUEST error | +
| 5 | +Flag the response with an htmx response header | +
For CSRF Security, you need a form parameter with the CSRF Token. By adding this 👇 when doing a hx-post/put/delete, The Hx requests will be sent with the CSRF parameter:
+<div hx-post"/hello" hx-vals='{"{inject:csrf.parameterName}": "{inject:csrf.token}"}'>Alternatively, you can use hx-headers on the <body> to make all hx requests secured with CSRF by adding a custom header:
<body hx-headers='{"{inject:csrf.headerName}":"{inject:csrf.token}"}'>
+</body>Some example projects with Quarkus Renarde and htmx: +- a demo note-taking web app +- a board game
+If you import the optional quarkus-renarde-barcode module, you can generate barcodes in your views or controllers.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-barcode</artifactId>
+ <version>3.0.9</version>
+</dependency>We support the following barcode types, with custom Qute tags:
+| Tag | +Description | +
|---|---|
|
+Generate an EAN 13 barcode. |
+
|
+Generate an EAN 8 barcode. |
+
|
+Generate an UPC A barcode. |
+
|
+Generate an UPC E barcode. |
+
|
+Generate a Code 39 barcode. |
+
|
+Generate a Code 93 barcode. |
+
|
+Generate a Code 128 barcode. |
+
|
+Generate a QR Code barcode. |
+
|
+Generate a Data Matrix barcode. |
+
All these tags accept an optional size parameter that sets both the width and height of the barcode
+in pixels, or width and height parameters to specify different values.These values all default
+to 200 pixels.
The generated barcodes will be inline HTML images using the Data URI +scheme as an embedded PNG image.
+If you wish to generate barcode images as PNG bytes or other formats, you can use the io.quarkiverse.renarde.barcode.Barcode
+helper class which allows you to generate bytecodes from your controllers.
If you import the optional quarkus-renarde-pdf module, you can generate PDF documents in your views.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-pdf</artifactId>
+ <version>3.0.9</version>
+</dependency>There are lots of complicated ways to generate PDFs, but the simplest is to use the versatility of HTML for rendering
+and its printing support. So, very much like you can print HTML files using your browser, and there are special rendering
+rules in CSS, you do the same in Renarde PDF: you render your page in HTML, and simply add @Produces(Pdf.APPLICATION_PDF)
+to your controller to produce a PDF file:
public class Application extends Controller {
+
+ @CheckedTemplate
+ public static class Templates {
+ public static native TemplateInstance page();
+ }
+
+ // This will return a PDF file to the caller
+ @Produces(Pdf.APPLICATION_PDF)
+ public TemplateInstance pdf() {
+ return Templates.page();
+ }
+
+ // This will return HTML to the caller
+ public TemplateInstance html() {
+ return Templates.page();
+ }
+}This way, the http://localhost:8080/Application/pdf and http://localhost:8080/Application/html +pages will render the same document in either PDF or HTML, which allows you to use your browser and its +developer tools to fine-tweak your document, until you’re ready to turn it into a PDF, which is +much harder to fine-tweak.
+As for the templates/Application/page.html template, it’s regular HTML, but you can also
+take advantage of the CSS print support
+to set things like document page size, odd/even page margins, etc…:
<!DOCTYPE html>
+<html>
+ <head>
+ <title>This is the PDF document title</title>
+ <style>
+/* Override page size, and set page margin */
+@page {
+ size: 15cm 9cm;
+ margin: 1cm;
+}
+ </style>
+ </head>
+ <body>
+ Some PDF text.
+ </body>
+</html>Note that the default page size is A4.
+| + + | ++This is an experimental API and feature, subject to change. + | +
Renarde can automatically generate a UI for editing your entities. This can be useful to expose +access to your entities to authenticated users who are trained enough to understand how to navigate +your model.
+You must import the optional quarkus-renarde-backoffice module.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-backoffice</artifactId>
+ <version>3.0.9</version>
+</dependency>Now, you can opt-in to specify which of your entities will be exposed via the generated backoffice by
+implementing the BackofficeController<X> type for each entity type X to expose:
package rest;
+
+import io.quarkiverse.renarde.backoffice.BackofficeController;
+import io.quarkus.security.Authenticated;
+import model.User;
+
+@Authenticated
+public class Users extends BackofficeController<User> {
+
+}| + + | ++This allows you to place authentication restrictions to your entities, but any other annotation +works too. + | +
| + + | ++Make sure to secure your backoffice, otherwise everyone will have access to your database! + | +
In order to also secure the backoffice index page, you may extend the BackofficeIndexController:
package rest;
+
+import io.quarkiverse.renarde.backoffice.BackofficeIndexController;
+import io.quarkus.security.Authenticated;
+
+@Authenticated
+public class Backoffice extends BackofficeIndexController {
+
+}This is all you have to do!
+Now you can sit back, relax and head over to http://localhost:8080/_renarde/backoffice/index and +see the list of entity types you have enlisted in the backoffice:
+
+If you select an entity type, you are presented with the list of entities of this type:
+
+From there, you can either create or edit one entity:
+
+The generated forms and controllers support the following attribute types:
+| Type/Annotation | +Form element | +
|---|---|
|
+Checkbox |
+
|
+Number input |
+
|
+Text field of length 1 |
+
|
+Text area |
+
|
+Text input |
+
|
+File input |
+
|
+Text area |
+
|
+DateTime input |
+
|
+Date input |
+
|
+Time input |
+
|
+Timestamp input |
+
|
+Select input with enum values |
+
|
+Multiple-select input with possible values |
+
|
+Multiple-select input with possible values |
+
|
+Select input with possible values |
+
| + + | ++This is an experimental API and feature, subject to change. + | +
Renarde can help you transport your entities' data from one place to another, which is a notoriously +complex thing to do with entities with relations. Most people who need to serialise an entity to a format, +such as JSON, need to annotate their model with special annotations, or write a custom serialiser and +deserialiser, because out of the box, model entities have too many relations to translate directly to JSON.
+On the other hand, if you do not care what the format of the serialised entity looks like, Renarde can +automatically generate the proper serialisers and deserialisers for your entities, to make sure that +you can serialise and deserialise them to JSON trivially using the Database Transporter module.
+This way, you can easily expose some or all of your data from your production or test instances, such +that DEV instances will automatically pick it up and seed their DEV database, which makes for much simpler +development set-up, with useful data.
+You must import the optional quarkus-renarde-transporter module.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-transporter</artifactId>
+ <version>3.0.9</version>
+</dependency>Now, if you wish to expose your serialised entities somewhere, you may write an endpoint like +this one:
+package rest;
+
+import io.quarkiverse.renarde.Controller;
+import io.quarkiverse.renarde.transporter.DatabaseTransporter;
+import jakarta.transaction.Transactional;
+import model.Configuration;
+import model.Organiser;
+import model.PreviousSpeaker;
+import model.PricePack;
+import model.PricePackDate;
+import model.Slot;
+import model.Speaker;
+import model.Sponsor;
+import model.Talk;
+import model.TalkTheme;
+import model.TalkType;
+import model.TemporarySlot;
+import model.Track;
+
+public class Serialiser extends Controller {
+
+ @Transactional
+ public String json() {
+ return DatabaseTransporter.export((entityType, fieldName, value) -> {
+ // this will sanitise some data we wish to remove from the export
+ if(entityType == Speaker.class) {
+ // make sure we remove confidential info
+ switch(fieldName) {
+ case "email":
+ case "phone":
+ return null;
+ }
+ }
+ return value;
+ },
+ // we want all of these entities
+ Configuration.listAll(),
+ Organiser.listAll(),
+ PreviousSpeaker.listAll(),
+ PricePack.listAll(),
+ PricePackDate.listAll(),
+ Slot.listAll(),
+ Speaker.listAll(),
+ Sponsor.listAll(),
+ Talk.listAll(),
+ TalkTheme.listAll(),
+ TalkType.listAll(),
+ TemporarySlot.listAll(),
+ Track.listAll());
+ }
+}| + + | ++Remember to not expose sensitive or private data publicly, or you should secure your endpoint. + | +
Now, if you want your DEV instances to pick up the data automatically from production or test servers, you can +write the following startup class:
+package util;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import io.quarkiverse.renarde.transporter.DatabaseTransporter;
+import io.quarkus.elytron.security.common.BcryptUtil;
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+import io.quarkus.hibernate.orm.panache.PanacheEntityBase;
+import io.quarkus.logging.Log;
+import io.quarkus.runtime.LaunchMode;
+import io.quarkus.runtime.StartupEvent;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.transaction.Transactional;
+import model.Configuration;
+import model.Organiser;
+import model.PreviousSpeaker;
+import model.PricePack;
+import model.PricePackDate;
+import model.Slot;
+import model.Speaker;
+import model.Sponsor;
+import model.Talk;
+import model.TalkTheme;
+import model.TalkType;
+import model.TemporarySlot;
+import model.Track;
+import model.User;
+
+@ApplicationScoped
+public class Startup {
+
+ @ConfigProperty(name = "dev-auto-setup.url")
+ Optional<String> devAutoSetupUrl;
+
+ /**
+ * This method is executed at the start of your application
+ */
+ @Transactional
+ public void start(@Observes StartupEvent evt) {
+ // in DEV mode we seed some data
+ if(LaunchMode.current() == LaunchMode.DEVELOPMENT) {
+ if(devAutoSetupUrl.isPresent()) {
+ String dataSource = devAutoSetupUrl.get();
+ Log.infof("Loading data from %s", dataSource);
+ try {
+ try(InputStream is = new URL(dataSource).openStream()){
+ String json = new String(is.readAllBytes(), StandardCharsets.UTF_8);
+ // make sure we delete all previous test data
+ Configuration.deleteAll();
+ Organiser.deleteAll();
+ PreviousSpeaker.deleteAll();
+ PricePack.deleteAll();
+ PricePackDate.deleteAll();
+ Slot.deleteAll();
+ Speaker.deleteAll();
+ Sponsor.deleteAll();
+ Talk.deleteAll();
+ TalkTheme.deleteAll();
+ TalkType.deleteAll();
+ TemporarySlot.deleteAll();
+ Track.deleteAll();
+ Map<Class<?>,List<? extends PanacheEntityBase>> entities = DatabaseTransporter.importEntities(json);
+ // Load the entities in the proper order: relation targets before relation owners
+ for (Class<? extends PanacheEntityBase> entityType : DatabaseTransporter.sortedEntityTypes()) {
+ List<? extends PanacheEntityBase> list = entities.get(entityType);
+ if(list != null) {
+ for (PanacheEntityBase entity : list) {
+ // remove the ID, to get a fresh entity
+ ((PanacheEntity)entity).id = null;
+ entity.persist();
+ }
+ }
+ }
+ }
+ } catch (IOException e) {
+ throw new UncheckedIOException(e);
+ }
+ }
+ }
+ }
+}And voilà! Your data is trivally transported from one server to another, using JSON, in a format +you don’t care about ♥.
+ Web Framework - Main ConceptsBy convention, you can place your model classes in the model package, but anywhere else works just as well.We
+recommend using Hibernate ORM with Panache.Here’s an example entity for our sample Todo application:
package model;
+
+import java.util.Date;
+import java.util.List;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.ManyToOne;
+
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+public class Todo extends PanacheEntity {
+
+ @ManyToOne
+ public User owner;
+
+ public String task;
+
+ public boolean done;
+
+ public Date doneDate;
+
+ public static List<Todo> findByOwner(User user) {
+ return find("owner = ?1 ORDER BY id", user).list();
+ }
+}By convention, you can place your controllers in the rest package, but anywhere else works just as well.You
+have to extend the Controller class in order to benefit from extra easy endpoint declarations and reverse-routing,
+but that superclass also gives you useful methods.We usually have one controller per model class, so we tend to use
+the plural entity name for the corresponding controller:
package rest;
+
+import java.util.Date;
+import java.util.List;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.ws.rs.POST;
+
+import org.jboss.resteasy.reactive.RestForm;
+import org.jboss.resteasy.reactive.RestPath;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import model.Todo;
+
+public class Todos extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index(List<Todo> todos);
+ }
+
+ public TemplateInstance index() {
+ // list every todo
+ List<Todo> todos = Todo.listAll();
+ // render the index template
+ return Templates.index(todos);
+ }
+
+ @POST
+ public void delete(@RestPath Long id) {
+ // find the Todo
+ Todo todo = Todo.findById(id);
+ notFoundIfNull(todo);
+ // delete it
+ todo.delete();
+ // send loving message
+ flash("message", "Task deleted");
+ // redirect to index page
+ index();
+ }
+
+ @POST
+ public void done(@RestPath Long id) {
+ // find the Todo
+ Todo todo = Todo.findById(id);
+ notFoundIfNull(todo);
+ // switch its done state
+ todo.done = !todo.done;
+ if(todo.done)
+ todo.doneDate = new Date();
+ // send loving message
+ flash("message", "Task updated");
+ // redirect to index page
+ index();
+ }
+
+ @POST
+ public void add(@NotBlank @RestForm String task) {
+ // check if there are validation issues
+ if(validationFailed()) {
+ // go back to the index page
+ index();
+ }
+ // create a new Todo
+ Todo todo = new Todo();
+ todo.task = task;
+ todo.persist();
+ // send loving message
+ flash("message", "Task added");
+ // redirect to index page
+ index();
+ }
+}Every public method is a valid endpoint. If it has no HTTP method annotation (@GET, @HEAD, @POST, @PUT, @DELETE) then
+it is assumed to be a @GET method.
Most @GET methods will typically return a TemplateInstance for rendering an HTML server-side template, and should not
+modify application state.
Controller methods annotated with @POST, @PUT and @DELETE will typically return void and trigger a redirect to a @GET
+method after they do their action. This is not mandatory, you can also return a TemplateInstance if you want, but it is good form
+to use a redirect to avoid involuntary actions when browsers reload the page. Those methods also get an implicit @Transactional
+annotation so you don’t need to add it.
If your controller is not annotated with @Path it will default to a path using the class name. If your controller method is not
+annotated with @Path it will default to a path using the method name. The exception is if you have a @Path annotation on the
+method with an absolute path, in which case the class path part will be ignored. Here’s a list of example annotations and how they
+result:
| Class declaration | +Method declaration | +URI | +
|---|---|---|
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
Furthermore, if you specify path parameters that are not present in your path annotations, they will be automatically +appended to your path:
+public class Orders extends Controller {
+
+ // The URI will be Orders/get/{owner}/{id}
+ public TemplateInstance get(@RestPath String owner, @RestPath Long id) {
+ }
+
+ // The URI will be /orders/{owner}/{id}
+ @Path("/orders")
+ public TemplateInstance otherGet(@RestPath String owner, @RestPath Long id) {
+ }
+}You can place your Qute views in the src/main/resources/templates folder,
+using the {className}/{methodName}.html naming convention.
Every controller that has views should declare them with a nested static class annotated with @CheckedTemplate:
public class Todos extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index(List<Todo> todos);
+ }
+
+ public TemplateInstance index() {
+ // list every todo
+ List<Todo> todos = Todo.listAll();
+ // render the index template
+ return Templates.index(todos);
+ }
+}Here we’re declaring the Todos/index.html template, specifying that it takes a todos parameter of type
+List<Todo> which allows us to validate the template at build-time.
Templates are written in Qute, and you can also declare imported templates in order to validate them using a
+toplevel class, such as the main.html template:
package rest;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+
+@CheckedTemplate
+public class Templates {
+ public static native TemplateInstance main();
+}Typical web applications will have a main template for their layout and use composition in every method. For example, we
+can declare the following main template in main.html:
<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <title>{#insert title /}</title>
+ <meta charset="UTF-8">
+ <link rel="stylesheet" media="screen" href="/stylesheets/main.css">
+ {#insert moreStyles /}
+ <script src="/javascripts/main.js" type="text/javascript" charset="UTF-8"></script>
+ {#insert moreScripts /}
+ </head>
+ <body>
+ {#insert /}
+ </body>
+</html>And then use it in our Todos/index.html template to list the todo items:
{#include main.html }
+{#title}Todos{/title}
+
+<table class="table">
+ <thead>
+ <tr>
+ <th>#</th>
+ <th>Task</th>
+ </tr>
+ </thead>
+ <tbody>
+ {#for todo in todos}
+ <tr>
+ <th>{todo.id}</th>
+ <td>{todo.task}</td>
+ </tr>
+ {/for}
+ </tbody>
+</table>
+
+{/include}| Tag | +Description | +
|---|---|
| + | Iterate over collections |
+
| + | Conditional statement |
+
| + | Switch statement |
+
| + | Adds value members to the local scope |
+
| + | Declare local variables |
+
| + | Template composition |
+
If you want to declare additional tags in order to be able to repeat them in your templates, simply place them in the
+templates/tags folder. For example, here is our user.html tag:
<span class="user-link" title="{it.userName}">
+{#if img??}
+{#gravatar it.email size=size.or(20) default='mm' /}
+{/if}
+{it.userName}</span>Which allows us to use it in every template:
+{#if inject:user}
+ {#if inject:user.isAdmin}<span class="bi-star-fill" title="You are an administrator"></span>{/if}
+ {#user inject:user img=true size=20/}
+{/if}You can pass parameters to your template with name=value pairs, and the first unnamed parameter value becomes available
+as the it parameter.
See the Qute documentation for more information.
+Renarde comes with a few extra tags to make your life easier:
+| Tag | +Description | +
|---|---|
|
+Generate a hidden HTML form element containing a CSRF token to be matched in the next request. |
+
|
+Inserts the error message for the given field name |
+
|
+Generates an HTML form for the given |
+
|
+Inserts a gravatar image for the given |
+
|
+Conditional statement executed if there is an error for the given field |
+
If you need additional methods to be registered to be used on your template expressions, you can declare static methods in
+a class annotated with @TemplateExtension:
package util;
+
+import java.util.Calendar;
+import java.util.Date;
+import java.util.GregorianCalendar;
+
+import io.quarkus.qute.TemplateExtension;
+
+@TemplateExtension
+public class JavaExtensions {
+
+ public static boolean isRecent(Date date){
+ Date now = new Date();
+ Calendar cal = new GregorianCalendar();
+ cal.add(Calendar.MONTH, -6);
+ Date sixMonthsAgo = cal.getTime();
+ return date.before(now) && date.after(sixMonthsAgo);
+ }
+
+}This one declares an additional method on the Date type, allowing you to test whether a date is recent or not:
{#if todo.done && todo.doneDate.isRecent()}
+ This was done recently!
+{/if}| Target type | +Method | +Description | +
|---|---|---|
|
+
|
+Formats the date to the |
+
|
+
|
+Formats the date to the |
+
|
+
|
+Returns |
+
|
+
|
+Formats the date in terms of |
+
|
+
|
+Returns an MD5 hash of the given string |
+
|
+
|
+Returns true if the given object is exactly of the specified class name |
+
If you need to pass variables to every template, instead of passing them manually to every view, you can define them as
+methods in a class annotated with @TemplateGlobal:
package util;
+
+import io.quarkus.qute.TemplateGlobal;
+
+@TemplateGlobal
+public class Globals {
+
+ public static String lineSeparator(){
+ return System.lineSeparator();
+ }
+
+}This one declares a lineSeparator global variable that you can use in the views:
This system uses this line separator: {lineSeparator}| Type | +Name | +Description | +
|---|---|---|
|
+
|
+The absolute request url, including scheme, host, port, path |
+
|
+
|
+The request method ( |
+
|
+
|
+The request HTTP scheme ( |
+
|
+
|
+The request authority part (ex: |
+
|
+
|
+The request host name (ex: |
+
|
+
|
+The request port (ex: |
+
|
+
|
+The request path (ex: |
+
|
+
|
+The controller endpoint class and method (ex: |
+
|
+
|
+True if the request is served over SSL/HTTPS |
+
|
+
|
+The remote client IP address |
+
|
+
|
+The remote client Host name, if available |
+
|
+
|
+The remote client port |
+
You can use webjars to provide third-party JavaScript or CSS. For example, here is how you can import Bootstrap
+and Bootstrap-icons in your pom.xml:
<dependency>
+ <groupId>org.webjars</groupId>
+ <artifactId>bootstrap</artifactId>
+ <version>5.1.3</version>
+</dependency>
+<dependency>
+ <groupId>org.webjars.npm</groupId>
+ <artifactId>bootstrap-icons</artifactId>
+ <version>1.7.0</version>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-webjars-locator</artifactId>
+</dependency>After that, you can include them in your Qute templates with:
+<head>
+ <link rel="stylesheet" media="screen" href="/webjars/bootstrap/css/bootstrap.min.css">
+ <link rel="stylesheet" media="screen" href="/webjars/bootstrap-icons/font/bootstrap-icons.css">
+ <script src="/webjars/bootstrap/js/bootstrap.min.js" type="text/javascript" charset="UTF-8"></script>
+</head>Look at https://mvnrepository.com/artifact/org.webjars for the list of available options.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Option to control the name of the cookie used to redirect the user back to where he wants to get access to. +
+
+Environment variable: |
+string |
+
|
+
Web Framework - Getting Started
+Renarde is a server-side Web Framework based on Quarkus, Qute,
+Hibernate and RESTEasy Reactive.
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde</artifactId>
+ <version>3.0.9</version>
+</dependency>Let’s see how you can quickly build a Web Application with Renarde. Let’s start with a Controller:
+package rest;
+
+import jakarta.ws.rs.Path;
+
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkiverse.renarde.Controller;
+
+public class Application extends Controller {
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance index();
+ }
+
+ @Path("/")
+ public TemplateInstance index() {
+ return Templates.index();
+ }
+}A Controller is the logic class that binds URIs to actions and views. They are almost like regular
+JAX-RS endpoints,
+but you opt-in to special magic by extending the Controller class, which gives you nice methods,
+but also super friendly behaviour.
In this Controller we declare a Qute template, and map the / to it.
We can then define the main page in src/main/resources/templates/Application/index.html:
<!DOCTYPE html>
+<html lang="en">
+ <body>
+ Hello, World!
+ </body>
+</html>Now if you navigate to your application at http://localhost:8080 you will see Hello, World! rendered.
Web Framework Security guideRenarde can help you deal with security and user registration, either manually, using OIDC, or
+a mix of both.
Renarde comes with built-in support for Cross-Site Request Forgery (CSRF) protection,
+via the (already imported) quarkus-csrf-reactive module dependency.
To be safe, make sure that all your GET, HEAD and OPTIONS endpoints do not alter application state, and
+always include a CSRF token to your POST, PUT, DELETE (and other) endpoints. On your endpoint side, you
+do not need to do anything, we will check the token for you. But on your form end, you need to include the CSRF
+token, which can be done by using the {#form/} tag to create your form, or the
+{#authenticityToken/} to generate a hidden form element with the token, or by writing
+the form element manually:
<input type="hidden" name="{inject:csrf.parameterName}" value="{inject:csrf.token}"/>When writing tests, if you are using @QuarkusTest and
+RestAssured to test endpoints secured with CSRF protection,
+you will need to make sure you obtain and pass the appropriate CSRF token to your POST (and similar) endpoints.
There are two ways to deal with this.
+Import the quarkus-renarde-test module:
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-test</artifactId>
+ <version>3.0.9</version>
+ <scope>test</scope>
+</dependency>This will automatically register a JUnit Extension
+which makes sure RestAssured has a filter set up for each of your
+test methods, which will pass a generated valid CSRF token as both cookie and form parameter. Not that this is only
+done for POST (and related) methods which contain either no body, or a form body
+(url-encoded or multipart).
| + + | +
+you can use the @DisableCSRFFilter annotation on your test method or class in order to disable the CSRF
+filter. For example, if you want to handle it yourself.
+ |
+
You will need to obtain a CSRF token from any GET endpoint, and resend it as part of your POST requests:
@Test
+public void test() {
+ String csrfToken = RestAssured
+ .given()
+ .when()
+ .get("/Application/index")
+ .then()
+ .extract().cookie("csrf-token");
+ // now we can call POST
+ RestAssured
+ .given()
+ .when()
+ // for CSRF protection
+ .cookie("csrf-token", csrfToken)
+ .param("csrf-token", csrfToken)
+ // for your actual endpoint
+ .param("param", "value")
+ .post("/Application/doSomething")
+ .then()
+ .statusCode(200);
+}In order to handle your own authentication by storing users in your database, you can use JWT tokens.
+Start with importing the renarde-security module:
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-security</artifactId>
+ <version>3.0.9</version>
+</dependency>And set those configuration values:
+# Must be set to get proper error reporting
+quarkus.http.auth.proactive=falseYour entity should extend RenardeUser and can look like this:
package model;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+@Table(name = "user_table")
+public class User extends PanacheEntity implements RenardeUser {
+
+ @Column(nullable = false)
+ public String email;
+ @Column(unique = true)
+ public String userName;
+ public String password;
+ public String firstName;
+ public String lastName;
+ public boolean isAdmin;
+
+ @Column(unique = true)
+ public String confirmationCode;
+
+ @Column(nullable = false)
+ @Enumerated(EnumType.STRING)
+ public UserStatus status;
+
+ public boolean isRegistered(){
+ return status == UserStatus.REGISTERED;
+ }
+
+ @Override
+ public Set<String> getRoles() {
+ Set<String> roles = new HashSet<>();
+ if(isAdmin) {
+ roles.add("admin");
+ }
+ return roles;
+ }
+
+ @Override
+ public String getUserId() {
+ return userName;
+ }
+
+ //
+ // Helpers
+
+ public static User findUnconfirmedByEmail(String email) {
+ return find("LOWER(email) = ?1 AND status = ?2", email.toLowerCase(), UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+
+ public static User findRegisteredByUserName(String username) {
+ return find("LOWER(userName) = ?1 AND status = ?2", username.toLowerCase(), UserStatus.REGISTERED).firstResult();
+ }
+
+ public static User findByUserName(String username) {
+ return find("LOWER(userName) = ?1", username.toLowerCase()).firstResult();
+ }
+
+ public static User findForContirmation(String confirmationCode) {
+ return find("confirmationCode = ?1 AND status = ?2", confirmationCode, UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+}Now tell Renarde how to map the JWT cookies to your user model by implementing RenardeUserProvider:
package util;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkiverse.renarde.security.RenardeUserProvider;
+import model.User;
+
+@ApplicationScoped
+public class MySecuritySetup implements RenardeUserProvider {
+
+ @Inject
+ RenardeSecurity security;
+
+ @Override
+ public RenardeUser findUser(String tenantId, String id) {
+ return User.findByUserName(id);
+ }
+}With this, Renarde will make sure that we produce a user named bean containing the current user if there is a
+logged-in user. You can then use it in your views with inject:user or by injecting it in
+your endpoints.
Renarde also provides a ControllerWithUser class which you can extend to access the current user for all controllers
+that need a user.
Now you can write your login and registration page like this:
+{#include main.html }
+{#title}Login{/title}
+
+<div class="row">
+ <div class="col-md-5">
+ {#form uri:Login.manualLogin()}
+ <fieldset>
+ <legend>Login</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName"/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Login</button>
+ </fieldset>
+ {/form}
+ </div>
+ <div class="col-md-5">
+ {#form uri:Login.register()}
+ <fieldset>
+ <legend>Register</legend>
+ {#formElement name="email" label="Email"}
+ {#input name="email"/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Register</button>
+ </fieldset>
+ {/form}
+ </div>
+</div>
+
+{/include}As for your registration page, it can look like this:
+{#include main.html }
+{#title}Complete registration{/title}
+
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName" value=newUser.userName/}
+ {/formElement}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName" value=newUser.firstName/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName" value=newUser.lastName/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}
+{/include}And your login and registration endpoint can look like this to handle user registration and login:
+package rest;
+
+import java.util.UUID;
+
+import jakarta.inject.Inject;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.core.NewCookie;
+import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.Response.ResponseBuilder;
+
+import org.hibernate.validator.constraints.Length;
+import org.jboss.resteasy.reactive.RestForm;
+import org.jboss.resteasy.reactive.RestQuery;
+
+import email.Emails;
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.router.Router;
+import io.quarkiverse.renarde.util.StringUtils;
+import io.quarkus.elytron.security.common.BcryptUtil;
+import io.quarkus.qute.CheckedTemplate;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkus.security.Authenticated;
+import model.User;
+import model.UserStatus;
+
+public class Login extends ControllerWithUser<User> {
+
+ @Inject
+ RenardeSecurity security;
+
+ @CheckedTemplate
+ static class Templates {
+ public static native TemplateInstance login();
+ public static native TemplateInstance register(String email);
+ public static native TemplateInstance confirm(User newUser);
+ public static native TemplateInstance logoutFirst();
+ public static native TemplateInstance welcome();
+ }
+
+ /**
+ * Login page
+ */
+ public TemplateInstance login() {
+ return Templates.login();
+ }
+
+ /**
+ * Welcome page at the end of registration
+ */
+ @Authenticated
+ public TemplateInstance welcome() {
+ return Templates.welcome();
+ }
+
+ /**
+ * Manual login form
+ */
+ @POST
+ public Response manualLogin(@NotBlank @RestForm String userName,
+ @NotBlank @RestForm String password) {
+ if(validationFailed()) {
+ login();
+ }
+ User user = User.findRegisteredByUserName(userName);
+ if(user == null
+ || !BcryptUtil.matches(password, user.password)) {
+ validation.addError("userName", "Invalid username/pasword");
+ prepareForErrorRedirect();
+ login();
+ }
+ NewCookie cookie = security.makeUserCookie(user);
+ return Response.seeOther(Router.getURI(Application::index)).cookie(cookie).build();
+ }
+
+
+ /**
+ * Manual registration form, sends confirmation email
+ */
+ @POST
+ public TemplateInstance register(@RestForm @NotBlank @Email String email) {
+ if(validationFailed())
+ login();
+ User newUser = User.findUnconfirmedByEmail(email);
+ if(newUser == null) {
+ newUser = new User();
+ newUser.email = email;
+ newUser.status = UserStatus.CONFIRMATION_REQUIRED;
+ newUser.confirmationCode = UUID.randomUUID().toString();
+ newUser.persist();
+ }
+ // send the confirmation code again
+ Emails.confirm(newUser);
+ return Templates.register(email);
+ }
+
+
+ /**
+ * Confirmation form, once email is verified, to add user info
+ */
+ public TemplateInstance confirm(@RestQuery String confirmationCode){
+ checkLogoutFirst();
+ User newUser = checkConfirmationCode(confirmationCode);
+ return Templates.confirm(newUser);
+ }
+
+ private void checkLogoutFirst() {
+ if(getUser() != null) {
+ logoutFirst();
+ }
+ }
+
+ /**
+ * Link to logout page
+ */
+ public TemplateInstance logoutFirst() {
+ return Templates.logoutFirst();
+ }
+
+ private User checkConfirmationCode(String confirmationCode) {
+ // can't use error reporting as those are query parameters and not form fields
+ if(StringUtils.isEmpty(confirmationCode)){
+ flash("message", "Missing confirmation code");
+ flash("messageType", "error");
+ redirect(Application.class).index();
+ }
+ User user = User.findForContirmation(confirmationCode);
+ if(user == null){
+ flash("message", "Invalid confirmation code");
+ flash("messageType", "error");
+ redirect(Application.class).index();
+ }
+ return user;
+ }
+
+ @POST
+ public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank String userName,
+ @RestForm @Length(min = 8) String password,
+ @RestForm @Length(min = 8) String password2,
+ @RestForm @NotBlank String firstName,
+ @RestForm @NotBlank String lastName) {
+ checkLogoutFirst();
+ User user = checkConfirmationCode(confirmationCode);
+
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ validation.required("password", password);
+ validation.required("password2", password2);
+ validation.equals("password", password, password2);
+
+ if(User.findRegisteredByUserName(userName) != null)
+ validation.addError("userName", "User name already taken");
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ user.userName = userName;
+ user.password = BcryptUtil.bcryptHash(password);
+ user.firstName = firstName;
+ user.lastName = lastName;
+ user.confirmationCode = null;
+ user.status = UserStatus.REGISTERED;
+
+ ResponseBuilder responseBuilder = Response.seeOther(Router.getURI(Login::welcome));
+ NewCookie cookie = security.makeUserCookie(user);
+ responseBuilder.cookie(cookie);
+ return responseBuilder.build();
+ }
+}You can now use the @Authenticated and @RolesAllowed("admin") annotations on your endpoints.
In DEV mode, your private/public keys will be generated for you at startup if they do not exist and +are not specified. Cleaning your project will remove those keys, so previous JWT tokens won’t be valid +anymore on restart.
+In production environments you will need to generate and specify your private and public keys using the following +commands:
+$ openssl genrsa -out rsaPrivateKey.pem 2048
+$ openssl rsa -pubout -in rsaPrivateKey.pem -out src/main/resources/publicKey.pem
+$ openssl pkcs8 -topk8 -nocrypt -inform pem -in rsaPrivateKey.pem -outform pem -out src/main/resources/privateKey.pemYou can then point to those files in your application.properties Quarkus configuration:
mp.jwt.verify.publickey.location=publicKey.pem
+mp.jwt.decrypt.key.location=privateKey.pem
+smallrye.jwt.sign.key.location=privateKey.pem
+smallrye.jwt.encrypt.key.location=publicKey.pem
+
+quarkus.native.resources.includes=publicKey.pem
+quarkus.native.resources.includes=privateKey.pemOIDC (Open ID Connect) is a way to delegate user login to external services, such as:
+If you use OIDC, you can skip the email validation phase, and avoid storing passwords for your users, but you may +likely still need to store a user representation in your data store, and associate it to the external identity provider +using the provider name and its own ID.
+The recommended set up is to place each provider in its own tenant, and disable the default tenant if you want to leave +it free for the manual user registration and authentication we already covered:
+# Google
+quarkus.oidc.google.provider=google
+quarkus.oidc.google.client-id=SECRET
+quarkus.oidc.google.credentials.secret=SECRET
+
+# Github
+quarkus.oidc.github.provider=github
+quarkus.oidc.github.client-id=SECRET
+quarkus.oidc.github.credentials.secret=SECRET
+
+# Manual context
+quarkus.oidc.manual.tenant-enabled=false
+
+# Default is just disabled
+quarkus.oidc.tenant-enabled=false
+
+# Get rid of keycloak dev services
+quarkus.keycloak.devservices.enabled=false
+
+# Must be set to get proper error reporting
+quarkus.http.auth.proactive=falseMake sure you import the renarde-oidc module in your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-oidc</artifactId>
+ <version>3.0.9</version>
+</dependency>We first adapt our User model to handle OIDC users by adding tenantId and authId fields:
package model;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkus.hibernate.orm.panache.PanacheEntity;
+
+@Entity
+@Table(name = "user_table", uniqueConstraints = @UniqueConstraint(columnNames = {"tenantId", "authId"}))
+public class User extends PanacheEntity implements RenardeUser {
+
+ @Column(nullable = false)
+ public String email;
+ @Column(unique = true)
+ public String userName;
+ public String password;
+ public String firstName;
+ public String lastName;
+ public boolean isAdmin;
+
+ @Column(unique = true)
+ public String confirmationCode;
+
+ public String tenantId;
+ public String authId;
+
+ @Column(nullable = false)
+ @Enumerated(EnumType.STRING)
+ public UserStatus status;
+
+ public boolean isRegistered(){
+ return status == UserStatus.REGISTERED;
+ }
+
+ @Override
+ public Set<String> getRoles() {
+ Set<String> roles = new HashSet<>();
+ if(isAdmin) {
+ roles.add("admin");
+ }
+ return roles;
+ }
+
+ @Override
+ public String getUserId() {
+ return userName;
+ }
+
+ public boolean isOidc() {
+ return tenantId != null;
+ }
+
+ //
+ // Helpers
+
+ public static User findUnconfirmedByEmail(String email) {
+ return find("LOWER(email) = ?1 AND status = ?2", email.toLowerCase(), UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+
+ public static User findRegisteredByUserName(String username) {
+ return find("LOWER(userName) = ?1 AND status = ?2", username.toLowerCase(), UserStatus.REGISTERED).firstResult();
+ }
+
+ public static User findByUserName(String username) {
+ return find("LOWER(userName) = ?1", username.toLowerCase()).firstResult();
+ }
+
+ public static User findByAuthId(String tenantId, String authId) {
+ return find("tenantId = ?1 AND authId = ?2", tenantId, authId).firstResult();
+ }
+
+ public static User findForContirmation(String confirmationCode) {
+ return find("confirmationCode = ?1 AND status = ?2", confirmationCode, UserStatus.CONFIRMATION_REQUIRED).firstResult();
+ }
+}Now you need to provide implementations of RenardeUserProvider and RenardeOidcHandler which you can group:
package util;
+
+import java.net.URI;
+import java.util.UUID;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+import jakarta.transaction.Transactional;
+import jakarta.ws.rs.core.Response;
+
+import io.quarkiverse.renarde.oidc.RenardeOidcHandler;
+import io.quarkiverse.renarde.oidc.RenardeOidcSecurity;
+import io.quarkiverse.renarde.security.RenardeSecurity;
+import io.quarkiverse.renarde.security.RenardeUser;
+import io.quarkiverse.renarde.security.RenardeUserProvider;
+import io.quarkiverse.renarde.router.Router;
+import io.quarkiverse.renarde.util.Flash;
+import io.quarkiverse.renarde.util.RedirectException;
+import model.User;
+import model.UserStatus;
+import rest.Application;
+import rest.Login;
+
+@ApplicationScoped
+public class MySecuritySetup implements RenardeUserProvider, RenardeOidcHandler {
+
+ @Inject
+ RenardeSecurity security;
+
+ @Inject
+ RenardeOidcSecurity oidcSecurity;
+
+ @Inject
+ Flash flash;
+
+ /**
+ * This allows us to map tenant/id to our users: manually or via OIDC
+ */
+ @Override
+ public RenardeUser findUser(String tenantId, String id) {
+ if(tenantId == null || tenantId.equals("manual")) {
+ return User.findByUserName(id);
+ } else {
+ return User.findByAuthId(tenantId, id);
+ }
+ }
+
+ /**
+ * This will be called on every successful OIDC authentication,
+ * be it a first-time user registration, or existing user login
+ */
+ @Transactional
+ @Override
+ public void oidcSuccess(String tenantId, String authId) {
+ User user = User.findByAuthId(tenantId, authId);
+ URI uri;
+ if(user == null) {
+ // registration
+ user = new User();
+ user.tenantId = tenantId;
+ user.authId = authId;
+
+ user.email = oidcSecurity.getOidcEmail();
+ user.firstName = oidcSecurity.getOidcFirstName();
+ user.lastName = oidcSecurity.getOidcLastName();
+ user.userName = oidcSecurity.getOidcUserName();
+
+ user.status = UserStatus.CONFIRMATION_REQUIRED;
+ user.confirmationCode = UUID.randomUUID().toString();
+ user.persist();
+
+ // go to registration
+ uri = Router.getURI(Login::confirm, user.confirmationCode);
+ } else if(!user.isRegistered()) {
+ // user exists, but not fully registered yet
+ // go to registration
+ uri = Router.getURI(Login::confirm, user.confirmationCode);
+ } else {
+ // regular login
+ uri = Router.getURI(Application::index);
+ }
+ throw new RedirectException(Response.seeOther(uri).build());
+ }
+
+ /**
+ * This will be called if the existing user has a valid OIDC session,
+ * and attemps to login again, so we check if the user exists, and is
+ * fully registered.
+ */
+ @Override
+ public void loginWithOidcSession(String tenantId, String authId) {
+ RenardeUser user = findUser(tenantId, authId);
+ // old cookie, no such user
+ if(user == null) {
+ flash.flash("message", "Invalid user: "+authId);
+ throw new RedirectException(security.makeLogoutResponse());
+ }
+ // redirect to registration
+ URI uri;
+ if(!user.isRegistered()) {
+ uri = Router.getURI(Login::confirm, ((User)user).confirmationCode);
+ } else {
+ flash.flash("message", "Already logged in");
+ uri = Router.getURI(Application::index);
+ }
+ throw new RedirectException(Response.seeOther(uri).build());
+ }
+}We have to adapt our registration page to account for users coming in from OIDC, by skipping the password +if the user is an OIDC user:
+{#include main.html }
+{#title}Complete registration{/title}
+
+{#form uri:Login.complete(newUser.confirmationCode)}
+
+<fieldset>
+ <legend>Complete registration for {newUser.email}</legend>
+ {#formElement name="userName" label="User Name"}
+ {#input name="userName" value=newUser.userName/}
+ {/formElement}
+ {#if !newUser.authId}
+ {#formElement name="password" label="Password"}
+ {#input name="password" type="password"/}
+ {/formElement}
+ {#formElement name="password2" label="Password Confirmation"}
+ {#input name="password2" type="password"/}
+ {/formElement}
+ {/if}
+ {#formElement name="firstName" label="First Name"}
+ {#input name="firstName" value=newUser.firstName/}
+ {/formElement}
+ {#formElement name="lastName" label="Last Name"}
+ {#input name="lastName" value=newUser.lastName/}
+ {/formElement}
+ <button type="submit" class="btn btn-primary">Complete registration</button>
+</fieldset>
+
+{/form}
+{/include}And the corresponding controller:
+ @POST
+ public Response complete(@RestQuery String confirmationCode,
+ @RestForm @NotBlank String userName,
+ @RestForm @Length(min = 8) String password,
+ @RestForm @Length(min = 8) String password2,
+ @RestForm @NotBlank String firstName,
+ @RestForm @NotBlank String lastName) {
+ checkLogoutFirst();
+ User user = checkConfirmationCode(confirmationCode);
+
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ // is it OIDC?
+ if(!user.isOidc()) {
+ validation.required("password", password);
+ validation.required("password2", password2);
+ validation.equals("password", password, password2);
+ }
+
+ if(User.findRegisteredByUserName(userName) != null)
+ validation.addError("userName", "User name already taken");
+ if(validationFailed())
+ confirm(confirmationCode);
+
+ user.userName = userName;
+ if(!user.isOidc()) {
+ user.password = BcryptUtil.bcryptHash(password);
+ }
+ user.firstName = firstName;
+ user.lastName = lastName;
+ user.confirmationCode = null;
+ user.status = UserStatus.REGISTERED;
+
+ ResponseBuilder responseBuilder = Response.seeOther(Router.getURI(Login::welcome));
+ if(!user.isOidc()) {
+ NewCookie cookie = security.makeUserCookie(user);
+ responseBuilder.cookie(cookie);
+ }
+ return responseBuilder.build();
+ }And finally we can add the OIDC login options to the login page:
+{#include main.html }
+{#title}Login{/title}
+
+<div class="row">
+ <div class="col-md-2">
+ <fieldset>
+ <legend>Login/Register</legend>
+ <div class="d-grid gap-2">
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('github')}" role="button"><img src="/images/signin-github.svg" height="16px" style="vertical-align: text-top"/> GitHub</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('google')}" role="button"><img src="/images/signin-google.svg" height="16px" style="vertical-align: text-top"/> Google</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('microsoft')}" role="button"><img src="/images/signin-microsoft.svg" height="16px" style="vertical-align: text-top"/> Microsoft</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('facebook')}" role="button"><img src="/images/signin-facebook.svg" height="16px" style="vertical-align: text-top"/> Facebook</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('apple')}" role="button"><img src="/images/signin-apple.svg" height="16px" style="vertical-align: text-top"/> Apple</a>
+ <a class="btn btn-block btn-light" href="{uri:RenardeOidcController.loginUsingOidc('twitter')}" role="button"><img src="/images/signin-twitter.svg" height="16px" style="vertical-align: text-top"/> Twitter</a>
+ </div>
+ </fieldset>
+ </div>
+ <-- ... Manual login and registration ... -->
+</div>
+
+{/include}In order to set up OIDC for Github you need to create a new OAuth application in your GitHub developer settings:
+
+Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to http://localhost:8080/_renarde/security/oidc-success
+(if you intend to test this using the Quarkus DEV mode).
Now click on Register application and you’ll be shown your application page:
+You need to click on Generate a new client secret, confirm your credentials, and write down
+your Client ID and Client secret (especially that one, because you will not be able to see it again
+later from that page, but you can always recreate one, do don’t worry too much):
+Now add the following configuration to your application.properties:
quarkus.oidc.github.provider=github
+quarkus.oidc.github.client-id=<Client ID>
+quarkus.oidc.github.credentials.secret=<Secret>In order to set up OIDC for Google you need to create a new project in your Google Cloud Platform console:
+Pick a project name and click on CREATE.
+Now make sure you select your project in the top selector, and click on the left-hand bar menu on APIs and Services > OAuth consent screen:
+Select External to authorise any Google user to log in to your application and press CREATE:
+Now you can fill in your application name, your support email, your developer contact information and press SAVE AND CONTINUE:
+Do not add any scopes on the next page, and press SAVE AND CONTINUE:
+Do not add any test user on the next page, and press SAVE AND CONTINUE:
+Click on the top menu CREATE CREDENTIALS > OAuth client ID:
+Select Web application as Application type, and add http://localhost:8080/_renarde/security/oidc-success in
+the Authorised redirect URIs list, then press CREATE:
+Copy your Client ID and Client Secret:
+
+You can now configure your application.properties:
quarkus.oidc.google.provider=google
+quarkus.oidc.google.client-id=<Client ID>
+quarkus.oidc.google.credentials.secret=<Secret>In order to set up OIDC for Microsoft you need to go to your Microsoft Azure Portal,
+and search for Azure Active Directory, then click on it:
+Once there, on the left side under Manage, click on App registrations then click on New registration:
+Fill in your application name, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) to allow anyone to log in, and add a Web Redirect URI as http://localhost:8080/_renarde/security/oidc-success,
+then click on Register:
+On that resulting page, copy the Client Id (under Application (client) ID, then click on Add a certificate or secret:
+Now, under Client secrets (0), click on New client secret:
+Click on Add in that dialog without changing anything:
+On the resulting page, copy your Secret ID:
+You can now configure your application.properties:
quarkus.oidc.microsoft.provider=microsoft
+quarkus.oidc.microsoft.client-id=<Client ID>
+quarkus.oidc.microsoft.credentials.secret=<Secret>In order to set up OIDC for Apple you need to create a developer account, and sign up for the 99€/year program, but you cannot test your application on localhost like most other OIDC providers:
+you will need to run it over https and make it publicly accessible, so for development purposes
+you may want to use a service such as ngrok.
Go to Create a new identifier and press +
+Dont touch anything, keep App IDs selected, and press Continue:
+Dont touch anything, keep App selected, and press Continue:
+Enter a description and a Bundle ID (use your application package name):
+
+Then scroll down to find the Sign in with Apple Capability, select it, and press Continue:
+Write down your App ID Prefix, then press Register:
+Back on the Identifiers page, press +:
+Select Service IDs and press Continue:
+Enter a description and Bundle ID (use your application package name), then press Continue:
+Now press Register:
+Back on the service list, click on your newly created service:
+
+Enable Sign in with Apple and press Configure:
+Add your domain and return URL (set to <host>/_renarde/security/oidc-success) and press Next:
+Now press Done:
+Now press Continue:
+And now press Save:
+Go to the Keys page on the left menu, and press +:
+Fill in a key name, enable Sign in with Apple, and press Configure:
+Select your Primary App ID and press Save:
+Back on the key page, press Continue:
+Now press Register:
+Write down your Key ID, download your key and save it to your Quarkus application in src/main/resources/AuthKey_<KEYID>.p8:
+You can now configure your application.properties:
quarkus.oidc.apple.provider=apple
+quarkus.oidc.apple.client-id=<Bundle ID>
+quarkus.oidc.apple.credentials.jwt.key-file=AuthKey_<Key ID>.p8
+quarkus.oidc.apple.credentials.jwt.token-key-id=<Key ID>
+quarkus.oidc.apple.credentials.jwt.issuer=<App ID Prefix>
+quarkus.oidc.apple.credentials.jwt.subject=<Bundle ID}Facebook you will not be let you test your application on localhost like most other OIDC providers:
+you will need to run it over https and make it publicly accessible, so for development purposes
+you may want to use a service such as ngrok.
In order to set up OIDC for Facebook start by Creating an application, select None as an app type, and press Next:
+Now enter an application name, and contact email, and press Create app:
+On the app page, click Set up on the Facebook login product:
+Quick the Quickstarts page and click on Facebook login > Settings on the left menu:
+Enter your Redirect URIs (set to <host>/_renarde/security/oidc-success) and press Save changes:
+Now go to Settings > Basic on the left hand menu, and write down your App ID and App secret:
+You can now configure your application.properties:
quarkus.oidc.facebook.provider=facebook
+quarkus.oidc.facebook.client-id=<App ID>
+quarkus.oidc.facebook.credentials.secret=<App secret>In order to set up OIDC for Spotify start by Creating an app, enter an app name,
+and http://localhost:8080/_renarde/security/oidc-success as Redirect URI, check the checkbox accepting the terms,
+and press Save:
+Now click on Settings:
+And click on View client secret in order to reveal your secret:
+Now copy your Client ID and Client secret into your application.properties:
quarkus.oidc.spotify.provider=spotify
+quarkus.oidc.spotify.client-id=<Client ID>
+quarkus.oidc.spotify.credentials.secret=<Client Secret>You can use Twitter for OIDC login, but at the moment, it restricts access to the user’s email, which means you +will have to obtain it and verify it yourself.
+In order to set up OIDC for Twitter start by Creating a project, enter a project name, and press Next:
+Enter a use case, and press Next:
+Enter a project description, and press Next:
+Now enter an application name, and press Next:
+Write down your keys, because they will not be displayed again, and press App Settings:
+Navigate down to the User authentication settings section and press Set up:
+Check the OAuth 2.0 check box:
+Select Web App as application type, then fill in your application details (use <host>/_renarde/security/oidc-success
+for the Callback URI).
| + + | +
+Twitter doesn’t require https usage in practice, but won’t accept your Website URL without it, so
+you can still use ngrok for it.
+ |
+
Now press Save:
+You can now copy your Client ID and Client Secret and press Done:
+You can now configure your application.properties:
quarkus.oidc.twitter.provider=twitter
+quarkus.oidc.twitter.client-id=<Client ID>
+quarkus.oidc.twitter.credentials.secret=<Client Secret>As soon as you integrate OIDC providers in your application, testing them becomes problematic, +because you probably don’t want to hit those external OIDC systems from your tests. But you still +want to test that your integration works well, and make it as fast as possible.
+Renarde provides you with custom test resources +that will start mock OIDC providers that you can use in place of the real online OIDC providers. All you need to +do is import this module:
+<dependency>
+ <groupId>io.quarkiverse.renarde</groupId>
+ <artifactId>quarkus-renarde-oidc-tests</artifactId>
+ <version>3.0.9</version>
+ <scope>test</scope>
+</dependency>And place one of these annotations on your test resource:
+| Annotation | +Role | +
|---|---|
|
+Starts a mock Apple OIDC provider |
+
|
+Starts a mock Facebook OIDC provider |
+
|
+Starts a mock Github OIDC provider |
+
|
+Starts a mock Google OIDC provider |
+
|
+Starts a mock Microsoft OIDC provider |
+
|
+Starts a mock Spotify OIDC provider |
+
|
+Starts a mock Twitter OIDC provider |
+
All these mock OIDC providers will automatically log you in for a single fixed user with the following +properties:
+| Provider | +TenantId | +AuthId | +Username | +First name | +Last name | +|
|---|---|---|---|---|---|---|
Apple |
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+|
Github |
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+|
Microsoft |
+
|
+
|
+
|
+
|
+
|
+
|
+
Spotify |
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
This extension provides support for Scala 3 in Quarkus.
+It uses the scala3-interfaces library to avoid user lock-in to any specific version of the Scala 3 compiler (Dotty).
+Instead, the reflection-based API is used and compilation is done by invoking the compiler version the user has installed from the runtime classpath.
For more information and background context on this, there are notes in the Scala3CompilationProvider.java file.
Additionally, passing compiler flags when in Dev Mode is supported through the use of an environment variable (QUARKUS_SCALA3_COMPILER_ARGS) which allows you to mirror your existing Maven/Gradle compilation configuration.
++++ ++
++ ++ + ++At the time of publishing, support for Scala 3 in Gradle is dependent on a not-yet-merged PR. + +
buildscript {
+ repositories {
+ mavenLocal()
+ mavenCentral()
+ }
+ dependencies {
+ classpath "ch.epfl.scala:gradle-bloop_2.12:1.4.8-106-8722ebfd"
+ }
+}
+
+plugins {
+ id "java"
+ id "scala"
+ id "io.quarkus"
+}
+
+// Bloop plugin uses old DSL -- MUST be applied like this
+apply plugin: "bloop"
+// This configuration dependent on the following PR being merged into bloop, can be removed after merge
+// https://github.com/scalacenter/bloop/pull/1548
+bloop {
+ stdLibName = "scala3-library_3"
+}
+
+repositories {
+ mavenCentral()
+ mavenLocal()
+}
+
+VERSIONS = [
+ SCALA3: "3.0.0",
+ QUARKUS_SCALA3: "0.0.1"
+]
+
+dependencies {
+ implementation "org.scala-lang:scala3-compiler_3:$VERSIONS.SCALA3"
+ implementation "io.quarkiverse.scala:quarkus-scala3:$VERSIONS.QUARKUS_SCALA3"
+
+ // Quarkus comes with Scala 2 distributed in it's Bill-of-Materials unfortunately
+ // It's Scala 2.12.13, which is not ABI compatible -- With Scala 3, we need to exclude this entirely
+ implementation(enforcedPlatform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}")) {
+ exclude group: 'org.scala-lang', module: 'scala-library'
+ }
+ implementation "io.quarkus:quarkus-arc"
+ implementation "io.quarkus:quarkus-resteasy-reactive"
+
+ testImplementation "io.quarkus:quarkus-junit5"
+ testImplementation "io.rest-assured:rest-assured"
+}
+
+group = "org.hasura"
+version = "1.0.0-SNAPSHOT"
+
+java {
+ sourceCompatibility = JavaVersion.VERSION_16
+ targetCompatibility = JavaVersion.VERSION_16
+}
+
+tasks.withType(ScalaCompile) {
+ scalaCompileOptions.additionalParameters = [
+ "-feature",
+ "-explain",
+ "-Ysafe-init",
+ "-Xsemanticdb"
+ ]
+}
+
+compileJava {
+ options.encoding = 'UTF-8'
+ options.compilerArgs << '-parameters'
+}
+
+compileTestJava {
+ options.encoding = 'UTF-8'
+}If you want to use this extension, you need to add the io.quarkiverse.scala:quarkus-scala3 extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.scala</groupId>
+ <artifactId>quarkus-scala3</artifactId>
+ <version>0.0.1<version>
+</dependency>Then, you will need to install the Scala 3 compiler, the Scala Maven plugin, and to fix an odd bug with the way that the Scala 3 compiler Maven dependencies are resolved.
+Due to Scala 2 version in upstream Quarkus BOM, the wrong version of scala-library (a transitive dependency: scala3-compiler_3 -> scala3-library_3 -> scala-library) is resolved.
This causes binary incompatibilities — and Scala to break. In order to fix this, you just need to manually align the version of scala-library to the one listed as used by the version of scala3-library_3 that’s the same as the scala3-compiler_3 version.
So for scala3-compiler_3 = 3.0.0, then scala3-library_3 = 3.0.0, and we check the scala-library version it uses:
Here, we can see that it was compiled with 2.13.5 in it’s dependencies. So that’s what we set in ours:
<properties>
+ <scala-maven-plugin.version>4.5.3</scala-maven-plugin.version>
+ <scala.version>3.0.0</scala.version>
+ <scala-library.version>2.13.5</scala-library.version>
+</properties>
+
+<dependencies>
+ <!-- Scala Dependencies -->
+ <dependency>
+ <groupId>org.scala-lang</groupId>
+ <artifactId>scala3-compiler_3</artifactId>
+ <version>${scala.version}</version>
+ </dependency>
+ <dependency>
+ <!-- Version manually aligned to scala3-library_3:3.0.0 dependency -->
+ <groupId>org.scala-lang</groupId>
+ <artifactId>scala-library</artifactId>
+ <version>${scala-library.version}</version>
+ </dependency>
+</dependencies>
+
+<build>
+ <sourceDirectory>src/main/scala</sourceDirectory>
+ <testSourceDirectory>src/test/scala</testSourceDirectory>
+
+ <!-- REST OF CONFIG -->
+
+ <plugin>
+ <groupId>net.alchim31.maven</groupId>
+ <artifactId>scala-maven-plugin</artifactId>
+ <version>${scala-maven-plugin.version}</version>
+ <executions>
+ <execution>
+ <id>scala-compile-first</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>add-source</goal>
+ <goal>compile</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>scala-test-compile</id>
+ <phase>process-test-resources</phase>
+ <goals>
+ <goal>add-source</goal>
+ <goal>testCompile</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <scalaVersion>${scala.version}</scalaVersion>
+ <!-- Some solid defaults, change if you like -->
+ <args>
+ <arg>-deprecated</arg>
+ <arg>-explain</arg>
+ <arg>-feature</arg>
+ <arg>-Ysafe-init</arg>
+ </args>
+ </configuration>
+ </plugin>
+</build>Finally, the last thing you want to do is make sure that you mirror any compiler args you have set up when you run in Dev Mode.
+To do this, just run the dev command with a prefix of the environment variable set. The format is comma-delimited:
+QUARKUS_SCALA3_COMPILER_ARGS="-deprecated,-explain,-feature,-Ysafe-init" mvn quarkus:devYou might save this as a bash/powershell/batch script for convenience.
+JUnit requires tests to return type void. Scala functions which are not annotated with : Unit return type Scala.Nothing, rather than void.
+This means that tests such as the undiscoverable test below will never be detected by JUnit.
See this issue for more information:
+Please voice your support for a better developer experience around this behavior if it feels poor to you, by commenting on this issue:
+@QuarkusTest
+class MyTest:
+
+ @Test
+ def `undiscoverable test` =
+ assert(1 == 1)
+
+ @Test
+ def `discoverable test`: Unit =
+ assert(2 == 2)You probably want JSON support for case class and enum serialization. +There are two things you need to enable this, as of the time of writing:
+The standard Jackson Scala module
+An addon module from one of the Jackson Scala maintainers for Scala 3 enums that hasn’t made its way into the official module yet
+To set this up:
+Add the following to your dependencies
+<!-- JSON Serialization Dependencies -->
+<dependency>
+ <groupId>com.github.pjfanning</groupId>
+ <artifactId>jackson-module-scala3-enum_3</artifactId>
+ <version>2.12.3</version>
+</dependency>
+
+<dependency>
+ <groupId>com.fasterxml.jackson.module</groupId>
+ <artifactId>jackson-module-scala_2.13</artifactId>
+ <version>2.12.4</version>
+</dependency>Set up something like the below in your codebase:
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.module.scala.DefaultScalaModule
+import com.github.pjfanning.`enum`.EnumModule
+import io.quarkus.jackson.ObjectMapperCustomizer
+
+import javax.inject.Singleton
+
+// https://quarkus.io/guides/rest-json#jackson
+@Singleton
+class Scala3ObjectMapperCustomizer extends ObjectMapperCustomizer:
+ def customize(mapper: ObjectMapper): Unit =
+ // General Scala support
+ // https://github.com/FasterXML/jackson-module-scala
+ mapper.registerModule(DefaultScalaModule)
+ // Suport for Scala 3 Enums
+ // https://github.com/pjfanning/jackson-module-scala3-enum
+ mapper.registerModule(EnumModule)The API is usable like this:
+import com.fasterxml.jackson.databind.ObjectMapper
+import io.quarkus.test.junit.QuarkusTest
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.{DisplayName, Test}
+
+import javax.inject.Inject
+import scala.collection.JavaConverters.*
+
+
+enum AnEnum:
+ case A extends AnEnum
+ case B extends AnEnum
+
+case class Other(foo: String)
+case class Something(name: String, someEnum: AnEnum, other: Other)
+
+@QuarkusTest
+class Scala3ObjectMapperCustomizerTest:
+
+ @Inject
+ var objectMapper: ObjectMapper = null
+
+ @Test
+ def `Jackson ObjectMapper can parse Scala 3 members`:
+ val sampleSomethingJSON: String = """
+ {
+ "name": "My Something",
+ "someEnum": "A",
+ "other": {
+ "foo": "bar"
+ }
+ }
+ """
+ val parsed = objectMapper.readValue[Something](sampleSomethingJSON, classOf[Something])
+ assertEquals(parsed.name, "My Something")
+ assertEquals(parsed.someEnum, AnEnum.A)
+ assertEquals(parsed.other.foo, "bar")If you weren’t aware, Kotlin has a very nice DSL module for rest-assured that makes it far more ergonomic. +With some finagling, it’s possible to replicate this (mostly) in Scala.
+Here’s a working outline that supports everything but .extract() — a PR or issue comment adding the .extract() case is much-welcomed:
Acknowledgements here should be given to Christopher Davenport from the Scala Discord for sharing the outline of how this sort of API could be written
+import io.restassured.RestAssured.*
+import io.restassured.internal.{ResponseSpecificationImpl, ValidatableResponseImpl}
+import io.restassured.response.{ExtractableResponse, Response, ValidatableResponse}
+import io.restassured.specification.{RequestSender, RequestSpecification, ResponseSpecification}
+
+class GivenConstructor(givenBlock: RequestSpecification => RequestSpecification):
+ def When(whenBlock: RequestSpecification => Response): ExpectationConstructor =
+ ExpectationConstructor(givenBlock, whenBlock)
+
+ class ExpectationConstructor(
+ givenBlock: RequestSpecification => RequestSpecification,
+ whenBlock: RequestSpecification => Response
+ ):
+ def Then(validatable: ValidatableResponse => Unit) =
+ val appliedGiven: RequestSpecification = givenBlock.apply(`given`())
+ val appliedWhen: Response = whenBlock.apply(appliedGiven)
+ validatable.apply(appliedWhen.`then`())
+
+object Given:
+ def apply(givenBlock: RequestSpecification => RequestSpecification): GivenConstructor = GivenConstructor(givenBlock)
+
+def When(whenBlock: RequestSpecification => Response) =
+ def blankGiven(givenBlock: RequestSpecification): RequestSpecification = `given`()
+ Given(blankGiven).When(whenBlock)And the way it can be used, is like this:
+import io.quarkus.test.junit.QuarkusTest
+import org.hamcrest.CoreMatchers.`is`
+import org.acme.Given
+import org.junit.jupiter.api.{DisplayName, Test}
+
+@QuarkusTest
+class GreetingResourceTest:
+
+ @Test
+ def testDSL(): Unit =
+ Given {
+ _.params("something", "value")
+ }.When {
+ _.get("/hello").prettyPeek()
+ }.Then {
+ _.statusCode(200)
+ }While Quarkus is heavily centered around REST-easy annotations for endpoints (being Java-oriented), it also exposes the underlying Vert.x instance.
+You can use this to write route handlers which are much more functional-feeling, and the API is similar to that of Express.js
+I recommend this article by Clement Escoffier which covers this far more in-depth
+import io.quarkus.runtime.annotations.QuarkusMain
+import io.quarkus.runtime.{Quarkus, QuarkusApplication}
+import io.vertx.core.Vertx
+import io.vertx.ext.web.Router
+
+object Application:
+ def main(args: Array[String]): Unit =
+ Quarkus.run(classOf[Application], args*)
+
+@QuarkusMain
+class Application extends QuarkusApplication:
+ override def run(args: String*): Int =
+ val vertx = CDI.current().select(classOf[Vertx]).get()
+ val router = Router.router(vertx)
+ mkRoutes(router)
+ Quarkus.waitForExit()
+ 0
+
+def mkRoutes(router: Router) =
+ router.get("/hello").handler(ctx => {
+ ctx.response.end("world")
+ })
+ router.post("/file-upload").handler(ctx => {
+ ctx.fileUploads.foreach(it => {
+ // Handle file
+ })
+ ctx.response.end("Got files")
+ })Describe what the extension does here.
+If you want to use this extension, you need to add the io.quarkiverse.shardingsphere:quarkus-shardingsphere-jdbc extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.shardingsphere</groupId>
+ <artifactId>quarkus-shardingsphere-jdbc</artifactId>
+</dependency>The shardingsphere datasource could be configured in the application.properties file. just like
quarkus.datasource.ds_0.db-kind=h2
+quarkus.datasource.ds_0.username=sa
+quarkus.datasource.ds_0.jdbc.url=jdbc:h2:mem:ds_0
+
+quarkus.datasource.ds_1.db-kind=h2
+quarkus.datasource.ds_1.username=sa
+quarkus.datasource.ds_1.jdbc.url=jdbc:h2:mem:ds_1
+
+quarkus.datasource.db-kind=shardingsphere
+quarkus.datasource.jdbc.url=jdbc:shardingsphere:classpath:config.yamlAnd in config.yaml file, you can configure the shardingsphere datasource like this:
dataSources:
+ ds_0:
+ dataSourceClassName: io.quarkiverse.shardingsphere.jdbc.QuarkusDataSource
+ dsName: ds_0
+ ds_1:
+ dataSourceClassName: io.quarkiverse.shardingsphere.jdbc.QuarkusDataSource
+ dsName: ds_1The more sharding rules configuration, please refer to the shardingsphere official document: https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/configuration/yaml/
+if you want to work with Quarkus Hibernate ORM, please add the following configuration in application.properties file to set the quarkus.hibernate-orm.dialect explicitly:
quarkus.hibernate-orm.dialect=io.quarkus.hibernate.orm.runtime.dialect.QuarkusH2Dialect| + + | +
+The transaction type of backend datasource must be set to DISABLED in application.properties file, like this:
+ |
+
quarkus.datasource.ds_0.jdbc.transactions=DISABLED
+quarkus.datasource.ds_1.jdbc.transactions=DISABLEDConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
This guide explains how your Quarkus application can utilize OpenTracing to provide distributed tracing for +interactive web applications.
+| + + | +
+
+
+OpenTelemetry is the recommended approach to tracing and telemetry for Quarkus. +
+
+The SmallRye OpenTracing support is discontinued and this extension is not actively maintained. +If you are interested in maintaining this extension, please reach out to us in the GitHub issues of this extension. + |
+
To complete this guide, you need:
+Roughly 15 minutes
+An IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
+Apache Maven 3.9.5
+A working container runtime (Docker or Podman)
+The Quarkus CLI
+Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)
+In this guide, we create a straightforward REST application to demonstrate distributed tracing.
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can skip right to the completed example.
+The completed example is located in the quickstart directory.
First, we need a new project. Create a new project with the following command:
+quarkus create app org.acme:opentracing-quickstart \
+ --extension='resteasy-reactive,quarkus-smallrye-opentracing' \
+ --no-code
+cd opentracing-quickstartThis command generates the Maven project and imports the smallrye-opentracing extension, which
+includes the OpenTracing support and the default Jaeger tracer.
If you already have your Quarkus project configured, you can add the smallrye-opentracing extension
+to your project by running the following command in your project base directory:
quarkus extension add smallrye-opentracingThis will add the following to your build file:
+<dependency>
+ <groupId>io.quarkiverse.opentracing</groupId>
+ <artifactId>quarkus-smallrye-opentracing</artifactId>
+ <version>1.0.0</version>
+</dependency>Create the src/main/java/org/acme/opentracing/TracedResource.java file with the following content:
package org.acme.opentracing;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import org.jboss.logging.Logger;
+
+@Path("/hello")
+public class TracedResource {
+
+ private static final Logger LOG = Logger.getLogger(TracedResource.class);
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ LOG.info("hello"); (1)
+ return "hello";
+ }
+}| 1 | +The log event carries OpenTracing information as well. In order to print OpenTracing information to the console output, the console log handler with the required OpenTracing event’s keys needs to be defined in the application.properties file. |
+
Notice that there is no tracing specific code included in the application. By default, requests sent to this +endpoint will be traced without any code changes being required. It is also possible to enhance the tracing information. +This can be achieved by SmallRye OpenTracing an implementation of +MicroProfile OpenTracing.
+There are two ways to configure the Jaeger tracer within the application.
+The first approach is by providing the properties within the src/main/resources/application.properties file:
quarkus.jaeger.service-name=myservice (1)
+quarkus.jaeger.sampler-type=const (2)
+quarkus.jaeger.sampler-param=1 (3)
+quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId}, parentId=%X{parentId}, spanId=%X{spanId}, sampled=%X{sampled} [%c{2.}] (%t) %s%e%n (4)| 1 | +If the quarkus.jaeger.service-name property (or JAEGER_SERVICE_NAME environment variable) is not provided then a "no-op" tracer will be configured, resulting in no tracing data being reported to the backend. |
+
| 2 | +Set up a sampler that uses a constant sampling strategy. | +
| 3 | +Sample all requests. Set sampler-param to somewhere between 0 and 1, e.g. 0.50, if you do not wish to sample all requests. | +
| 4 | +Add trace IDs into log message. | +
The second approach is to supply the properties as environment variables. These can be specified using jvm.args as shown in the following section.
The first step is to start the tracing system to collect and display the captured traces:
+docker run -p 5775:5775/udp -p 6831:6831/udp -p 6832:6832/udp -p 5778:5778 -p 16686:16686 -p 14268:14268 jaegertracing/all-in-one:latestNow we are ready to run our application. If using application.properties to configure the tracer:
quarkus devor if configuring the tracer via environment variables:
+quarkus dev -Djvm.args="-DJAEGER_SERVICE_NAME=myservice -DJAEGER_SAMPLER_TYPE=const -DJAEGER_SAMPLER_PARAM=1"Once both the application and tracing system are started, you can make a request to the provided endpoint:
+$ curl http://localhost:8080/hello
+helloWhen the first request has been submitted, the Jaeger tracer within the app will be initialized:
+2019-10-16 09:35:23,464 INFO [io.jae.Configuration] (executor-thread-1) Initialized tracer=JaegerTracer(version=Java-0.34.0, serviceName=myservice, reporter=RemoteReporter(sender=UdpSender(), closeEnqueueTimeout=1000), sampler=ConstSampler(decision=true, tags={sampler.type=const, sampler.param=true}), tags={hostname=localhost.localdomain, jaeger.version=Java-0.34.0, ip=127.0.0.1}, zipkinSharedRpcSpan=false, expandExceptionLogs=false, useTraceId128Bit=false)
+13:20:11 INFO traceId=1336b2b0a76a96a3, parentId=0, spanId=1336b2b0a76a96a3, sampled=true [or.ac.qu.TracedResource] (executor-thread-63) helloThen visit the Jaeger UI to see the tracing information.
+Hit CTRL+C to stop the application.
REST endpoints are automatically traced.
+If you need to trace additional methods, you can add the org.eclipse.microprofile.opentracing.Traced annotation to CDI bean classes or their non-private methods.
This can be useful to trace incoming requests from non-REST calls (like request coming from a message) or to create spans inside a trace.
+Here is an example of a FrancophoneService which methods are traced.
import jakarta.enterprise.context.ApplicationScoped;
+
+import org.eclipse.microprofile.opentracing.Traced;
+
+@Traced
+@ApplicationScoped
+public class FrancophoneService {
+
+ public String bonjour() {
+ return "bonjour";
+ }
+}| + + | +
+The best way to add OpenTracing capability to reactive messaging based applications is by adding the Traced annotation to all incoming methods.
+ |
+
The OpenTracing API Contributions project offers additional instrumentation that can be used to add tracing to a large variety of technologies/components.
+The instrumentation documented in this section has been tested with Quarkus and works in both standard and native mode.
+The JDBC instrumentation will add a span for each JDBC queries done by your application, to enable it, add the following dependency to your build file:
+<dependency>
+ <groupId>io.opentracing.contrib</groupId>
+ <artifactId>opentracing-jdbc</artifactId>
+</dependency>implementation("io.opentracing.contrib:opentracing-jdbc")Then, you need to enable it in the configuration:
+quarkus.datasource.jdbc.tracing=truequarkus.datasource.jdbc.tracing is a build time configuration property:
+it makes sure all the tracing infrastructure is included in your application.
| + + | +
+
+
+This is especially important when building a native executable as we need to +make sure the OpenTracing JDBC driver has been registered for reflection, +together with the underlying JDBC driver. + |
+
The Agroal extension will take care of adjusting the JDBC URL with the tracing prefix
+when tracing is enabled,
+so you do not have to adjust the JDBC URL yourself.
By default, when quarkus.datasource.jdbc.tracing is true, tracing is enabled at runtime
+but you can explicitly disable it by setting the following property:
quarkus.datasource.jdbc.tracing.enabled=falseThis way, you can have your Quarkus application ready for tracing and toggle JDBC tracing at runtime.
+The Kafka instrumentation will add a span for each message sent to or received from a Kafka topic. To enable it, add the following dependency to your build file:
+<dependency>
+ <groupId>io.opentracing.contrib</groupId>
+ <artifactId>opentracing-kafka-client</artifactId>
+</dependency>It contains OpenTracing interceptors that must be registered on Kafka producers and consumers.
+If you followed the Kafka guide, the interceptors can be added on the generated-price and the prices channels as follows:
# Configure the Kafka sink (we write to it)
+mp.messaging.outgoing.generated-price.connector=smallrye-kafka
+mp.messaging.outgoing.generated-price.topic=prices
+mp.messaging.outgoing.generated-price.value.serializer=org.apache.kafka.common.serialization.IntegerSerializer
+mp.messaging.outgoing.generated-price.interceptor.classes=io.opentracing.contrib.kafka.TracingProducerInterceptor
+
+# Configure the Kafka source (we read from it)
+mp.messaging.incoming.prices.connector=smallrye-kafka
+mp.messaging.incoming.prices.value.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer
+mp.messaging.incoming.prices.interceptor.classes=io.opentracing.contrib.kafka.TracingConsumerInterceptor| + + | +
+interceptor.classes accept a list of classes separated by a comma.
+ |
+
The Mongo Driver instrumentation will add a span for each command executed by your application. To enable it, add the following dependency to your build file:
+<dependency>
+ <groupId>io.opentracing.contrib</groupId>
+ <artifactId>opentracing-mongo-common</artifactId>
+</dependency>It contains the OpenTracing CommandListener that will be registered on the configuration of the mongo client. +Following the MongoDB guide, the command listener will be registered defining the config property as follows:
+# Enable tracing commands in MongoDB client
+quarkus.mongodb.tracing.enabled=trueTo enable it, add the following dependency to your build file:
+<dependency>
+ <groupId>io.jaegertracing</groupId>
+ <artifactId>jaeger-zipkin</artifactId>
+</dependency>It contains the dependencies to convert the request to zipkin format. +The zipkin compatibility mode will be activated after defining the config property as follows:
+# Enable zipkin compatibility mode
+quarkus.jaeger.zipkin.compatibility-mode=trueConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Environment variable: |
+
+
|
+
|
+
For more information about the Jaeger extension configuration, have a look at the Jaeger extension documentation.
+This extension is used to notify Linux service manager (systemd) about start-up completion and other service status changes.
+To use the extension, add the dependency to the target project:
+<dependency>
+ <groupId>io.quarkiverse.systemd.notify</groupId>
+ <artifactId>quarkus-systemd-notify</artifactId>
+ <version>1.0.1</version>
+</dependency>and configure the service unit file with the following minumum configurations:
+[Service]
+Type=notify
+AmbientCapabilities=CAP_SYS_ADMINAssuming quarkus-run.jar is located at /opt/quarkus-app/quarkus-run.jar:
Create a unit configuration file at /etc/systemd/system/quarkus.service:
[Unit]
+Description=Quarkus Server
+After=network.target
+Wants=network.target
+
+[Service]
+Type=notify
+AmbientCapabilities=CAP_SYS_ADMIN
+ExecStart=/bin/java -jar /opt/quarkus-app/quarkus-run.jar
+SuccessExitStatus=0 143
+
+[Install]
+WantedBy=multi-user.targetEnable the service (this will make it to run at system start-up as well):
+sudo systemctl enable quarkusStart/Stop/Restart the service:
+sudo systemctl start quarkus
+sudo systemctl stop quarkus
+sudo systemctl restart quarkusCheck status of the service:
+sudo systemctl status quarkusConfiguration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The resource path within the application artifact to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of the parsers which must be supported.
+Most of the document formats recognized by Apache Tika are supported by default but it affects the application memory and native executable sizes. One can list only the required parsers in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Controls how the content of the embedded documents is parsed. By default it is appended to the main document content. Setting this property to false makes the content of each of the embedded documents available separately. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration of the individual parsers. For example: quarkus.tika.parsers = pdf,odf quarkus.tika.parser-options.pdf.sort-by-position = true +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Full parser class name for a given parser abbreviation. For example: quarkus.tika.parsers = classparser quarkus.tika.parser.classparser = org.apache.tika.parser.asm.ClassParser +
+
+Environment variable: |
+
|
++ |
This guide explains how your Quarkus application can use Apache Tika to parse the documents.
+Apache Tika is a content analysis toolkit which is used to parse the documents in PDF, Open Document, Excel and many other well known binary and text formats using a simple uniform API. Both the document text and properties (metadata) are available once the document has been parsed.
+| + + | +
+
+
+If you are planning to run the application as a native executable and parse documents that may have been created with charsets different than the standard ones supported in Java such as
+
+
+
+
+
+When building native images in Docker using the standard Quarkus Docker configuration files some additional features need to be
+installed to support Apache POI. Specifically font information is not included in [Red Hat’s ubi-minimal images](https://developers.redhat.com/products/rhel/ubi). To install it
+simply add these lines to your
+
+
+
+ |
+
To complete this guide, you need:
+less than 20 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven {maven-version}
+Docker
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the tika-quickstart directory.
| + + | +
+
+
+The provided solution contains a few additional elements such as tests and testing infrastructure. + |
+
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:2.16.5.Final:create \
+ -DprojectGroupId=org.acme.example \
+ -DprojectArtifactId=tika-quickstart \
+ -DclassName="org.acme.tika.TikaParserResource" \
+ -Dpath="/parse" \
+ -Dextensions="tika,resteasy-reactive,awt"
+cd tika-quickstartThis command generates a Maven project, importing the tika and resteasy-reactive extensions.
+We also import the AWT extension as some of the Tika operations done in this guide require it.
If you already have your Quarkus project configured, you can add the extensions +to your project by running the following command in your project base directory:
+./mvnw quarkus:add-extension -Dextensions="tika,resteasy-reactive,awt"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.tika</groupId>
+ <artifactId>quarkus-tika</artifactId>
+ <version>1.1.1</version>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy-reactive</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-awt</artifactId>
+</dependency>Open the src/main/java/org/acme/tika/TikaParserResource.java file and see the following content:
package org.acme.tika;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+@Path("/parse")
+public class TikaParserResource {
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return "hello";
+ }
+}Next update TikaParserResource to accept and parse PDF and OpenDocument format documents:
package org.acme.tika;
+
+import java.io.InputStream;
+import java.time.Duration;
+import java.time.Instant;
+
+import javax.inject.Inject;
+import javax.ws.rs.Consumes;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.MediaType;
+
+import io.quarkus.tika.TikaParser;
+import org.jboss.logging.Logger;
+
+@Path("/parse")
+public class TikaParserResource {
+ private static final Logger log = Logger.getLogger(TikaParserResource.class);
+
+ @Inject
+ TikaParser parser;
+
+ @POST
+ @Path("/text")
+ @Consumes({"application/pdf", "application/vnd.oasis.opendocument.text"})
+ @Produces(MediaType.TEXT_PLAIN)
+ public String extractText(InputStream stream) {
+ Instant start = Instant.now();
+
+ String text = parser.getText(stream);
+
+ Instant finish = Instant.now();
+
+ log.info(Duration.between(start, finish).toMillis() + " mls have passed");
+
+ return text;
+ }
+}As you can see the JAX-RS resource method was renamed to extractText, @GET annotation was replaced with POST and @Path(/text) annotation was added, and @Consumes annotation shows that PDF and OpenDocument media type formats can now be accepted. An injected TikaParser is used to parse the documents and report the extracted text. It also measures how long does it take to parse a given document.
Now we are ready to run our application. Use:
+./mvnw compile quarkus:devand you should see output similar to:
+$ ./mvnw clean compile quarkus:dev
+[INFO] Scanning for projects...
+[INFO]
+INFO] --------------------< org.acme.example:apache-tika >--------------------
+[INFO] Building apache-tika 1.0.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+...
+Listening for transport dt_socket at address: 5005
+2019-10-15 14:23:26,442 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
+2019-10-15 14:23:26,991 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 549ms
+2019-10-15 14:23:27,637 INFO [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 1.361s. Listening on: http://0.0.0.0:8080
+2019-10-15 14:23:27,638 INFO [io.quarkus] (main) Profile dev activated. Live Coding activated.
+2019-10-15 14:23:27,639 INFO [io.quarkus] (main) Installed features: [cdi, resteasy-reactive, tika]Now that the REST endpoint is running, we can get it to parse PDF and OpenDocument documents using a command line tool like curl:
+$ curl -X POST -H "Content-type: application/pdf" --data-binary @target/classes/quarkus.pdf http://localhost:8080/parse/text
+Hello Quarkusand
+$ curl -X POST -H "Content-type: Content-type: application/vnd.oasis.opendocument.text" --data-binary @target/classes/quarkus.odt http://localhost:8080/parse/text
+Hello QuarkusYou can build a native executable with the usual command ./mvnw package -Dnative.
+Running it is as simple as executing ./target/tika-quickstart-1.0.0-SNAPSHOT-runner.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The resource path within the application artifact to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of the parsers which must be supported.
+Most of the document formats recognized by Apache Tika are supported by default but it affects the application memory and native executable sizes. One can list only the required parsers in
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Controls how the content of the embedded documents is parsed. By default it is appended to the main document content. Setting this property to false makes the content of each of the embedded documents available separately. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration of the individual parsers. For example: quarkus.tika.parsers = pdf,odf quarkus.tika.parser-options.pdf.sort-by-position = true +
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Full parser class name for a given parser abbreviation. For example: quarkus.tika.parsers = classparser quarkus.tika.parser.classparser = org.apache.tika.parser.asm.ClassParser +
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The resource path within the application artifact to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of the parsers which must be supported. +
+
+Most of the document formats recognized by Apache Tika are supported by default but it affects the application memory and native executable sizes. One can list only the required parsers in
+
+Either the abbreviated or full parser class names can be used. Only PDF and OpenDocument format parsers can be listed using the reserved 'pdf' and 'odf' abbreviations. Custom class name abbreviations have to be used for all other parsers. For example: +
+
+
+
+
+
+This property will have no effect if the `tikaConfigPath' property has been set. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Controls how the content of the embedded documents is parsed. By default it is appended to the main document content. Setting this property to false makes the content of each of the embedded documents available separately. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration of the individual parsers. For example: +
+
+
+
+
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Full parser class name for a given parser abbreviation. For example: +
+
+
+
+
+
+Environment variable: |
+
|
++ |
This guide explains how your Quarkus application can use Apache Tika to parse the documents.
+Apache Tika is a content analysis toolkit which is used to parse the documents in PDF, Open Document, Excel and many other well known binary and text formats using a simple uniform API. Both the document text and properties (metadata) are available once the document has been parsed.
+| + + | +
+
+
+If you are planning to run the application as a native executable and parse documents that may have been created with charsets different than the standard ones supported in Java such as
+
+
+
+
+
+When building native images in Docker using the standard Quarkus Docker configuration files some additional features need to be
+installed to support Apache POI. Specifically font information is not included in [Red Hat’s ubi-minimal images](https://developers.redhat.com/products/rhel/ubi). To install it
+simply add these lines to your
+
+
+
+ |
+
To complete this guide, you need:
+less than 20 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven {maven-version}
+Docker
+We recommend that you follow the instructions in the next sections and create the application step by step. +However, you can go right to the completed example.
+Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the tika-quickstart directory.
| + + | +
+
+
+The provided solution contains a few additional elements such as tests and testing infrastructure. + |
+
First, we need a new project. Create a new project with the following command:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.2.9.Final:create \
+ -DprojectGroupId=org.acme.example \
+ -DprojectArtifactId=tika-quickstart \
+ -DclassName="org.acme.tika.TikaParserResource" \
+ -Dpath="/parse" \
+ -Dextensions="tika,resteasy-reactive,awt"
+cd tika-quickstartThis command generates a Maven project, importing the tika and resteasy-reactive extensions.
+We also import the AWT extension as some of the Tika operations done in this guide require it.
If you already have your Quarkus project configured, you can add the extensions +to your project by running the following command in your project base directory:
+./mvnw quarkus:add-extension -Dextensions="tika,resteasy-reactive,awt"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.tika</groupId>
+ <artifactId>quarkus-tika</artifactId>
+ <version>2.0.3</version>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-resteasy-reactive</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-awt</artifactId>
+</dependency>Open the src/main/java/org/acme/tika/TikaParserResource.java file and see the following content:
package org.acme.tika;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+@Path("/parse")
+public class TikaParserResource {
+
+ @GET
+ @Produces(MediaType.TEXT_PLAIN)
+ public String hello() {
+ return "hello";
+ }
+}Next update TikaParserResource to accept and parse PDF and OpenDocument format documents:
package org.acme.tika;
+
+import java.io.InputStream;
+import java.time.Duration;
+import java.time.Instant;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+
+import io.quarkus.tika.TikaParser;
+import org.jboss.logging.Logger;
+
+@Path("/parse")
+public class TikaParserResource {
+ private static final Logger log = Logger.getLogger(TikaParserResource.class);
+
+ @Inject
+ TikaParser parser;
+
+ @POST
+ @Path("/text")
+ @Consumes({"application/pdf", "application/vnd.oasis.opendocument.text"})
+ @Produces(MediaType.TEXT_PLAIN)
+ public String extractText(InputStream stream) {
+ Instant start = Instant.now();
+
+ String text = parser.getText(stream);
+
+ Instant finish = Instant.now();
+
+ log.info(Duration.between(start, finish).toMillis() + " mls have passed");
+
+ return text;
+ }
+}As you can see the JAX-RS resource method was renamed to extractText, @GET annotation was replaced with POST and @Path(/text) annotation was added, and @Consumes annotation shows that PDF and OpenDocument media type formats can now be accepted. An injected TikaParser is used to parse the documents and report the extracted text. It also measures how long does it take to parse a given document.
Now we are ready to run our application. Use:
+./mvnw compile quarkus:devand you should see output similar to:
+$ ./mvnw clean compile quarkus:dev
+[INFO] Scanning for projects...
+[INFO]
+INFO] --------------------< org.acme.example:apache-tika >--------------------
+[INFO] Building apache-tika 1.0.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+...
+Listening for transport dt_socket at address: 5005
+2019-10-15 14:23:26,442 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
+2019-10-15 14:23:26,991 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 549ms
+2019-10-15 14:23:27,637 INFO [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 1.361s. Listening on: http://0.0.0.0:8080
+2019-10-15 14:23:27,638 INFO [io.quarkus] (main) Profile dev activated. Live Coding activated.
+2019-10-15 14:23:27,639 INFO [io.quarkus] (main) Installed features: [cdi, resteasy-reactive, tika]Now that the REST endpoint is running, we can get it to parse PDF and OpenDocument documents using a command line tool like curl:
+$ curl -X POST -H "Content-type: application/pdf" --data-binary @target/classes/quarkus.pdf http://localhost:8080/parse/text
+Hello Quarkusand
+$ curl -X POST -H "Content-type: Content-type: application/vnd.oasis.opendocument.text" --data-binary @target/classes/quarkus.odt http://localhost:8080/parse/text
+Hello QuarkusYou can build a native executable with the usual command ./mvnw package -Dnative.
+Running it is as simple as executing ./target/tika-quickstart-1.0.0-SNAPSHOT-runner.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The resource path within the application artifact to the
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Comma separated list of the parsers which must be supported. +
+
+Most of the document formats recognized by Apache Tika are supported by default but it affects the application memory and native executable sizes. One can list only the required parsers in
+
+Either the abbreviated or full parser class names can be used. Only PDF and OpenDocument format parsers can be listed using the reserved 'pdf' and 'odf' abbreviations. Custom class name abbreviations have to be used for all other parsers. For example: +
+
+
+
+
+
+This property will have no effect if the `tikaConfigPath' property has been set. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Controls how the content of the embedded documents is parsed. By default it is appended to the main document content. Setting this property to false makes the content of each of the embedded documents available separately. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Configuration of the individual parsers. For example: +
+
+
+
+
+
+Environment variable: |
+
|
++ |
+
+
+
+
+
+Full parser class name for a given parser abbreviation. For example: +
+
+
+
+
+
+Environment variable: |
+
|
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The import data from file during the start. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Unleash URL service endpoint +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Application name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instance ID. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable Unleash metrics +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Application Unleash token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Application environment +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Fetch toggles interval +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Send metrics interval +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Backup file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A synchronous fetch on initialisation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable proxy authentication by JVM properties +
+
+Environment variable: |
+boolean |
+
|
+
Unleash is a feature toggle system, that gives you a great overview of all feature toggles across all your applications and services. +Quarkus Unleash extension is client for Unleash.
+If you want to use this extension, you need to add the quarkiverse-unleash extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.unleash</groupId>
+ <artifactId>quarkus-unleash</artifactId>
+ <version>0.8.0</version>
+</dependency>Assuming you have Unleash running on localhost:4242 you should add the following properties to your application.properties and fill in the values for url.
quarkus.unleash.url=http://localhost:4242/apiOnce you have configured the properties, you can start using an Unleash-client.
+@ApplicationScoped
+public class TestService {
+
+ @Inject
+ Unleash unleash;
+
+ public boolean isTest() {
+ return unleash.isEnabled("quarkus.unleash.test");
+ }
+}By using the @FeatureToggle annotation there is a shortcut to inject feature toggle.
@ApplicationScoped
+public class TestService {
+
+ @FeatureToggle(name = "my-toggle")
+ Instance<Boolean> myToggle;
+
+ @FeatureToggle(name = "my-toggle", defaultValue = true)
+ Instance<Boolean> myToggleDefault;
+
+}By using the @FeatureVariant annotation there is a shortcut to inject feature toggle
+variant or the payload of the variant.
@ApplicationScoped
+public class TestService {
+
+ @FeatureVariant(name = "toggle-variant")
+ Instance<Variant> variant;
+
+ @FeatureVariant(name = "toggle-payload")
+ Instance<String> variant;
+
+ @FeatureVariant(name = "toggle-variant-json")
+ Instance<MyCustomJsonModel> variant;
+
+}To use the test extension, add this dependency to the project:
+<dependency>
+ <groupId>io.quarkiverse.unleash</groupId>
+ <artifactId>quarkus-unleash-test</artifactId>
+ <version>0.8.0</version>
+ <scope>test</scope>
+</dependency>UnleashTestResource creates an instance of admin and standard Unleash clients just for testing.
+These instances are separate from the application instances.
@QuarkusTest
+@QuarkusTestResource(UnleashTestResource.class)
+public class BaseTest {
+
+ @InjectUnleashAdmin
+ UnleashAdmin admin;
+
+ @InjectUnleash
+ Unleash client;
+
+ @Test
+ public void test() {
+
+ admin.toggleOff("toggle-1");
+ admin.toggleOn("toggle-2");
+
+ // wait for client change
+ await().atLeast(12, SECONDS)
+ .pollInterval(4, SECONDS)
+ .until(() -> client.isEnabled("toggle-2"));
+
+ boolean toggleOn = client.isEnabled("toggle-2");
+
+ // ... test my application
+
+ }
+}Dev Services for Unleash is automatically enabled unless:
+quarkus.unleash.devservices.enabled is set to false
quarkus.unleash.url is configured
Dev Service for Unleash relies on Docker to start the broker. If your environment does not support Docker, you will need
+to start the broker manually, or connect to an already running broker. You can configure the broker address using
+quarkus.unleash.url.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The import data from file during the start. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Unleash URL service endpoint +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Application name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instance ID. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable Unleash metrics +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Application Unleash token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Application environment +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Fetch toggles interval +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Send metrics interval +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Backup file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A synchronous fetch on initialisation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable proxy authentication by JVM properties +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Unleash servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The import data from file during the start. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The container image name to use, for unleash database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Unleash DB servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether or not the Unleash extension is active. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Unleash URL service endpoint +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Application name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instance ID. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable Unleash metrics +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Application Unleash token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Application environment +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Fetch toggles interval (in seconds) +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Send metrics interval (in seconds) +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Backup file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A synchronous fetch on initialisation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable proxy authentication by JVM properties +
+
+Environment variable: |
+boolean |
+
|
+
Unleash is a feature toggle system, that gives you a great overview of all feature toggles across all your applications and services. +Quarkus Unleash extension is client for Unleash.
+If you want to use this extension, you need to add the quarkiverse-unleash extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.unleash</groupId>
+ <artifactId>quarkus-unleash</artifactId>
+ <version>1.2.0</version>
+</dependency>Assuming you have Unleash running on localhost:4242 you should add the following properties to your application.properties and fill in the values for url.
quarkus.unleash.url=http://localhost:4242/apiOnce you have configured the properties, you can start using an Unleash-client.
+@ApplicationScoped
+public class TestService {
+
+ @Inject
+ Unleash unleash;
+
+ public boolean isTest() {
+ return unleash.isEnabled("quarkus.unleash.test");
+ }
+}By using the @FeatureToggle annotation there is a shortcut to inject feature toggle.
@ApplicationScoped
+public class TestService {
+
+ @FeatureToggle(name = "my-toggle")
+ Instance<Boolean> myToggle;
+
+ @FeatureToggle(name = "my-toggle", defaultValue = true)
+ Instance<Boolean> myToggleDefault;
+
+}| + + | +
+
+
+If the |
+
By using the @FeatureVariant annotation there is a shortcut to inject feature toggle
+variant or the payload of the variant.
@ApplicationScoped
+public class TestService {
+
+ @FeatureVariant(name = "toggle-variant")
+ Instance<Variant> variant;
+
+ @FeatureVariant(name = "toggle-payload")
+ Instance<String> variant;
+
+ @FeatureVariant(name = "toggle-variant-json")
+ Instance<MyCustomJsonModel> variant;
+
+}To use the test extension, add this dependency to the project:
+<dependency>
+ <groupId>io.quarkiverse.unleash</groupId>
+ <artifactId>quarkus-unleash-test</artifactId>
+ <version>1.2.0</version>
+ <scope>test</scope>
+</dependency>UnleashTestResource creates an instance of admin and standard Unleash clients just for testing.
+These instances are separate from the application instances.
@QuarkusTest
+@QuarkusTestResource(UnleashTestResource.class)
+public class BaseTest {
+
+ @InjectUnleashAdmin
+ UnleashAdmin admin;
+
+ @InjectUnleash
+ Unleash client;
+
+ @Test
+ public void test() {
+
+ admin.toggleOff("toggle-1");
+ admin.toggleOn("toggle-2");
+
+ // wait for client change
+ await().atLeast(12, SECONDS)
+ .pollInterval(4, SECONDS)
+ .until(() -> client.isEnabled("toggle-2"));
+
+ boolean toggleOn = client.isEnabled("toggle-2");
+
+ // ... test my application
+
+ }
+}Dev Services for Unleash is automatically enabled unless:
+quarkus.unleash.devservices.enabled is set to false
quarkus.unleash.url is configured
Dev Service for Unleash relies on Docker to start the broker. If your environment does not support Docker, you will need
+to start the broker manually, or connect to an already running broker. You can configure the broker address using
+quarkus.unleash.url.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Unleash servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Enabled or disable log of the mock-server +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The import data from file during the start. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The container image name to use, for unleash database. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Unleash DB servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether or not the Unleash extension is active. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Unleash URL service endpoint +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Application name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Project name +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Instance ID. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Disable Unleash metrics +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Application Unleash token +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Application environment +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Fetch toggles interval (in seconds) +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Send metrics interval (in seconds) +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Backup file +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+A synchronous fetch on initialisation +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable proxy authentication by JVM properties +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether or not an health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies if being a standby should still return the active status code instead of the standby status code. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies if being a performance standby should still return the active status code instead of the performance standby status code. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a vault instance when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the Vault instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Vault starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Vault instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Should the Transit secret engine be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Should the PKI secret engine be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Custom container initialization commands +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Microprofile Config ordinal. +
+
+This is provided as an alternative to the
+
+The default value is higher than the file system or jar ordinals, but lower than env vars. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Vault server url.
+<p>
+Example: https://localhost:8200
+<p>
+See also the documentation for the
+
+Environment variable: |
++ | + |
+
+
+
+
+
+Renew grace period duration. +<p> +This value if used to extend a lease before it expires its ttl, or recreate a new lease before the current +lease reaches its max_ttl. +By default Vault leaseDuration is equal to 7 days (ie: 168h or 604800s). +If a connection pool maxLifetime is set, it is reasonable to set the renewGracePeriod to be greater +than the maxLifetime, so that we are sure we get a chance to renew leases before we reach the ttl. +In any case you need to make sure there will be attempts to fetch secrets within the renewGracePeriod, +because that is when the renewals will happen. This is particularly important for db dynamic secrets +because if the lease reaches its ttl or max_ttl, the password of the db user will become invalid and +it will be not longer possible to log in. +This value should also be smaller than the ttl, otherwise that would mean that we would try to recreate +leases all the time. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Vault config source cache period.
+<p>
+Properties fetched from vault as MP config will be kept in a cache, and will not be fetched from vault
+again until the expiration of that period.
+This property is ignored if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of comma separated vault paths in kv store,
+where all properties will be available as MP config properties as-is, with no prefix.
+<p>
+For instance, if vault contains property
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Maximum number of attempts when fetching MP Config properties on the initial connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Used to hide confidential infos, for logging in particular. +Possible values are: +<p> +* low: display all secrets. +* medium: display only usernames and lease ids (ie: passwords and tokens are masked). +* high: hide lease ids and dynamic credentials username. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Kv secret engine version. +<p> +see https://www.vaultproject.io/docs/secrets/kv/index.html +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+KV secret engine path.
+<p>
+This value is used when building the url path in the KV secret engine programmatic access
+(i.e.
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout to establish a connection with Vault. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Request timeout on Vault. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of remote hosts that are not proxied when the client is configured to use a proxy. This list serves the same purpose as the JVM
+
+Entries can use the * wildcard character for pattern matching, e.g *.example.com matches www.example.com. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The proxy host. If set the client is configured to use a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The port the proxy is listening on, 3128 by default. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+List of comma separated vault paths in kv store,
+where all properties will be available as prefixed MP config properties.
+<p>
+For instance if the application properties contains
+
+
+Environment variable: |
+list of string |
+required |
+
+
+
+
+
+
+Dynamic credentials' role.
+<p>
+Roles are defined by the secret engine in use. For example,
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Mount of dynamic credentials secrets engine, for example
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path of dynamic credentials request.
+<p>
+Request paths are dictated by the secret engine in use. For standard secret engines this should be
+left as the default of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A path in vault kv store, where we will find the kv-key.
+<p>
+One of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key name to search in vault path
+
+Environment variable: |
+string |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Vault Enterprise namespace
+<p>
+If set, this will add a
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Vault token, bypassing Vault authentication (kubernetes, userpass or approle). This is useful in development where an authentication mode might not have been set up. In production we will usually prefer some authentication such as userpass, or preferably kubernetes, where Vault tokens get generated with a TTL and some ability to revoke them. Lease renewal does not apply. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client token wrapped in a wrapping token, such as what is returned by: +
+
+vault token create -wrap-ttl=60s -policy=myapp +
+
+client-token and client-token-wrapping-token are exclusive. Lease renewal does not apply. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Role Id for AppRole auth method. This property is required when selecting the app-role authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Secret Id for AppRole auth method. This property is required when selecting the app-role authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Wrapping token containing a Secret Id, obtained from: +
+
+vault write -wrap-ttl=60s -f auth/approle/role/myapp/secret-id +
+
+secret-id and secret-id-wrapping-token are exclusive +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Allows configure Approle authentication mount path. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+User for userpass auth method. This property is required when selecting the userpass authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for userpass auth method. This property is required when selecting the userpass authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Wrapping token containing a Password, obtained from: +
+
+vault kv get -wrap-ttl=60s secret/ +
+
+The key has to be 'password', meaning the password has initially been provisioned with: +
+
+vault kv put secret/ password= +
+
+password and password-wrapping-token are exclusive +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Kubernetes authentication role that has been created in Vault to associate Vault policies, with Kubernetes service accounts and/or Kubernetes namespaces. This property is required when selecting the Kubernetes authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of the file containing the Kubernetes JWT token to authenticate against in Kubernetes authentication mode. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Allows configure Kubernetes authentication mount path. +
+
+Environment variable: |
+string |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Allows to bypass certificate validation on TLS communications. +
+
+If true this will allow TLS communications with Vault, without checking the validity of the certificate presented by Vault. This is discouraged in production because it allows man in the middle type of attacks. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Certificate bundle used to validate TLS communications with Vault. +
+
+The path to a pem bundle file, if TLS is required, and trusted certificates are not set through javax.net.ssl.trustStore system property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true and Vault authentication type is kubernetes, TLS will be active and the cacert path will be set to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. If set, this setting will take precedence over property quarkus.vault.tls.ca-cert. This means that if Vault authentication type is kubernetes and we want to use quarkus.vault.tls.ca-cert or system property javax.net.ssl.trustStore, then this property should be set to false. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Specifies the name of the key to use. By default this will be the property key alias. Used when +the same transit key is used with different configurations. Such as in: +
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Set to true when the input is already hashed. Applies to sign operations. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+When using a RSA key, specifies the RSA signature algorithm. Applies to sign operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the hash algorithm to use for supporting key types. Applies to sign operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the type of key to create for the encrypt operation. Applies to encrypt operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. Applies to encrypt operations. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
HashiCorp Vault is a multi-purpose tool aiming at protecting sensitive data, such as +credentials, certificates, access tokens, encryption keys, … In the context of Quarkus, several use cases +are supported:
+mounting a map of properties stored into the +Vault kv secret engine as an Eclipse MicroProfile config source
+fetching credentials from Vault when configuring an Agroal datasource, as documented in the Vault Datasource Guide
+fetching credentials from Vault when connecting to a RabbitMQ broker, as documented in the RabbitMQ Dynamic Credentials Guide
+accessing Vault kv secret engine programmatically
+support for the TOTP Secret Engine
+support for the Transit Secret Engine as documented +in the Vault Transit Secret Engine Guide
+support for the PKI Secret Engine as documented +in the Vault PKI Secret Engine Guide
+support for several authentication methods as documented in the Vault Authentication guide
+Under the hood, the Quarkus Vault extension takes care of authentication when negotiating a client Vault token plus +any transparent token or lease renewals according to ttl and max-ttl.
+To complete this guide, you need:
+roughly 20 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+| + + | +
+
+
+Using Dev Services, Quarkus will take care of starting Vault in dev and test mode. + |
+
Let’s start Vault in development mode:
+docker run --rm --cap-add=IPC_LOCK -e VAULT_ADDR=http://localhost:8200 -p 8200:8200 -d --name=dev-vault vault:1.6.0You can check that vault is running with:
+docker logs dev-vaultYou should see:
+==> Vault server configuration:
+
+ Api Address: http://0.0.0.0:8200
+ Cgo: disabled
+ Cluster Address: https://0.0.0.0:8201
+ Listener 1: tcp (addr: "0.0.0.0:8200", cluster address: "0.0.0.0:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
+ Log Level: info
+ Mlock: supported: true, enabled: false
+ Storage: inmem
+ Version: Vault v1.6.0
+
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+
+You may need to set the following environment variable:
+
+ $ export VAULT_ADDR='http://0.0.0.0:8200'
+
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+
+Unseal Key: 0lZ2/vzpa92pH8gersSn2h9b5tmzd4m5sqIdMC/4PDs=
+Root Token: s.5VUS8pte13RqekCB2fmMT3u2
+
+Development mode should NOT be used in production installations!
+
+==> Vault server started! Log data will stream in below:In development mode, Vault gets configured with several options that makes it convenient:
+Vault is already initialized with one key share (whereas in normal mode this has to be done explicitly and the +number of key shares is 5 by default)
+the unseal key and the root token are displayed in the logs (please write down the root token, we will need it +in the following step)
+Vault is unsealed
+in-memory storage
+TLS is disabled
+a kv secret engine v2 is mounted at secret/
| + + | +
+
+
+By default Quarkus assumes that a kv secret engine in version 2 mounted at path |
+
In the following step, we are going to add a userpass authentication that we will use from the Quarkus application,
+to access a secret stored in the kv secret engine.
First open a shell inside the vault container:
+docker exec -it dev-vault shSet the VAULT_TOKEN with the value that was printed in the logs:
export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2You can check Vault’s status using the CLI command vault status:
Key Value
+--- -----
+Seal Type shamir
+Initialized true
+Sealed false
+Total Shares 1
+Threshold 1
+Version 1.6.0
+Cluster Name vault-cluster-b07e80d8
+Cluster ID 55bd74b6-eaaf-3862-f7ce-3473ab86c57f
+HA Enabled falseNow let’s add a secret configuration for our application:
+vault kv put secret/myapps/vault-quickstart/config a-private-key=123456We have defined a path secret/myapps/vault-quickstart in Vault that we need to give access to from the Quarkus application.
Create a policy that gives read access to secret/myapps/vault-quickstart and subpaths:
cat <<EOF | vault policy write vault-quickstart-policy -
+path "secret/data/myapps/vault-quickstart/*" {
+ capabilities = ["read", "create"]
+}
+EOF| + + | +
+
+
+When using a kv secret engine version 2, secrets are written and fetched at path |
+
And finally, let’s enable the userpass auth secret engine, and create user bob with access to the vault-quickstart-policy:
vault auth enable userpass
+vault write auth/userpass/users/bob password=sinclair policies=vault-quickstart-policy| + + | +
+
+
+Quarkus supports additional Vault Authentication methods. Check the Vault Authentication guide for details. + |
+
To check that the configuration is correct, try logging in:
+vault login -method=userpass username=bob password=sinclairYou should see:
+Success! You are now authenticated. The token information displayed below
+is already stored in the token helper. You do NOT need to run "vault login"
+again. Future Vault requests will automatically use this token.
+
+Key Value
+--- -----
+token s.s93BVzJPzBiIGuYJHBTkG8Uw
+token_accessor OKNipTAgxWbxsrjixASNiwdY
+token_duration 768h
+token_renewable true
+token_policies ["default" "vault-quickstart-policy"]
+identity_policies []
+policies ["default" "vault-quickstart-policy"]
+token_meta_username bobNow set VAULT_TOKEN to the token above (instead of the root token), and try reading the vault-quickstart secret config:
export VAULT_TOKEN=s.s93BVzJPzBiIGuYJHBTkG8Uw
+vault kv get secret/myapps/vault-quickstart/configYou should see:
+======== Data ========
+Key Value
+--- -----
+a-private-key 123456mvn io.quarkus.platform:quarkus-maven-plugin:3.8.1:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=vault-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy,vault"
+cd vault-quickstartIf you already have your Quarkus project configured, you can add the vault extension
+to your project by running the following command in your project base directory:
./mvnw quarkus:add-extension -Dextensions="vault"This will add the following to your pom.xml:
<dependency>
+ <groupId>io.quarkiverse.vault</groupId>
+ <artifactId>quarkus-vault</artifactId>
+ <version>4.0.0-alpha.2</version>
+</dependency>Configure access to Vault from the application.properties:
# vault url
+quarkus.vault.url=http://localhost:8200
+
+# vault authentication
+quarkus.vault.authentication.userpass.username=bob
+quarkus.vault.authentication.userpass.password=sinclair
+
+# path within the kv secret engine where is located the vault-quickstart secret configuration
+quarkus.vault.secret-config-kv-path=myapps/vault-quickstart/config| + + | +
+
+
+Using Dev Services, Quarkus will take care of configuring the Vault connection in dev and test mode. + |
+
This should mount whatever keys are stored in secret/myapps/vault-quickstart as Config properties.
Let’s verify that by adding a new endpoint in GreetingResource:
+@Path("/hello")
+public class GreetingResource {
+
+ @ConfigProperty(name = "a-private-key")
+ String privateKey;
+
+ ...
+
+ @GET
+ @Path("/private-key")
+ @Produces(MediaType.TEXT_PLAIN)
+ public String privateKey() {
+ return privateKey;
+ }
+}Now compile the application and run it:
+./mvnw clean install
+java -jar target/quarkus-app/quarkus-run.jarFinally test the new endpoint:
+curl http://localhost:8080/hello/private-keyYou should see:
+123456| + + | +
+
+
+The Vault Config Source is configured with ordinal |
+
| + + | +
+
+
+Only scalar types are supported for secrets value from Vault. + |
+
Sometimes secrets are retrieved from an arbitrary path that is known only at runtime through an application
+specific property, or a method argument for instance.
+In that case it is possible to inject a Quarkus VaultKVSecretEngine, and retrieve secrets programmatically.
For instance, in GreetingResource, add:
@Inject
+VaultKVSecretEngine kvSecretEngine;
+
+...
+
+@GET
+@Path("/secrets/{vault-path}")
+@Produces(MediaType.TEXT_PLAIN)
+public String getSecrets(@PathParam("vault-path") String vaultPath) {
+ return kvSecretEngine.readSecret("myapps/vault-quickstart/" + vaultPath).toString();
+}Add a new key in Vault:
+vault kv put secret/myapps/vault-quickstart/private mysecret=abcRestart the application after rebuilding it, and test it with the new endpoint:
+curl http://localhost:8080/hello/secrets/privateYou should see:
+{mysecret=abc}The Vault TOTP secrets engine generates time-based credentials according to the TOTP standard.
+Vault TOTP supports both the generator scenario (like Google Authenticator) and the provider scenario (like the Google.com sign in).
+The Vault extension integrates with the Vault TOTP secret engine by providing an io.quarkus.vault.VaultTOTPSecretEngine class.
import io.quarkus.vault.VaultTOTPSecretEngine;
+import io.quarkus.vault.secrets.totp.CreateKeyParameters;
+import io.quarkus.vault.secrets.totp.KeyConfiguration;
+import io.quarkus.vault.secrets.totp.KeyDefinition;
+
+@Inject
+VaultTOTPSecretEngine vaultTOTPSecretEngine;
+
+CreateKeyParameters createKeyParameters = new CreateKeyParameters("Google", "test@gmail.com");
+createKeyParameters.setPeriod("30m");
+
+/** Google Authentication logic */
+
+final Optional<KeyDefinition> myKey = vaultTOTPSecretEngine
+ .createKey("my_key_2", createKeyParameters); (1) (2)
+
+final String keyCode = vaultTOTPSecretEngine.generateCode("my_key_2"); (3)
+
+/** Google Login logic */
+
+boolean valid = vaultTOTPSecretEngine.validateCode("my_key_2", keyCode); (4)| 1 | +Create a key to generate codes. | +
| 2 | +KeyDefinition class contains an embeddable base64 QR code that can be used by third-party code generators. |
+
| 3 | +Generates a code (not using third-party generator). | +
| 4 | +Validates that the code is valid. | +
If you are using the quarkus-smallrye-health extension, quarkus-vault can add a readiness health check
+to validate the connection to the Vault server. This is disabled by default.
If enabled, when you access the /q/health/ready endpoint of your application you will have information about the connection validation status.
This behavior can be enabled by setting the quarkus.vault.health.enabled property to true in your application.properties.
Only if Vault is initialized, unsealed and active, the health endpoint returns that Vault is ready to serve requests.
+You can change a bit this behaviour by using quarkus.vault.health.stand-by-ok and quarkus.vault.health.performance-stand-by-ok to true in your application.properties.
Specifies if being a standby should still return the active status code instead of the standby status code.
+Specifies if being a performance standby should still return the active status code instead of the performance standby status code.
+You can inject io.quarkus.vault.VaultSystemBackendEngine to run system operations programmatically.
| + + | ++When the readiness probe is failing in Kubernetes, then the application is not reachable. This means that if Vault is failing, all services depending on Vault will become unreachable and maybe this is not the desired state, so use this flag according to your requirements. + | +
In production mode, TLS should be activated between the Quarkus application and Vault to prevent man-in-the-middle attacks.
+There are several ways to configure the Quarkus application:
+through the standard javax.net.ssl.trustStore system property, which should refer to a JKS truststore containing
+the trusted certificates
using property quarkus.vault.tls.ca-cert, which should refer to a pem encoded file.
If quarkus.vault.tls.ca-cert is not set and the Quarkus application is using the Kubernetes authentication,
+TLS will be active and use the CA certificate bundle located in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.
+If you want to disable this behavior (for instance when using a trust store), you need to set it explicitly using:
+quarkus.vault.tls.use-kubernetes-ca-cert=false.
The last relevant property is quarkus.vault.tls.skip-verify, which allows to communicate with Vault using TLS,
+but without checking the certificate authenticity. This may be convenient in development, but is strongly
+discouraged in production as it is not more secure than talking to Vault in plain HTTP.
Beside the typical client use cases, the Quarkus extension can be used to provision Vault as well, +for instance as part of a CD pipeline. Specific CDI beans and operations support this scenario:
+VaultSystemBackendEngine: create Vault Policies. See the Vault documentation.
VaultKubernetesAuthService. See the Vault documentation.
Configure the Kubernetes Auth Method (Kubernetes host, certificates, keys, …)
+Create Kubernetes Auth Roles (association between Kubernetes service accounts, Kubernetes namespaces and Vault policies)
+VaultTransitSecretEngine: CRUD operations on keys. See the Vault documentation.
For instance:
+@Inject
+VaultSystemBackendEngine vaultSystemBackendEngine;
+
+@Inject
+VaultKubernetesAuthService vaultKubernetesAuthService;
+
+...
+
+ String rules = "path \"transit/*\" {\n" +
+ " capabilities = [ \"create\", \"read\", \"update\" ]\n" +
+ "}";
+ String policyName = "sys-test-policy";
+ vaultSystemBackendEngine.createUpdatePolicy(policyName, rules);
+
+ String roleName = "test-auth-k8s";
+ List<String> boundServiceAccountNames = asList("vault-auth");
+ List<String> boundServiceAccountNamespaces = asList("default");
+ List<String> tokenPolicies = asList(policyName);
+
+ vaultKubernetesAuthService.createRole(roleName, new VaultKubernetesAuthRole()
+ .setBoundServiceAccountNames(boundServiceAccountNames)
+ .setBoundServiceAccountNamespaces(boundServiceAccountNamespaces)
+ .setTokenPolicies(tokenPolicies));Like any client, a provisioning program would have to authenticate using one of the supported Auth methods, and get the appropriate grants through one or more policies. Example:
+# create Policies
+path "sys/policy/*" {
+ capabilities = ["read", "create", "update", "delete"]
+}
+
+# create Kubernetes Auth Roles
+path "auth/kubernetes/role/*" {
+ capabilities = ["read", "create", "update", "delete"]
+}You should adjust to the minimal set of access rights depending on your specific use case.
+Quarkus supports a feature called Dev Services that allows you to create various containers without any config.
+What that means in practice is that if you have Docker running and have not configured quarkus.vault.url,
+Quarkus will automatically start a Vault container when running tests or in dev mode, and automatically
+configure the connection.
When running the production version of the application, the Vault connection needs to be configured as normal,
+so if you want to include a production Vault config in your application.properties and continue to use Dev Services
+we recommend that you use the %prod. profile to define your Vault connection settings.
Most of the time you need to share the server between applications. +Dev Services for Vault implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.
+| + + | +
+Dev Services for Vault starts the container with the quarkus-dev-service-vault label which is used to identify the container.
+ |
+
If you need multiple (shared) servers, you can configure the quarkus.vault.devservices.service-name attribute and indicate the server name.
+It looks for a container with the same value, or starts a new one if none can be found.
+The default service name is vault.
Sharing is enabled by default in dev mode, but disabled in test mode.
+You can disable the sharing with quarkus.vault.devservices.shared=false.
To help with provisioning the automatically managed Vault instance, you can enable certain secret engines.
+| + + | +
+
+
+As mentioned above Vault containers started in dev mode automatically mount the kv secret engine v2
+at |
+
Enable the Transit Secret Engine at transit/ using:
quarkus.vault.devservices.transit-enabled=trueEnable the PKI Secret Engine at pki/ using:
quarkus.vault.devservices.pki-enabled=trueAs a general matter, you should consider reading the extensive Vault documentation +and apply best practices.
+The features exposed today through the Vault extension covers only a small fraction of what the product is capable of. +Still, it addresses already some of the most common microservices scenarii (e.g. sensitive configuration and database +credentials), which goes a long way towards creating secured applications.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether or not an health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies if being a standby should still return the active status code instead of the standby status code. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies if being a performance standby should still return the active status code instead of the performance standby status code. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a vault instance when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Indicates if the Vault instance managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Vault starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Vault instances. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Should the Transit secret engine be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Should the PKI secret engine be enabled +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Custom container initialization commands +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Microprofile Config ordinal. +
+
+This is provided as an alternative to the
+
+The default value is higher than the file system or jar ordinals, but lower than env vars. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Vault server url.
+<p>
+Example: https://localhost:8200
+<p>
+See also the documentation for the
+
+Environment variable: |
++ | + |
+
+
+
+
+
+Renew grace period duration. +<p> +This value if used to extend a lease before it expires its ttl, or recreate a new lease before the current +lease reaches its max_ttl. +By default Vault leaseDuration is equal to 7 days (ie: 168h or 604800s). +If a connection pool maxLifetime is set, it is reasonable to set the renewGracePeriod to be greater +than the maxLifetime, so that we are sure we get a chance to renew leases before we reach the ttl. +In any case you need to make sure there will be attempts to fetch secrets within the renewGracePeriod, +because that is when the renewals will happen. This is particularly important for db dynamic secrets +because if the lease reaches its ttl or max_ttl, the password of the db user will become invalid and +it will be not longer possible to log in. +This value should also be smaller than the ttl, otherwise that would mean that we would try to recreate +leases all the time. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Vault config source cache period.
+<p>
+Properties fetched from vault as MP config will be kept in a cache, and will not be fetched from vault
+again until the expiration of that period.
+This property is ignored if
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of comma separated vault paths in kv store,
+where all properties will be available as MP config properties as-is, with no prefix.
+<p>
+For instance, if vault contains property
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Maximum number of attempts when fetching MP Config properties on the initial connection. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Used to hide confidential infos, for logging in particular. +Possible values are: +<p> +* low: display all secrets. +* medium: display only usernames and lease ids (ie: passwords and tokens are masked). +* high: hide lease ids and dynamic credentials username. +
+
+Environment variable: |
+
+
|
+
|
+
+
+
+
+
+
+Kv secret engine version. +<p> +see https://www.vaultproject.io/docs/secrets/kv/index.html +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+KV secret engine path.
+<p>
+This value is used when building the url path in the KV secret engine programmatic access
+(i.e.
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Timeout to establish a connection with Vault. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Request timeout on Vault. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+List of remote hosts that are not proxied when the client is configured to use a proxy. This list serves the same purpose as the JVM
+
+Entries can use the * wildcard character for pattern matching, e.g *.example.com matches www.example.com. +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+The proxy host. If set the client is configured to use a proxy. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+The port the proxy is listening on, 3128 by default. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+List of comma separated vault paths in kv store,
+where all properties will be available as prefixed MP config properties.
+<p>
+For instance if the application properties contains
+
+
+Environment variable: |
+list of string |
+required |
+
+
+
+
+
+
+Dynamic credentials' role.
+<p>
+Roles are defined by the secret engine in use. For example,
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Mount of dynamic credentials secrets engine, for example
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Path of dynamic credentials request.
+<p>
+Request paths are dictated by the secret engine in use. For standard secret engines this should be
+left as the default of
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+A path in vault kv store, where we will find the kv-key.
+<p>
+One of
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Key name to search in vault path
+
+Environment variable: |
+string |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Vault Enterprise namespace
+<p>
+If set, this will add a
+
+Environment variable: |
+string |
++ |
| + | Type |
+Default |
+
+
+
+
+
+
+Vault token, bypassing Vault authentication (kubernetes, userpass or approle). This is useful in development where an authentication mode might not have been set up. In production we will usually prefer some authentication such as userpass, or preferably kubernetes, where Vault tokens get generated with a TTL and some ability to revoke them. Lease renewal does not apply. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client token wrapped in a wrapping token, such as what is returned by: +
+
+vault token create -wrap-ttl=60s -policy=myapp +
+
+client-token and client-token-wrapping-token are exclusive. Lease renewal does not apply. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Role Id for AppRole auth method. This property is required when selecting the app-role authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Secret Id for AppRole auth method. This property is required when selecting the app-role authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Wrapping token containing a Secret Id, obtained from: +
+
+vault write -wrap-ttl=60s -f auth/approle/role/myapp/secret-id +
+
+secret-id and secret-id-wrapping-token are exclusive +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Allows configure Approle authentication mount path. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+User for userpass auth method. This property is required when selecting the userpass authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Password for userpass auth method. This property is required when selecting the userpass authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Wrapping token containing a Password, obtained from: +
+
+vault kv get -wrap-ttl=60s secret/ +
+
+The key has to be 'password', meaning the password has initially been provisioned with: +
+
+vault kv put secret/ password= +
+
+password and password-wrapping-token are exclusive +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Kubernetes authentication role that has been created in Vault to associate Vault policies, with Kubernetes service accounts and/or Kubernetes namespaces. This property is required when selecting the Kubernetes authentication type. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Location of the file containing the Kubernetes JWT token to authenticate against in Kubernetes authentication mode. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Allows configure Kubernetes authentication mount path. +
+
+Environment variable: |
+string |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Allows to bypass certificate validation on TLS communications. +
+
+If true this will allow TLS communications with Vault, without checking the validity of the certificate presented by Vault. This is discouraged in production because it allows man in the middle type of attacks. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Certificate bundle used to validate TLS communications with Vault. +
+
+The path to a pem bundle file, if TLS is required, and trusted certificates are not set through javax.net.ssl.trustStore system property. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If true and Vault authentication type is kubernetes, TLS will be active and the cacert path will be set to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. If set, this setting will take precedence over property quarkus.vault.tls.ca-cert. This means that if Vault authentication type is kubernetes and we want to use quarkus.vault.tls.ca-cert or system property javax.net.ssl.trustStore, then this property should be set to false. +
+
+Environment variable: |
+boolean |
+
|
+
| + | Type |
+Default |
+
+
+
+
+
+
+Specifies the name of the key to use. By default this will be the property key alias. Used when +the same transit key is used with different configurations. Such as in: +
+
+
+
+
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Set to true when the input is already hashed. Applies to sign operations. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+When using a RSA key, specifies the RSA signature algorithm. Applies to sign operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the hash algorithm to use for supporting key types. Applies to sign operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the type of key to create for the encrypt operation. Applies to encrypt operations. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. Applies to encrypt operations. +
+
+Environment variable: |
+string |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Working with Vault is typically a 2 step process:
+Logging in, which returns a client token
+Start using Vault using the client token, within the limits of what is allowed by the policies associated with the token
+There are several Vault authentication methods supported in Quarkus today, namely:
+Token: whenever you already have a token
+Userpass: authenticate with a username and a password
+AppRole: authenticate with a role id and a secret id (which can +be seen as a Userpass for automated workflows - machines and services)
+Kubernetes, which is applicable to workloads deployed into Kubernetes
+This guide aims at providing examples for each of those authentication methods.
+To complete this guide, you need:
+to complete the Vault guide
+roughly 30 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+For the Kubernetes authentication: A Kubernetes distribution to deploy the Quarkus application (Minishift, K3s, Docker Desktop, …)
+We assume there is a Vault container and a PostgreSQL container running from the Vault guide, and the root token is known.
+First, create a new shell, docker exec into the container and set the root token:
docker exec -it dev-vault sh
+/ # export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2Create a token for the vault-quickstart-policy policy:
/ # vault token create -policy=vault-quickstart-policy
+Key Value
+--- -----
+token s.JqMeE1UEyUb19F6zmMW0SWx6
+token_accessor q1ynY9T7FDgbMKd3uST7RzLy
+token_duration 768h
+token_renewable true
+token_policies ["default" "vault-quickstart-policy"]
+identity_policies []
+policies ["default" "vault-quickstart-policy"]Now use the generated client token in the application configuration:
+quarkus.vault.authentication.client-token=s.JqMeE1UEyUb19F6zmMW0SWx6Compile and start the application:
+./mvnw clean install
+java -jar target/quarkus-app/quarkus-run.jarFinally test the application endpoint:
+curl http://localhost:8080/hello/private-keyYou should see: 123456.
One drawback of this approach is that you expose a secret piece of information (i.e. the token) that can give access +to sensitive data in Vault. This requires ensuring that the application’s configuration stays secure at all time. +If an intruder was to access the client token, it would be able to start calling Vault on all endpoints permitted +by the policy.
+This risk can be mitigated using an approach called +Response Wrapping (which used to be known as +Cubbyhole Authentication in older versions of Vault). This principle is simple: instead of configuring the +client token itself, we hide it inside a Wrapping Token, which we provide to the application. Upon startup, +the application will unwrap the Wrapping Token, and fetch the real token from within. The additional level of +security comes from the fact that the Wrapping Token is short lived (from a few seconds to a few minutes; +basically just enough to start and unwrap the token), and can be unwrapped only once. +If the Wrapping Token gets stolen and unwrapped, we will notice immediately because the legitimate application +will get an error saying that the token is invalid.
+With that in mind, let’s create a new token and wrap it inside a Wrapping Token with a TTL of 1 minute:
+/ # vault token create -wrap-ttl=60s -policy=vault-quickstart-policy
+Key Value
+--- -----
+wrapping_token: s.2cLMBoKhelDK6W3uAFT2umXu
+wrapping_accessor: ojvbOtmLzB5D47SzXGo9b3sR
+wrapping_token_ttl: 1m
+wrapping_token_creation_time: 2020-04-14 16:05:20.990240428 +0000 UTC
+wrapping_token_creation_path: auth/token/create
+wrapped_accessor: a4ITYQNnQtwCOUmV5DJMpCiGNow let’s use this wrapping token in the configuration:
+quarkus.vault.authentication.client-token-wrapping-token=s.2cLMBoKhelDK6W3uAFT2umXuCompile and run the application without the tests, you should be able now to curl the private key 123456 as before.
Stop the application, and execute tests with ./mvnw test. They should fail with the following error:
ERROR: Failed to start application
+io.quarkus.vault.VaultException: wrapping token is not valid or does not exist; this means that the token has already expired (if so you can increase the TTL on the wrapping token) or has been consumed by somebody else (potentially indicating that the wrapping token has been stolen)Normally the userpass auth method should already be enabled from the Vault guide. If not, execute the following
+commands now:
vault auth enable userpass
+vault write auth/userpass/users/bob password=sinclair policies=vault-quickstart-policyAnd simply specify the username and password for this user in the application configuration:
+quarkus.vault.authentication.userpass.username=bob
+quarkus.vault.authentication.userpass.password=sinclairTest the application endpoint after compiling and starting the application again:
+curl http://localhost:8080/hello/private-keyYou should see: 123456.
| + + | +
+
+
+Userpass supports response wrapping as well for the |
+
Approle is an authentication method suited for technical workflows. It relies on 2 pieces of information:
+role id can be compared to the user name in Userpass
+secret id plays the role of the password
To set up Approle you need to enable the approle auth method, create an app role,
+and generate a role id and secret id:
/ # vault auth enable approle
+/ # vault write auth/approle/role/myapprole policies=vault-quickstart-policy
+
+/ # vault read auth/approle/role/myapprole/role-id
+Key Value
+--- -----
+role_id b15460ff-fea0-43fc-1002-a045fb60dfc4
+
+/ # vault write -f auth/approle/role/myapprole/secret-id
+Key Value
+--- -----
+secret_id d2f13e1f-f32a-f60a-86d8-0b5cdaeb821b
+secret_id_accessor 2acff656-d049-c4b3-a752-6125e69210baAdd the appropriate properties:
+quarkus.vault.authentication.app-role.role-id=b15460ff-fea0-43fc-1002-a045fb60dfc4
+quarkus.vault.authentication.app-role.secret-id=d2f13e1f-f32a-f60a-86d8-0b5cdaeb821bAfter compiling and running the application you should be able to curl it on the
+private-key endpoint to see the secret information 123456 as usual.
Similarly to direct client token authentication, it is possible to wrap the secret-id:
/ # vault write -wrap-ttl=60s -f auth/approle/role/myapprole/secret-id
+Key Value
+--- -----
+wrapping_token: s.aSq7tcRqfeboZqLMPfa5gkXJ
+wrapping_accessor: u5EPZOnqyIJN8mT44od67WMS
+wrapping_token_ttl: 1m
+wrapping_token_creation_time: 2020-04-14 16:59:25.482352967 +0000 UTC
+wrapping_token_creation_path: auth/approle/role/myapprole/secret-idReplace the secret-id property with secret-id-wrapping-token in the configuration:
quarkus.vault.authentication.app-role.secret-id-wrapping-token=s.aSq7tcRqfeboZqLMPfa5gkXJFinally, recompile the application without tests (otherwise you are going to consume the wrapping token),
+launch it and curl the private-key endpoint. As usual, you should see 123456.
Vault provides an integration with Kubernetes to allow containers to authenticate with Vault using their
+Kubernetes JWT token located in /var/run/secrets/kubernetes.io/serviceaccount.
The setup is more involved than with the other auth methods because we need to allow Vault to talk +to the master API to be able to validate the JWT token that the application will authenticate with.
+The first step involves creating a vault-auth-sa service account with auth-delegator
+role that Vault will use to communicate with the master API.
First create file vault-auth-k8s.yml:
---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+name: vault-auth-sa
+---
+kind: ClusterRoleBinding
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+name: vault-auth-delegator
+subjects:
+- kind: User
+name: vault-auth-sa
+namespace: default
+roleRef:
+kind: ClusterRole
+name: system:auth-delegator
+apiGroup: rbac.authorization.k8s.ioAnd apply it: kubectl apply -f vault-auth-k8s.yml.
Once the objects are created, we need to capture the JWT token of this service account, +and grab the public certificate of the cluster:
+secret_name=$(kubectl get sa vault-auth-sa -o json | jq -r '.secrets[0].name')
+token=$(kubectl get secret $secret_name -o json | jq -r '.data.token' | base64 --decode)
+echo token=$token
+kubectl get secret $secret_name -o json | jq -r '.data."ca.crt"' | base64 -D > /tmp/ca.crtThe next step requires to exec interactively with the root token into the Vault container +to configure the Kubernetes auth method:
+docker exec -it dev-vault sh
+export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2Once inside the pod, set the token variable to the value that was just printed in the console before, and
+recreate ca.crt with the same content as /tmp/ca.crt outside the container. Finally use kubectl config view
+to assess the url of your Kubernetes cluster:
token=... => set the value printed in the console just before
+vi ca.crt => copy/paste /tmp/ca.crt from outside the container
+kubernetes_host => url from the kubectl config view (e.g. https://kubernetes.docker.internal:6443)Now we have all the information we need to configure Vault:
+vault auth enable kubernetes
+
+# configure master API access from Vault
+vault write auth/kubernetes/config \
+ token_reviewer_jwt=$token \
+ kubernetes_host=$kubernetes_host \
+ kubernetes_ca_cert=@ca.crt
+
+# create vault-quickstart-role role
+vault write auth/kubernetes/role/vault-quickstart-role \
+ bound_service_account_names=vault-quickstart-sa \
+ bound_service_account_namespaces=default \
+ policies=vault-quickstart-policy \
+ ttl=1hAdd the following properties to the application (and remove any other authentication Vault property,
+plus replace <host> by the ip or name of the local host that is running the Vault and PostgreSQL containers,
+such that they will be accessible from the pod):
quarkus.vault.url=http://<host>:8200
+quarkus.datasource.db-kind=postgresql
+quarkus.datasource.username=<your username>
+quarkus.datasource.password=<your password>
+quarkus.datasource.jdbc.url = jdbc:postgresql://<host>:5432/mydatabase
+
+quarkus.vault.authentication.kubernetes.role=vault-quickstart-role
+
+quarkus.log.category."io.quarkus.vault".level=DEBUGNow build the application:
+./mvnw package -DskipTests
+docker build -f src/main/docker/Dockerfile.jvm -t quarkus/vault-quickstart-jvm .Create a vault-quickstart-k8s.yml file with:
---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: vault-quickstart-sa
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ labels:
+ app: vaultapp
+ name: vaultapp
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: vaultapp
+ template:
+ metadata:
+ labels:
+ app: vaultapp
+ spec:
+ serviceAccountName: vault-quickstart-sa
+ containers:
+ - image: quarkus/vault-quickstart-jvm
+ imagePullPolicy: Never
+ name: vaultapp
+ ports:
+ - containerPort: 8080
+ name: vaultport
+ protocol: TCP
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: vaultapp
+ labels:
+ app: vaultapp
+spec:
+ type: NodePort
+ ports:
+ - name: vault
+ port: 8080
+ nodePort: 30400
+ selector:
+ app: vaultappAnd apply it: kubectl apply -f vault-quickstart-k8s.yml.
This will deploy the application, and make it available on port 30400 of the Kubernetes host.
You can check that the application has started from the logs:
+kubectl get pods
+pod=$(kubectl get pod -l app=vaultapp -o json | jq -r '.items[0].metadata.name')
+kubectl logs $podYou should see:
+exec java -Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager -XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -XX:MinHeapFreeRatio=20 -XX:MaxHeapFreeRatio=40 -XX:+ExitOnOutOfMemoryError -cp . -jar /deployments/app.jar
+__ ____ __ _____ ___ __ ____ ______
+ --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
+ -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
+--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
+2020-04-15 18:30:00,983 DEBUG [io.qua.vau.run.con.VaultConfigSource] (main) loaded vault runtime config VaultRuntimeConfig{url=Optional[http://<host>:8200], kubernetesAuthenticationRole=vault-quickstart-role, kubernetesJwtTokenPath='/var/run/secrets/kubernetes.io/serviceaccount/token', userpassUsername='', userpassPassword='***', appRoleRoleId='', appRoleSecretId='***', appRoleSecretIdWrappingToken='***', clientToken=***, clientTokenWrappingToken=***, renewGracePeriod=PT1H, cachePeriod=PT10M, logConfidentialityLevel=MEDIUM, kvSecretEngineVersion=2, kvSecretEngineMountPath='secret', tlsSkipVerify=false, tlsCaCert=Optional.empty, connectTimeout=PT5S, readTimeout=PT1S}
+2020-04-15 18:30:00,985 DEBUG [io.qua.vau.run.con.VaultConfigSource] (main) loaded vault buildtime config io.quarkus.vault.runtime.config.VaultBuildTimeConfig@4163f1cd
+2020-04-15 18:30:01,310 DEBUG [io.qua.vau.run.cli.OkHttpClientFactory] (main) create SSLSocketFactory with tls /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+2020-04-15 18:30:01,559 DEBUG [io.qua.vau.run.VaultAuthManager] (main) authenticate with jwt at: /var/run/secrets/kubernetes.io/serviceaccount/token => ***
+2020-04-15 18:30:01,779 DEBUG [io.qua.vau.run.VaultAuthManager] (main) created new login token: {clientToken: ***, renewable: true, leaseDuration: 3600s, valid_until: Wed Apr 15 19:30:01 GMT 2020}
+2020-04-15 18:30:01,802 DEBUG [io.qua.vau.run.con.VaultConfigSource] (main) loaded 1 properties from vault
+2020-04-15 18:30:02,722 DEBUG [io.qua.vau.run.VaultAuthManager] (Agroal_7305849841) extended login token: {clientToken: ***, renewable: true, leaseDuration: 3600s, valid_until: Wed Apr 15 19:30:02 GMT 2020}
+2020-04-15 18:30:03,274 INFO [io.quarkus] (main) vault-quickstart 1.0.0-SNAPSHOT (powered by Quarkus 999-SNAPSHOT) started in 4.255s. Listening on: http://0.0.0.0:8080
+2020-04-15 18:30:03,276 INFO [io.quarkus] (main) Profile prod activated.
+2020-04-15 18:30:03,276 INFO [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-postgresql, narayana-jta, resteasy, vault]Notice in particular the following log line:
+authenticate with jwt at: /var/run/secrets/kubernetes.io/serviceaccount/token => ***Finally curl the private-key endpoint to make sure you can retrieve your secret:
curl http://localhost:30400/hello/private-keyYou should see 123456.
The most common use case when working with Vault is to keep confidential the database connection credentials. +There are several approaches that are supported in Quarkus, with different levels of sophistication +and security:
+Property fetched from the KV Secret Engine using the Vault MicroProfile Config Source
+Quarkus Credentials Provider
+Vault Dynamic DB Credentials
+This guide aims at providing examples for each of those approaches. We will reuse the application implemented +in the Vault guide and enhance it with a simple persistence use case.
+To complete this guide, you need:
+to complete the Vault guide
+roughly 20 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+We assume the Vault guide application has been developed, a Vault container is running, and the root token is known. +In this section we are going to start a PostgreSQL database, and add a persistence service in the application.
+Add the Hibernate and PostgreSQL extensions to the application:
+mvn quarkus:add-extension -Dextensions="io.quarkus:quarkus-hibernate-orm,io.quarkus:quarkus-jdbc-postgresql"+
Create a simple service:
+@ApplicationScoped
+public class SantaClausService {
+
+ @Inject
+ EntityManager em;
+
+ @Transactional
+ public List<Gift> getGifts() {
+ return (List<Gift>) em.createQuery("select g from Gift g").getResultList();
+ }
+}With its Gift entity:
@Entity
+public class Gift {
+
+ private Long id;
+ private String name;
+
+ @Id
+ @GeneratedValue(strategy = GenerationType.SEQUENCE, generator="giftSeq")
+ public Long getId() {
+ return id;
+ }
+
+ public void setId(Long id) {
+ this.id = id;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}Finally, add a new endpoint in GreetingResource:
@Inject
+SantaClausService santaClausService;
+
+@GET
+@Path("/gift-count")
+@Produces(MediaType.TEXT_PLAIN)
+public int geGiftCount() {
+ return santaClausService.getGifts().size();
+}Start a PostgreSQL database:
+docker run --ulimit memlock=-1:-1 -it --rm=true --memory-swappiness=0 --name postgres-quarkus-hibernate -e POSTGRES_USER=sarah -e POSTGRES_PASSWORD=connor -e POSTGRES_DB=mydatabase -p 5432:5432 postgres:10.5Now we are ready to configure Vault and Quarkus to be able to connect to this database from the application.
+The simplest approach is to write the database password in the KV secret engine under the path that is +fetched from the Vault Config Source.
+Open a new shell, docker exec in the Vault container and set the root token:
docker exec -it dev-vault sh
+export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2Add a dbpassword property in the config path of the KV secret engine, beside the original a-private-key
+property:
vault kv put secret/myapps/vault-quickstart/config a-private-key=123456 dbpassword=connorAdd the following configuration in Quarkus to use the value of property dbpassword as our database password:
# configure your datasource
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.username = sarah
+quarkus.datasource.password = ${dbpassword}
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/mydatabase
+
+# drop and create the database at startup (use `update` to only update the schema)
+quarkus.hibernate-orm.database.generation=drop-and-createCompile and start the application:
+./mvnw package
+java -jar target/quarkus-app/quarkus-run.jarTest it with the gift-count endpoint:
curl http://localhost:8080/hello/gift-countYou should see:
+0This approach is certainly the simplest of all. It has also the big advantage of working with any subsystem +that requires a secret information in the configuration (i.e. not just Agroal). +The only drawback is that the password will never be fetched again from Vault after the initial property loading. +This means that if the db password was changed while running, the application would have to be restarted after +Vault has been updated with the new password. +This contrasts with the credentials provider approach, which fetches the password from Vault every time a connection +creation is attempted.
+In this approach we introduce a new abstraction called the Credentials Provider that acts as an intermediary +component between the Agroal datasource and Vault. The additional configuration required is small, and it +has the major advantage of handling gracefully database password change while the application is running, +without any restart. Since all new connections go through the Credentials Provider to fetch their password, +we make sure we have a fresh value every time.
+Create a new path (different than the config path) in Vault where the database password will be added:
vault kv put secret/myapps/vault-quickstart/db password=connorSince we allowed read access on secret/myapps/vault-quickstart/* subpaths in the policy, there is nothing else
+we have to do to allow the application to read it.
When fetching credentials from Vault that are intended to be used by the Agroal connection pool, we need +first to create a named Vault credentials provider in the application.properties:
+quarkus.vault.credentials-provider.mydatabase.kv-path=myapps/vault-quickstart/dbThis defines a credentials provider mydatabase that will fetch the password from key password
+at path myapps/vault-quickstart/db.
The credentials provider can now be used in the datasource configuration, in place of the password
+property:
# configure your datasource
+quarkus.datasource.db-kind = postgresql
+quarkus.datasource.username = sarah
+quarkus.datasource.credentials-provider = mydatabase
+quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/mydatabaseRecompile, start and test the gift-count endpoint. You should see 0 again.
The two previous approaches work well and are very popular. However they rely on a well known user configured +in the application (i.e. the database user), and the security comes from the confidentiality of the password. +If the password was stolen, we would have to change it in the database and in Vault. Regularly rotating passwords +is actually a very good practice to limit (in time) the impact of getting the password stolen.
+A more sophisticated approach consists in letting Vault create and retire database accounts on a regular basis. +This is supported in Vault with the Database secret engine. A number +of databases are supported, such as PostgreSQL.
+First we need to enable the database secret engine, configure the postgresql-database-plugin and create
+the database role mydbrole (replace 10.0.0.3 by the actual host that is running the PostgreSQL container;
+for simplicity we disabled TLS between Vault and the PostgreSQL database):
vault secrets enable database
+
+vault write database/config/mydb \
+ plugin_name=postgresql-database-plugin \
+ allowed_roles=mydbrole \
+ connection_url=postgresql://{{username}}:{{password}}@10.0.0.3:5432/mydatabase?sslmode=disable \
+ username=sarah \
+ password=connor
+
+cat <<EOF > vault-postgres-creation.sql
+CREATE ROLE "{{name}}" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "{{name}}";
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public to "{{name}}";
+EOF
+
+vault write database/roles/mydbrole \
+ db_name=mydb creation_statements=@vault-postgres-creation.sql \
+ default_ttl=1h \
+ max_ttl=24h \
+ revocation_statements="ALTER ROLE \"{{name}}\" NOLOGIN;" \
+ renew_statements="ALTER ROLE \"{{name}}\" VALID UNTIL '{{expiration}}';"| + + | +
+
+
+For this use case, user |
+
Then we need to give a read capability to the Quarkus application on path database/creds/mydbrole.
cat <<EOF | vault policy write vault-quickstart-policy -
+path "secret/data/myapps/vault-quickstart/*" {
+ capabilities = ["read", "create"]
+}
+path "database/creds/mydbrole" {
+ capabilities = [ "read" ]
+}
+EOFNow that Vault knows how to create users in PostgreSQL, we just need to change the mydatabase credentials
+provider to use credentials-role & credentials-mount.
quarkus.vault.credentials-provider.mydatabase.credentials-role=mydbrole
+quarkus.vault.credentials-provider.mydatabase.credentials-mount=database| + + | +
+
+
+When using |
+
Finally, we need to tell our Quarkus database configuration to recycle connections before the lease TTL we +configured in Vault. This will ensure the database connection will always use valid credentials.
+In this example the default TTL is set to 1 hour, so we will recycle connections every 30 minutes:
+quarkus.datasource.jdbc.max-lifetime=30m+
| + + | +
+
+
+When using a reactive datasource you will need to use the |
+
Recompile with ./mvnw package, start and test the gift-count endpoint. You should see 0 again.
Notice in the logs:
+2020-04-22 14:29:48,522 DEBUG [io.qua.vau.run.VaultDbManager] (Agroal_682171661) generated mydbrole credentials: {leaseId: database/creds/mydbrole/L6PxoI68gZDeVPXP0RAA4c0a, renewable: true, leaseDuration: 60s, valid_until: Wed Apr 22 14:30:48 CEST 2020, username: v-userpass-mydbrole-HeOMJCmy9coEnO2my2AR-1587558588, password:***}If you connect to the PostgreSQL database, and list all users configured on mydatabase, you will see the
+sarah super user, but also the technical users dynamically created by Vault:
docker exec -it postgres-quarkus-hibernate bash
+psql mydatabase sarah
+
+mydatabase=# \du
+ List of roles
+ Role name | Attributes | Member of
+-----------------------------------------------------+------------------------------------------------------------+-----------
+ sarah | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
+ v-userpass-mydbrole-HeOMJCmy9coEnO2my2AR-1587558588 | Password valid until 2020-04-22 12:30:53+00 | {}
+ v-userpass-mydbrole-N2ITbBXxoqMQ3A3cZL88-1587558572 | Cannot login +| {}
+ | Password valid until 2020-04-22 12:30:37+00 |
+As you can see 2 users have been created:
+v-userpass-mydbrole-N2ITbBXxoqMQ3A3cZL88-1587558572 that has expired, which was created while we were executing the tests.
v-userpass-mydbrole-HeOMJCmy9coEnO2my2AR-1587558588 that is valid until 12:30:53.
As expected, users have been created dynamically by Vault, with expiration dates, allowing a rotation to occur, +without breaking existing connections, allowing a greater level of security than the traditional +password based approaches.
+The generator is designed specifically for easily generating Java POJOs, and API classes that target Vault system and plugin APIs. It uses YAML files, referred to as a "specs", that each describe an API in very Java-centric terms.
+Currently, the generator is used to generate the supported native Vault system apis and secret plugin apis. That being said, a long-term goal for the generator is that users with custom Vault plugins will be able to generate API objects for them as well.
+The generator can be called directly from the command line, or via Maven using the exec-maven-plugin; the Quarkus Vault client uses the latter approach (while using the build-helper-maven-plugin to only regenerate when the specs are out of date).
The generator produces three main types for each API:
+The main class for accessing an associated Vault API. Each method represents an endpoint of the associated API. All the methods are reactive and return a Smallrye Mutiny Uni. Internally, the API uses another generated class, a request factory, to build Vault API requests. The API either returns the unaltered response from Vault, or for certain endpoints, unwraps the useful data nested in the raw Vault response.
The API uses the request factory to build Vault API requests. It is also reactive and returns a Smallrye Mutiny Uni. The request factory is generated from the same spec as the API, and is designed to be used by the API. In general, it is not intended to be used directly by end users. Although, because Vault APIs are diverse and complex, it is possible that end users can use the request factory directly to build requests that can be modified in a way not directly supported by the API.
The generator also produces DTO POJO classes that are used by the API to represent the data that is sent to and received from Vault. The DTO classes are generated from the same spec as the API and request factory, with many of them being implied by the request parameters or result types. Additionally, spec files can declare shared DTOs that can be used by multiple APIs. DTOs can also be enumerated types.
+The generator uses a YAML file to describe the API. The spec file is designed to be very Java-centric, while intending to be a fairly direct representation of the Vault API. The spec file is designed to be easily understood by Java developers with knowledge of Vault APIs.
+All the Java types referenced in the spec support Java generics, including wildcards and type parameter bounds.
+The spec file is divided into the following sections:
+The API section describes the API itself, including the name, the Vault API path, wether the API is mountable at different paths, and base OTel tracing titles.
+The operations section describes the API endpoints. Each operation is described in terms of its HTTP method, nested path, method parameters and result type. The parameters can used in a the path, query parameters or request body. The result type is can take a few forms, be it a "leased" result (the standard Vault response format), a plain DTO, or a raw binary/string value. Parameters and results can define "simple" DTOs inline as needed, refer to shared DTOs defined in the types section, or even refer to types defined in other specs or the client itself.
+The types section describes the DTOs used by the API. DTOs are described in terms of their fields, which are either primitive types, or other DTOs. DTOs can also be enumerated types.
+The enums section describes the enumerated types used by the API. Enumerated types are described in terms of their values.
+The API sections consists of the following fields:
+name: # required
+category: # defaults to empty
+prefix: # defaults to "Vault"
+packageName: # defaults to "io.quarkus.vault.client.api"
+relativePackageName: # defaults to lowercase "<category>.<name>"
+traceNameTag: # defaults to lowecase "<name>"
+basePath: # defaults to empty
+mountable: # defaults to true
+namespaced: # defaults to trueThe name of the API. This is used to generate the API class name, and is also used to generate the request factory class name. The full name of each class is prefixed with the prefix field and the capitalized category field.
The category of the API. This is used when forming the API class name, request factory class name and the Java package name all the types will be generated in. While it defaults to empty, it should be specified as secrets for secret plugins and as auth for authentication plugins.
The prefix used when forming the API class name and request factory class name. It defaults to Vault and probably should not be changed/specified.
The base Java package name for all types, not just those generated by the spec. It defaults to io.quarkus.vault.client.api and probably should not be changed/specified.
The relative Java package name for all types generated by the spec. It defaults to the lowercase category field, followed by a dot, followed by the lowercase name field. It is relative to the packageName field.
The OpenTelemetry trace name tag for the API. It defaults to the lowercase name field. The full tag for each operation is of the form "Vault [<category> (<traceNameTag>)] <operationTitle>". The operation title is generated by converting the operation name from camel-case to title-case.
The base path for the API. It defaults to empty. The base path is used to form the full path for each operation. The full path for each operation is of the form "<basePath>/<operationPath>". The operation path is specified for each operation.
+Whether the API is mountable at different paths. It defaults to true. If true, each operation’s path will have a mount path injected in the approprate location. For all plugins this should be true. For system APIs (i.e., those under /sys) this should be false.
Whether the API is namespaced. It defaults to true. If true, each operation’s request will have a namespace injected into each request according to the configuration of the VaultClient.
The operations section is an array of operation definitions. Each operation definition consists of the following fields:
+name: # required
+method: # defaults to "GET" (one of "GET", "POST", "PUT", "PATCH", "DELETE", "LIST", "HEAD")
+path: # required if 'pathChoice` is not specified
+pathChoice: # required if 'path' is not specified
+trace: # defaults to title case of 'name'
+authenticated: # defaults to true
+namespaced: # defaults to true
+tokenFrom: # defaults to null
+wrapTTLFrom: # defaults to null
+bodyFrom: # defaults to null
+bodyType: # defaults to null
+queryFrom: # defaults to null
+headers: # defaults to an empty list
+typeParameters: # defaults to an empty list
+parameters: # defaults to an empty list
+result: # defaults to null
+recoverNotFound: # defaults to nullThe name of the operation. This is used to generate the method name in the API class. It is also converted to title case and used as the operation title for OpenTelemetry tracing.
+The HTTP method for the operation. It defaults to GET. The method specifies the HTTP method used for the operation as required by Vault.
The path for the operation. This is used to generate the full path for the operation. The full path is of the form "<basePath>/<path>". The path can contain parameters (specified as ':paramName`) that are replaced with the appropriate value from the operation’s parameters. The path will also contain a mount path is injected into the appropriate location if the API is mountable.
+The patch choice field can be used in place of the path field to specify a choice of paths based on the value of a parameter. The path choice field is an array of path choice definitions. The path choice definition consists of the following fields:
param: # name of the parameter to use the value to select the path
+choices: # array of path choice values
+ value: # the value of the parameter that selects this path
+ path: # the path to use if the parameter has the specified valueThe path field in each choice can be complex and and contain parameter references just like the main path field.
The OpenTelemetry trace name tag for the operation. It defaults to the title case of the name field. The full tag for each operation is of the form "Vault [<category> (<traceNameTag>)] <operationTitle>".
Whether the operation requires authentication. It defaults to true. If true, the operation will have a token injected into each request according to the configuration of the VaultClient.
Whether the operation requires a namespace. It defaults to true. If true, the operation will have a namespace injected into each request according to the configuration of the VaultClient.
If an operation parameter needs to be used as the token for the operation, this field can be used to specify the name of the parameter. If specified, the parameter will be used as the token for the operation, overriding the token injected by the VaultClient.
If the operation response is to be wrapped according to Vault response wrapping rules, this field can be used to specify the name of the parameter that contains the TTL for the wrapping.
+If the operation has a request body built solely from one or more parameters, this field can be used to specify the name of the parameters that contains the body. It is specified as a list of parameter names.
+If the operation has a request body that is a DTO declared elsewhere, this field specifies the full java type name for that type.
+If the operation requires query parameters in the request URL, this field is a list of parameter names that should be used as query parameters. Each query parameter will use the parameter name as the query parameter name, and the parameter value as the query parameter value.
+If the operation requires additional headers in the request, this field is a map of header names to values. Each header value can be literal or specify a parameter name to use as the header value (using the :paramName syntax).
If the operation is a generic method, this field is a list of type parameter names to use for the method (possibly with bounds information if needed).
+The parameters for the operation. This is an array of parameter definitions. Each parameter definition consists of the following fields:
+name: # required (in camel case)
+serializedName: # defaults to the snake case of 'name'
+required: # defaults to false
+body: # defaults to false
+includeIn: # defaults to null can be "API" or "Factory"
+annotations: # defaults to an empty list
+type: # defaults to null, required if 'object' is not specified
+object: # defaults to null, required if 'type' is not specifiedThe name of the parameter. This is used to generate the parameter name in the API method and in other instances.
+The serialized name of the parameter. This is used when the parameter is included in the request body (using bodyFrom) or as a query parameter. It defaults to the snake case of the name field.
Whether the parameter is required. It defaults to false. If true, the parameter will not be nullable in the API method.
+Whether the parameter is to be used as the request body. It defaults to false. If true, the parameter will be used as the request body and should be a DTO type.
+Where the parameter should be included. It defaults to null. If null, the parameter will be included in the API method and in the request factory method. If API, the parameter will only be included in the API method. If Factory, the parameter will only be included in the request factory method. This is a specialized parameter and very rarely should be used.
A list of Java annotations to add to the parameter.
+The Java type of the parameter. This is required if the object field is not specified. The type must be defined in the types section of the spec (or elsewhere).
An inline POJO definition of the parameter type. This is required if the type field is not specified.
The result type for the operation. It defaults to null. The result type comes in three different forms (specified in the kind field):
The result is a leased result. This is the standard Vault response format that returns an optional data field and an optional auth field along with other result properties. The generated Java method will return a wrapping result type (derived from the predefined VaultLeasedResult class) that has the data and auth properties defined by the result specification. The leased result definition consists of the following fields:
kind: leased
+data: # inline definition of data returned, required if `dataType` is not specified
+dataType: # name of the data type returned, required if `data` is not specified
+unwrapData: # defaults to false
+auth: # inline definition of auth returned, required if `authType` is not specified
+authType: # name of the auth type returned, required if `auth` is not specified
+unwrapAuth: # defaults to false
+unwrapUsing: # defaults to null
+unwrapUsingArguments: # defaults to an empty list
+unwrappedType: # defaults to nullThe data and auth fields can be specified as inline POJO definitions or as type names. If specified as type names, the type must be defined in the types section of the spec (or elsewhere). If either of these are not specified the type defaults to a java.lang.Object.
Many of the Vault API leased responses do not provide much useful information. To allow defining the DTOs inline while not requiring users to "see" the wrapping type, results can specify "unwrapping". Specifying unwrapData to true will cause the API method to return the data or dataType value directly. Specifying unwrapAuth to true will cause the API method to return the auth or authType value directly. Finally, you can specify unwrapUsing, unwrapUsingArguments and unwrappedType to do custom unwrapping. Together unwrapUsing and unwrapUsingArguments specify a Java Code Block, while the unwrappedType specifies the type returned by the code block.
The result is a standard JSON value. This is used for operations that return a simple JSON value, such as the sys/health/info endpoint.
kind: json
+type: # required if `object` is not specified
+object: # inline definition of the object returned, required if `type` is not specifiedEither the type or object field must be specified. If the type field is specified, the type must be defined in the types section of the spec (or elsewhere). If the object field is specified, it is an inline POJO definition.
The result is a raw binary or string value. This is used for operations that return a raw binary or string value.
+kind: raw
+type: # requiredThe type field must be specified and must be a Java type that is either byte[] or java.lang.String.
If the operation is expected to return a value instead of throwing a client error when a 404 is encountered, this field can be used to what, and how, that value is returned.The field is a map with the following fields:
+using: # required
+arguments: # defaults to an empty listThe using and arguments fields are used to specify a Java Code Block that will be used to recover from the 404.
The types section is an array of POJO definitions.
+The enums section is an array of enumerated type definitions.Each enumerated type definition consists of the following fields:
+name: # required
+values: # requiredThe methods section is an array of method definitions. Each method definition consists of the following fields:
+name: # required
+returnType: # required
+typeParameters: # defaults to an empty list
+parameters: # defaults to an empty list
+body: # defaults to null
+bodyArguments: # defaults to an empty list
+annotations: # defaults to an empty listThe name of the method. This is used to generate the method name in the owning class.
+The Java type of the method return value.
+If the method is a generic method, this field is a list of type parameter names to use for the method (possibly with bounds information if needed).
+The parameters for the method.This is a map of parameter names to Java types for each parameter.
+parameters:
+ someParameter: java.lang.String
+ anotherParameter: java.lang.IntegerPOJO definitions are specified in the Types Section or inline throughout different fields in the spec file. Inline POJO definitions are limited compared to those in the types section but still support a wide range of features, and they represent on the properties field of a full POJO definition.POJO definitions support of the following fields:
name: # required
+extends: # defaults to null
+implements: # defaults to an empty list
+annotations: # defaults to an empty list
+nested: # defaults to an empty list
+properties: # defaults to an empty list
+methods: # defaults to an empty listThe name of the POJO. This is used to generate the POJO class name.
+The name of class that this POJO extends; directly translates to the Java extends keyword.
A list of interfaces that this POJO implements; directly translates to the Java implements keyword.
A list of Java Annotations to add to the POJO class.
+A list of nested POJO definitions. Nested POJOs are defined inline but still support all the properties of a full POJO definition.
+A list of properties definitions for the POJO.Each property definition consists of the following fields:
+name: # required
+serializedName: # defaults to the snake case of 'name'
+type: # defaults to null, required if 'object' is not specified
+object: # defaults to null, required if 'type' is not specified
+annotations: # defaults to an empty list
+required: # defaults to falseThe name of the property. This is used to generate the property name in the POJO class.
+The serialized name of the property.It defaults to the snake case of the name field.
The Java type of the property.This is required if the object field is not specified.The type must be defined in the types section of the spec (or elsewhere).
An inline POJO definition of the property type.This is required if the type field is not specified.
A list of Java Annotations to add to the property.
+Whether the property is required.It defaults to false.If true, the property will not be nullable in the POJO class.
+Java annotations can be specified for POJOs, POJO properties, and POJO methods.Annotations are specified with the following fields:
+type: # required
+members: # defaults to an empty listThe Java type of the annotation.
+A map of annotation property members. Each property value is specified as:
+format: # required
+arguments: # defaults to an empty listTogether the format and arguments fields are simplified Java Code Block initializing the annotation member.
Here is a Jackson JsonSerialize annotation for a POJO property:
+type: com.fasterxml.jackson.databind.annotation.JsonSerialize
+members:
+- using: <type>com.example.SomeSerializerwhich would produce a Java annotation similar to:
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.example.SomeSerializer;
+
+class SomeClass {
+ @JsonSerialize(using = SomeSerializer.class)
+ String someProperty;
+}The generator uses JavaPoet to generate Java code.JavaPoet uses CodeBlock classes to generate Java code, as the project puts it, "beautifully".This requires specifying Java types as arguments to the code block to ensure they are imported correctly.The spec file supports specifying a limited set of the JavaPoet parameters for any code blocks in the spec files.
The spec files supports code block using the following argument forms in the code block text:
+The value will be expected to be a Java type and will be replaced with the appropriate, imported, Java type name.
+The value will be treated as a string value, and will be replaced in the code block with a quoted and escaped version of the provided value.
+The value will be expected to be a literal value and will be replaced in the code block with the exact string.
+Each code block will have arguments map or list.That specifies the value to use for each argument.When using a map format, argument <name>s are allowed, when using the list format no names can be specified.In either case the argument values can be in one of two formats.
+Any value that starts with <type> will be treated as a Java type name and should only be used with arguments that are specified using the $<name>:T format.
All other values will be considered strings and can be used with arguments that are specified using the $<name>:S or $<name>:L formats.
For code blocks that are expected to be complex, (e.g., method bodies in POJO definitions) the code block arguments will be specified as a map. For code blocks that expected to be simple (e.g., method return types) the code block arguments will be specified as a list.
+The following example is an excerpt from a POJO method definition that uses the map argument format:
+# code block with map arguments (names must be specified)
+name: test
+returnType: java.io.StringReader
+body: |
+ $wrapped:T $name:L = new $wrapped:T($value:S);
+ return $name:L;
+bodyArguments:
+ wrapped: <type>java.io.StringReader
+ name: value
+ value: "hello world"which generates the Java code similar to the following:
+import java.io.StringReader;
+
+class SomeClass {
+ StringReader test() {
+ StringReader value = "hello world";
+ return value;
+ }
+}The following example is an excerpt from an unwrapping code block that uses the list argument format:
+# code block with list arguments (no names can be specified)
+unwrapUsing: return new $T(r.getData());
+unwrapUsingArguments:
+- <type>java.io.StringReaderwhich generates Java code similar to the following:
+import java.io.StringReader;
+
+class SomeAPI {
+ Uni<StringReader> test() {
+ var request = buildRequest();
+ return request.map(r -> new StringReader(r.getData()));
+ }
+}Vault’s PKI Secret Engine generates dynamic X.509 certificates. It allows services to get certificates without +manually generating a private key and CSR, submitting to a CA, and waiting for signed certificate. The PKI secret +engine allows dynamically generating certificates, which has the following advantages over classic CA scenarios:
+Generating certificates with short TTLs reduces the need for and/or size of CRLs.
+Allows for ephemeral certificates that are generated upon application startup, stored in memory and discarded on shutdown.
+In this guide we cover the following:
+setup: configuring the engine to generate certificates
+generation: generating certificates using roles
+revocation: revoking a previously generated certificate
+To complete this guide, you need:
+to complete the "Starting Vault" section of the Vault guide
+roughly 15 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+We assume there is a Vault running from the Vault guide, and the root token is known. +The first step consists of activating the PKI Secret Engine, and configuring a CA certificate +and private key:
+docker exec -it dev-vault sh
+export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2
+
+vault secrets enable pki
+# ==> Success! Enabled the pki secrets engine at: pki/
+
+vault secrets tune -max-lease-ttl=8760h pki
+# ==> Success! Tuned the secrets engine at: pki/
+
+vault write pki/root/generate/internal \
+ common_name=my-website.com \
+ ttl=8760h
+# ==> Success! Configured CA with self-signed root
+# ==> Key Value
+# ==> --- -----
+# ==> certificate -----BEGIN CERTIFICATE-----...
+# ==> expiration 1536807433
+# ==> issuing_ca -----BEGIN CERTIFICATE-----...
+# ==> serial_number 7c:f1:fb:2c:6e:4d:99:0e:82:1b:08:0a:81:ed:61:3e:1d:fa:f5:29This example configures the CA with an internal self-signed root certificate and associated key pair that is +managed by Vault. Alternatively, you can configure the CA with an existing key pair.
+| + + | +
+CA configuration can be done programmatically using VaultPKISecretEngine.generateRoot(GenerateRootOptions)
+ |
+
With the CA configured we now require a role to be defined that determines what parameters are allowed when +generating certificates.
+Here we create a role example-dot-com that allows certificates with the common name
+allowed to be any subdomain of my-website.com.
vault write pki/roles/example-dot-com \
+ allowed_domains=my-website.com \
+ allow_subdomains=true \
+ max_ttl=72h
+# ==> Success! Data written to: pki/roles/example-dot-com| + + | +
+Role configuration can be done programmatically using
+VaultPKISecretEngine.updateRole(String role, RoleOptions options)
+ |
+
First, let’s create a simple Quarkus application with Vault and Jackson extensions:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.1:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=vault-pki-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy,vault,resteasy-jackson"
+cd vault-pki-quickstartNow, configure access to Vault from the application.properties:
# vault url
+quarkus.vault.url=http://localhost:8200
+
+# vault authentication
+quarkus.vault.authentication.userpass.username=bob
+quarkus.vault.authentication.userpass.password=sinclairWe can then add a new endpoint that will allow us to generate a certificate using the configured CA & role:
+@Path("/pki")
+@Produces(TEXT_PLAIN)
+@Consumes(TEXT_PLAIN)
+public class PKIResource {
+
+ @Inject
+ public VaultPKISecretEngine pkiSecretEngine;
+
+ @POST
+ @Path("/generate")
+ public String generate(String subdomain) {
+ GenerateCertificateOptions options = new GenerateCertificateOptions()
+ .setSubjectCommonName(subdomain + ".my-website.com");
+ GeneratedCertificate generated = pkiSecretEngine.generateCertificate("example-dot-com", options);
+ return generated.certificate.getData();
+ }
+}After compiling and starting the Quarkus application, let’s generate a new certificate with a generated key pair:
+curl -X POST --data 'a-subdomain' --header "Content-Type: text/plain" http://localhost:8080/pki/generate
+
+# ==> -----BEGIN CERTIFICATE-----
+# ==> ...
+# ==> -----END CERTIFICATE-----Alternatively we can generate a key pair and CSR locally and generate a certificate by having vault sign our CSR.
+Let’s add a new method that accepts a CSR:
+@POST
+@Path("/sign")
+public String sign(String csr) {
+ GenerateCertificateOptions options = new GenerateCertificateOptions();
+ SignedCertificate signed = pkiSecretEngine.signRequest("example-dot-com", csr, options);
+ return signed.certificate.getData();
+}Now we can generate a CSR (e.g. using OpenSSL) and pass it to our /sign endpoint to sign and generate a
+certificate from the CSR:
openssl req -newkey rsa:2048 -keyout example.key -out example.csr
+
+curl -X POST --data @example.csr --header "Content-Type: text/plain" http://localhost:8080/pki/sign
+
+# ==> -----BEGIN CERTIFICATE-----
+# ==> ...
+# ==> -----END CERTIFICATE-----Let’s add another new method to our PKIResource:
@POST
+@Path("/revoke")
+public void revoke(String serialNumber) {
+ pkiSecretEngine.revokeCertificate(serialNumber);
+}And revoke a previously generated certificate:
+curl -X POST --data '1d:2e:c6:06:45:18:60:0e:23:d6:c5:17:43:c0:fe:46:ed:d1:50:be' --header "Content-Type: text/plain" http://localhost:8080/pki/revoke
+# ==> No DataQuarkus’s Vault PKI support includes that ability to mount & unmount PKI engines dynamically using
+the VaultPKISecretEngineFactory & VaultSystemBackendEngine interfaces.
To enable, or mount, a new PKI engine at specific mount path you can use the
+VaultSystemBackendEngine.enable method:
// Obtain interfaces via injection or other standard CDI method.
+VaultSystemBackendEngine systemBackendEngine = ...;
+VaultPKISecretEngineFactory pkiSecretEngineFactory = ...;
+
+// Mount a PKI engine at a specified path.
+EnableEngineOptions options = new EnableEngineOptions()
+ .setMaxLeaseTimeToLive("8760h");
+systemBackendEngine.enable(VaultSecretEngine.PKI, "pki-dyn", "A dynamic PKI engine", options);
+
+// Obtain an engine manager for the newly mounted PKI engine.
+VaultPKISecretEngine dynPkiSecretEngine = pkiSecretEngineFactory.engine("pki-dyn");
+
+// Use dynamically created engine as you please.
+dynPkiSecretEngine.generateRoot(new GenerateRootOptions());To disable (aka unmount) a PKI engine at a specific path you simply use the VaultSystemBackendEngine.disable method:
systemBackendEngine.disable("pki-dyn");| + + | +
+If you want to test if a specific mount path is already in use you can use
+VaultSystemBackendEngine.isEngineMounted(String).
+ |
+
The PKI Secret Engine is a great tool for managing CAs and their provisioned certificates. +We have seen the most obvious functions of the interface but all of the methods and modes of Vault’s PKI secret +engine are supported, including:
+Provisioning roles used to generate certificates.
+Storing the root CA externally and issuing certificates from intermediate CAs.
+Reading current CRLs for each provisioned engine instance.
+Feel free to look at the VaultPKISecretEngine & VaultPKISecretEngineFactory interfaces.
Vault’s Transit Secret Engine offers an "encryption as a service" functionality. It allows to store encryption +keys into Vault, and provides services to encrypt/decrypt and sign/verify arbitrary pieces of data. This brings +several advantages, such as:
+limited key exposure: keys never leave the Vault. Instead the data is sent to Vault to get +encrypted/decrypted/signed/verified.
+reliable and consistent algorithms: algorithms are implemented by Vault. It supports a wide variety, and there is +only one implementation used for a given algorithm type, regardless of the client’s technology.
+it relieves developers from having to embed cryptographic libraries into their applications.
+In the context of Quarkus, the main (non administration) services are being covered:
+encrypt: encrypt some data and return the cipher text
+decrypt: decrypt the cipher text and return the clear data
+rewrap: reencrypt a cipher text using the most recent key version
+sign: sign a piece of data
+verify signature: verify that a signature is correct for a piece of data
+To complete this guide, you need:
+to complete the "Starting Vault" section of the Vault guide
+roughly 15 minutes
+an IDE
+JDK 11+ installed with JAVA_HOME configured appropriately
Apache Maven 3.8.1+
+Docker installed
+We assume there is a Vault running from the Vault guide, and the root token is known. +The first step consists in activating the Transit Secret Engine, and creating the different keys:
+docker exec -it dev-vault sh
+export VAULT_TOKEN=s.5VUS8pte13RqekCB2fmMT3u2
+
+vault secrets enable transit
+# ==> Success! Enabled the transit secrets engine at: transit/
+
+vault write -f transit/keys/my-encryption-key
+# ==> Success! Data written to: transit/keys/my-encryption-key
+
+vault write transit/keys/my-sign-key type=ecdsa-p256
+# ==> Success! Data written to: transit/keys/my-sign-keyNote that you did not have to provide the key value. You only provide its name, and Vault will generate it for you and +keep it secured.
+Once the keys have been created, we now need to create a policy that provides access for it:
+cat <<EOF | vault policy write vault-transit-quickstart-policy -
+path "transit/encrypt/my-encryption-key" {
+ capabilities = [ "update" ]
+}
+path "transit/decrypt/my-encryption-key" {
+ capabilities = [ "update" ]
+}
+path "transit/sign/my-sign-key" {
+ capabilities = [ "update"]
+}
+path "transit/verify/my-sign-key" {
+ capabilities = [ "update" ]
+}
+EOF
+# ==> Success! Uploaded policy: vault-transit-quickstart-policyAnd finally, let’s add the vault-transit-quickstart-policy to user bob that was created in the Vault guide:
vault write auth/userpass/users/bob password=sinclair policies=vault-quickstart-policy,vault-transit-quickstart-policyTo check that the configuration is correct, try logging in:
+vault login -method=userpass username=bob password=sinclairYou should see:
+Success! You are now authenticated. The token information displayed below
+is already stored in the token helper. You do NOT need to run "vault login"
+again. Future Vault requests will automatically use this token.
+
+Key Value
+--- -----
+token s.s93BVzJPzBiIGuYJHBTkG8Uw
+token_accessor OKNipTAgxWbxsrjixASNiwdY
+token_duration 768h
+token_renewable true
+token_policies ["default" "vault-quickstart-policy"]
+identity_policies []
+policies ["default" "vault-quickstart-policy"]
+token_meta_username bobNow set VAULT_TOKEN to the token above (instead of the root token), and try encrypting some data:
export VAULT_TOKEN=s.s93BVzJPzBiIGuYJHBTkG8Uw
+# note: "my secret data" in base64 is "bXkgc2VjcmV0IGRhdGEK"
+vault write transit/encrypt/my-encryption-key plaintext=bXkgc2VjcmV0IGRhdGEKYou should see:
+Key Value
+--- -----
+ciphertext vault:v1:vIQxsLANFbcfKofJL55zjoIXV6MqAzvjKUUQLGg5pWTz0W2Qab/B4nEJaQ==First, let’s create a simple Quarkus application with Vault and Jackson extensions:
+mvn io.quarkus.platform:quarkus-maven-plugin:3.8.1:create \
+ -DprojectGroupId=org.acme \
+ -DprojectArtifactId=vault-transit-quickstart \
+ -DclassName="org.acme.quickstart.GreetingResource" \
+ -Dpath="/hello" \
+ -Dextensions="resteasy,vault,resteasy-jackson"
+cd vault-transit-quickstartNow, configure access to Vault from the application.properties:
# vault url
+quarkus.vault.url=http://localhost:8200
+
+# vault authentication
+quarkus.vault.authentication.userpass.username=bob
+quarkus.vault.authentication.userpass.password=sinclairNote that you did not need to specify the existence of a particular encryption key in the configuration. You only +do so in special cases such as specifying the key type for upsert, or changing the signature algorithm, … Check the complete configuration for more +information.
+We can then add a new endpoint that will allow us to encrypt and decrypt data:
+@Path("/transit")
+@Produces(TEXT_PLAIN)
+@Consumes(TEXT_PLAIN)
+public class TransitResource {
+
+ @Inject
+ public VaultTransitSecretEngine transitSecretEngine;
+
+ @POST
+ @Path("/encrypt")
+ public String encrypt(String clearData) {
+ return transitSecretEngine.encrypt("my-encryption-key", clearData);
+ }
+
+ @POST
+ @Path("/decrypt")
+ public String decrypt(String cipherText) {
+ return transitSecretEngine.decrypt("my-encryption-key", cipherText).asString();
+ }
+}After compiling and starting the Quarkus application, let’s encrypt some data:
+curl -X POST --data 'some secret data' --header "Content-Type: text/plain" http://localhost:8080/transit/encrypt
+# ==> vault:v1:fN4P7WNjIegpb3lD/pSuhXvyONhGrI21gcKNcedk+5jpjguOw6JkqXYXlkY=And decrypt back this cipher text:
+curl -X POST --data 'vault:v1:fN4P7WNjIegpb3lD/pSuhXvyONhGrI21gcKNcedk+5jpjguOw6JkqXYXlkY=' --header "Content-Type: text/plain" http://localhost:8080/transit/decrypt
+# ==> some secret dataLet’s add 2 new methods to our TransitResource:
@POST
+@Path("/sign")
+public String sign(String input) {
+ return transitSecretEngine.sign("my-sign-key", input);
+}
+
+public static class VerifyRequest {
+ public String signature;
+ public String input;
+}
+
+@POST
+@Path("/verify")
+@Consumes(APPLICATION_JSON)
+public Response verify(VerifyRequest request) {
+ transitSecretEngine.verifySignature("my-sign-key", request.signature, request.input);
+ return Response.accepted().build();
+}And start signing some data:
+curl -X POST --data 'some secret data' --header "Content-Type: text/plain" http://localhost:8080/transit/sign
+# ==> vault:v1:MEUCIQDl+nE4y4E878bkugGG6FG1/RsttaQnoWfZHppeuk4TnQIgTGWTtMhVPCzN8VH/EEr2qp5h34lI1bnEP6L1F+QQoPI=And finally, let’s make sure the signature is matching our input data:
+curl -v -X POST --data '{"input":"some secret data","signature":"vault:v1:MEUCIQDl+nE4y4E878bkugGG6FG1/RsttaQnoWfZHppeuk4TnQIgTGWTtMhVPCzN8VH/EEr2qp5h34lI1bnEP6L1F+QQoPI="}' --header "Content-Type: application/json" http://localhost:8080/transit/verify
+# ==> ... < HTTP/1.1 202 AcceptedThe Transit Secret Engine is a powerful tool in the enterprise. +We have seen the most obvious functions of the interface, but the rest of the methods or flavors +should not be overlooked:
+For instance batch oriented methods are strongly recommended for mass operations (encrypt, decrypt, …)
+Transit contexts allow key derivation where one key is used to derive other keys for specific named contexts +(e.g. person names, person addresses, …)
+Rewrapping allows to reencrypt data with the most recent key version when the Vault administrator decides to +rotate keys
+Feel free to look at the VaultTransitSecretEngine interface plus the dedicated Transit Secret Engine configuration
+properties in the Vault guide for all the details.
Web Bundler - Advanced GuidesThe Web Root is src/main/resources/web, this is where the Web Bundler will look for stuff to bundle and serve.
There are 2 ways to add static files (fonts, images, music, video, …) to your app:
+- Files in src/main/resources/web/static/** will be served statically under http://localhost:8080/static/ (you can choose another directory name Config Reference). For convenience, those static files are excluded (marked as external) from the bundling by default. This allows to reference them from scripts or styles without errors (e.g. import '/static/foo.png';).
+- Other files imported from scripts or styles will be bundled and processed by the configured loaders (see How is it bundled (Loaders)) allowing different options (like embedding them as data-url).
The Web-Bundler is natively integrated with Qute to render html templates at build-time (this won’t affect runtime). This way you may create SPA out of the box. For this, just provide an index.html file (or any other .html file) in the src/main/resources/web directory.
Combined with the {#bundle /} tag, this file will be rendered with the scripts and styles tags to include in your html template. This file will be served as the default index file (e.g. http://localhost:8080/).
+| + + | +
+You can use the Qute config: namespace, it will be evaluated a build-time (runtime config will be ignored).
+ |
+
| + + | +
+This rendering option is happening at build time, so you won’t be able to access any Qute runtime data in this file. If you want to render data (for example in a server-side rendering app with htmx), you should add the Qute Web extension (or Renarde extension for MVC with Qute) and use src/main/resources/templates/ directory instead. The {#bundle /} tag will also work in this case.
+ |
+
By default, directory src/main/resources/web/app is destined to contain the scripts, styles and possibly assets for your app. It will be bundled and served into /static/bundle/main-[hash].[ext]. (see Entry-Points for more options).
Once added in the pom.xml, the web dependencies can be imported and used with the ESM import syntax, they will automatically be bundled.
+| + + | ++Web Dependencies (script and styles) need to be imported in order to be bundled, dead code will be eliminated during the build. + | +
import $ from 'jquery';
+import 'bootstrap/dist/css/bootstrap.css';
+
+$('.hello').innerText('Hello');Styles can be also be imported from a scss file:
+@import "bootstrap/dist/scss/bootstrap.scss";Only what’s imported will be part of the resulting bundle, to make it easy, the Web Bundler will automatically generate an index importing all the files found in an entry-point directory.
+Of course, you can also provide this index manually (named index.js,ts,jsx,tsx) and choose what to import. Example:
import './my-script.js'
+import './my-style.scss'
+import './example.png'You may configure different entry-points (to generate different bundles):
+quarkus.web-bundler.bundle.page-1=true (1)
+quarkus.web-bundler.bundle.page-2=true (2)| 1 | +Bundle src/main/resources/web/page-1/… into /static/bundle/page-1-[hash].[ext] |
+
| 2 | +Bundle src/main/resources/web/page-2/… into /static/bundle/page-2-[hash].[ext] |
+
or customize the directory name and bundled file name (and possibly merge multiple directories into one bundle):
+quarkus.web-bundler.bundle.foo=true (1)
+quarkus.web-bundler.bundle.bar=true (2)
+quarkus.web-bundler.bundle.bar.key=my-key
+quarkus.web-bundler.bundle.bar.dir=my-dir
+quarkus.web-bundler.bundle.baz=true (1)
+quarkus.web-bundler.bundle.baz.key=foo| 1 | +Bundle src/main/resources/web/foo/… and src/main/resources/web/baz/… together into /static/bundle/foo-[hash].[ext] |
+
| 2 | +Bundle src/main/resources/web/my-dir/… into /static/bundle/my-key-[hash].[ext] |
+
| + + | +
+By default, as soon as more than one entry-point key is configured, shared code and web dependencies are split off into a separate file. That way if the user first browses to one page and then to another page, they don’t have to download all the JavaScript for the second page from scratch if the shared part has already been downloaded and cached by their browser. The path of the shared static script is /static/bundle/chunk-[hash].js. This setup is perfect if you create an app with different pages using different scripts, libraries and styles.
+ |
+
Bases on the files extensions, the Web Bundler will use pre-configured loaders to bundle them. For scripts and styles, the default configuration should be enough.
+For other assets (svg, gif, png, jpg, ttf, …) imported from your scripts and styles using their relative path, you may choose the loader based on the file extension allowing different options (e.g. serving, embedding the file as data-url, binary, base64, …). By default, they will automatically be copied and served using the file loader.
+For example, url('./example.png') in a style or import example from './example.png'; in a script will be processed, the file will be copied with a static name and the path will be replaced by the new file static path (e.g. /static/bundle/assets/example-QH383.png). The example variable will contain the public path to this file to be used in a component img src for example.
| + + | +
+For convenience, when using a file located in the static directory (e.g. url('/static/example.png'), the path will not be processed because all files under /static/** are marked as external (to be ignored from the bundling). Since /static/example.png will be served by Quarkus (See Static files), it is ok.
+ |
+
You can use scss or sass files out of the box. Local import are supported. Importing partials is also supported begin with _ (as in _code.scss imported with @import 'code';).
| + + | +
+This features requires quarkus-qute or quarkus-qute-web in the project (and this is not made to be used with the build-time template rendering).
+ |
+
This is not always needed but if you need to add specific script and/or style to your Qute tags (Server Side Qute Components). This will help you do it elegantly.
+To enable server-side components, add this in the application.properties:
quarkus.web-bundler.bundle.components=true
+quarkus.web-bundler.bundle.components.key=main (1)
+quarkus.web-bundler.bundle.components.qute-tags=true (2)| 1 | +use main to have a single merged bundle with the app (or remove this line to use qute-components as default) |
+
| 2 | +activate qute-tags support (default is false) |
+
Here is a nice convention to define your components: src/main/resources/web/components/[name]/[name].{html,css,scss,js,ts,…};. The scripts, styles and assets will be bundled, the html template will be usable as a Qute tag.
Example:
+- src/main/resources/web/components/hello/hello.html
+- src/main/resources/web/components/hello/hello.js
+- src/main/resources/web/components/hello/hello.scss
This way you can use {#hello} in your templates and the scripts & styles will be bundled.
| + + | ++You may create different qute components groups to be used in different pages. + | +
The Web Bundler is integrated with NPM dependencies through MVNPM (default) (default) or WebJars. +Once added in the pom.xml the dependencies are directly available through import from the scripts and styles.
+Using the Web Bundler, Web Dependencies are bundled, there is not point for the jars to be packaged in the resulting app.
+Web Dependencies with provided scope (or compileOnly with Gradle) will not be packaged in the resulting app.
INFO: By default, the Web Bundler will fail at build time if it detects non compile only Web Dependencies. You can configure a flag to allow them but keep in mind that they will be served by Quarkus.
+| + + | ++If you don’t import a Web Dependency from an entry-point (Indexing), it won’t be bundled (dead code elimination). + | +
mvnpm (Maven NPM) is a maven repository facade on top of the NPM Registry.
+Lookup for packages on https://mvnpm.org or https://www.npmjs.com/ then add them as web dependencies to your pom.xml:
+...
+<dependencies>
+ ...
+ <dependency>
+ <groupId>org.mvnpm</groupId> (1)
+ <artifactId>jquery</artifactId> (2)
+ <version>3.7.0</version> (3)
+ <scope>provided</scope> (4)
+ </dependency>
+</dependencies>
+...| 1 | +use org.mvnpm or org.mvnpm.at.something for @something/dep |
+
| 2 | +All dependencies published on NPM are available | +
| 3 | +Any published NPM version for your dependency | +
| 4 | +Use provided scope to avoid having the dependency packaged in the target application |
+
If a package or a version in not yet available in Maven Central:
+You may use the mvnpm.org website to synchronize new versions with Maven Central (Click on the Maven Central icon)
+If configured with the mvnpm repository, when requesting a dependency, it will inspect the registry to see if it exists and if it does, convert it to a Maven dependency and publish it to Maven Central so that future developers (and CI) won’t need the repository.
+Configure the mvnpm-repo profile in your ~/.m2/settings.xml:
+.settings.xml
<settings> + <profiles> + <profile> + <id>mvnpm-repo</id> + <repositories> + <repository> + <id>central</id> + <name>central</name> + <url>https://repo.maven.apache.org/maven2</url> + </repository> + <repository> + <snapshots> + <enabled>false</enabled> + </snapshots> + <id>mvnpm.org</id> + <name>mvnpm</name> + <url>https://repo.mvnpm.org/maven2</url> + </repository> + </repositories> + </profile> + </profiles> +</settings>+
| + + | +
+I only use -Pmvnpm-repo when locking my project or updating mvnpm versions.
+ |
+
| + + | ++In case of web dependencies versions conflicts, you can set the version to use for this dependency in the project dependencyManagement (even when using the locker). + | +
To deal with Web Dependencies, the Web Bundler manages a node_modules directory. The default location for it is the build direcotry (i.e. target/node_modules on Maven). For a good IDE support (detection of imports and types), you may use the project directory instead quarkus.web-bundler.dependencies.node-modules=node_modules and add the node_modules/ to the .gitignore, the IDE will look recursivelly in parent directories for imports and the Web Bundler too.
As the NPM ecosystem is over-using version ranges for dependencies, just a few npm dependencies can lead to a big amount of poms to download in order to get the right versions for your project. This leads to long lasting minutes of downloading poms when cloning or during CI. To solve this problem and also to make your build reproducible it is highly recommended to lock your web dependencies versions. This way it will be long only the first time and then it will be fast and reproducible.
+As Maven doesn’t provide a native version locking system, the mvnpm team has implemented a way to easily generate and use a locking pom.xml (BOM). The locker Maven Plugin will create a version locker BOM for your org.mvnpm and org.webjars dependencies. It is essential as NPM dependencies are over using ranges. After the locking, the quantity of files to download is considerably reduced (better for reproducibility, contributors and CI).
+It is easy to set up and update, here is the documentation.
+Gradle provides a native version locking system, to install it, add this:
+dependencyLocking {
+ lockAllConfigurations()
+}Then run gradle dependencies --write-locks to generate the lockfile.
| + + | ++Adding new dependencies or recent versions has to be done manually from their website. + | +
WebJars are client-side web libraries (e.g. jQuery & Bootstrap) packaged into JAR (Java Archive) files. You can browse the repository from the website.
+quarkus.web-bundler.dependencies.type=webjars<dependency>
+ <groupId>org.webjars.npm</groupId>
+ <artifactId>jquery</artifactId>
+ <version>3.7.0</version>
+ <scope>provided</scope>
+</dependency>After the bundling is done, the bundle files will be served by Quarkus under {quarkus.http.root-path}/static/bundle/… by default (Config Reference).
This may also be configured with an external URL (e.g. 'https://my.cdn.org/'), in which case, Bundle files will NOT be served by Quarkus and all resolved paths in the bundle and mapping will automatically point to this url (a CDN for example).
+In production, it is a good practise to have a hash inserted in the scripts and styles file names (E.g.: main-XKHKUJNQ.js) to differentiate builds (make them static). This way they can be cached without a risk of missing the most recent builds.
In the Web Bundler, we also do it in dev mode, this way the app is as close as possible to production. You won’t have surprise when deploying a new version of your application.
+To make it easy there are several ways to resolve the bundle files public paths from the templates and the code.
+From any Qute template you can use the {#bundle /} tag to help insert the bundled scripts and styles in your html page. examples:
{#bundle /}
+Output:
+<script type="text/javascript" src="/static/bundle/main-[hash].js"></script>
+<link rel="stylesheet" media="screen" href="/static/bundle/main-[hash].css">
+
+{#bundle key="components"/}
+Output:
+<script type="text/javascript" src="/static/bundle/components-[hash].js"></script>
+<link rel="stylesheet" media="screen" href="/static/bundle/components-[hash].css">
+
+{#bundle tag="script"/}
+Output:
+<script type="text/javascript" src="/static/bundle/main-[hash].js"></script>
+
+{#bundle tag="style"/}
+Output:
+<link rel="stylesheet" media="screen" href="/static/bundle/main-[hash].css">
+
+{#bundle key="components" tag="script"/}
+Output:
+<script type="text/javascript" src="/static/bundle/components-[hash].js"></script>Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The directory in the resources which serves as root for the web assets +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Resources located in {quarkus.web-bundler.web-root}/{quarkus.web-bundler.static} will be served by Quarkus. This directory path is also used as prefix for serving (e.g. {quarkus.web-bundler.web-root}/static/foo.png will be served on {quarkus.http.root-path}/static/foo.png) +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+When configured with an internal path (e.g. 'foo/bar'), Bundle files will be served on this path by Quarkus (prefixed by {quarkus.http.root-path}). When configured with an external URL (e.g. 'https://my.cdn.org/'), Bundle files will NOT be served by Quarkus and all resolved paths in the bundle and mapping will automatically point to this url (a CDN for example). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the js loader: https://esbuild.github.io/content-types/#javascript +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the jsx loader: https://esbuild.github.io/content-types/#jsx +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the tsx loader: https://esbuild.github.io/content-types/#jsx +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the ts loader: https://esbuild.github.io/content-types/#typescript +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the local-css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the global-css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the file loader: https://esbuild.github.io/content-types/#file This loader will copy the file to the output directory and embed the file name into the bundle as a string. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the copy loader: https://esbuild.github.io/content-types/#copy +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the base64 loader: https://esbuild.github.io/content-types/#base64 +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the binary loader: https://esbuild.github.io/content-types/#binary +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the dataurl loader: https://esbuild.github.io/content-types/#data-url +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the empty loader: https://esbuild.github.io/content-types/#empty-file +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the text loader: https://esbuild.github.io/content-types/#text +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the json loader: https://esbuild.github.io/content-types/#json +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+This defines the list of external paths for esbuild (https://esbuild.github.io/api/#external). Instead of being bundled, the import will be preserved. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable or disable bundle splitting (https://esbuild.github.io/api/#splitting) Code shared between multiple entry points is split off into a separate shared file (chunk) that both entry points import +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to the node_modules directory (relative to the project root). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Disable this option to allow using runtime web dependencies. When a runtime scope web dependency is used, the dependency will be present in the target app and served at runtime. When a compile only scope web dependency is used, the dependency will only be used at build time and will not be present in the target app. WARNING: Maven compile scope is considered as a runtime scope, use 'provided' for compile only. On Gradle, 'compileOnly' is compile only. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When enabled, Quarkus will create redirections from {bundlePath}/{entryPointKey}.{js,css} to the corresponding file containing the unique hash. This is useful for fixed external access to the bundle files (fullstack microservices). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The default charset +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Enable or disable this entry point. You can use this to use the map key as key and dir for this entry point. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory for this entry point under the web root. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The key for this entry point (use the same key as another to bundle them together). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicate if this directory contains qute tags (as .html files) This is only available if the Quarkus Qute extension is in the project. +
+
+Environment variable: |
+boolean |
+
|
+
Web Bundler - ExamplesQuarkus Blast: Web Bundler, Renarde, htmx, hyperscript, Bootstrap
+React: Web Bundler, React, React Bootstrap
+Renotes: Web Bundler, Renarde, htmx, Bootstrap
+jQuery: Web Bundler, jQuery, Bootstrap
+Gradle jQuery: Gradle, Web Bundler, jQuery, Bootstrap
+TODO Demo App: Web Bundler, Lit, Vaadin Web Components
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+The directory in the resources which serves as root for the web assets +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Resources located in {quarkus.web-bundler.web-root}/{quarkus.web-bundler.static} will be served by Quarkus. This directory path is also used as prefix for serving (e.g. {quarkus.web-bundler.web-root}/static/foo.png will be served on {quarkus.http.root-path}/static/foo.png) +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+When configured with an internal path (e.g. 'foo/bar'), Bundle files will be served on this path by Quarkus (prefixed by {quarkus.http.root-path}). When configured with an external URL (e.g. 'https://my.cdn.org/'), Bundle files will NOT be served by Quarkus and all resolved paths in the bundle and mapping will automatically point to this url (a CDN for example). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the js loader: https://esbuild.github.io/content-types/#javascript +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the jsx loader: https://esbuild.github.io/content-types/#jsx +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the tsx loader: https://esbuild.github.io/content-types/#jsx +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the ts loader: https://esbuild.github.io/content-types/#typescript +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the local-css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the global-css loader: https://esbuild.github.io/content-types/#css +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the file loader: https://esbuild.github.io/content-types/#file This loader will copy the file to the output directory and embed the file name into the bundle as a string. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the copy loader: https://esbuild.github.io/content-types/#copy +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the base64 loader: https://esbuild.github.io/content-types/#base64 +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the binary loader: https://esbuild.github.io/content-types/#binary +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the dataurl loader: https://esbuild.github.io/content-types/#data-url +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the empty loader: https://esbuild.github.io/content-types/#empty-file +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Configure the file extensions using the text loader: https://esbuild.github.io/content-types/#text +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Configure the file extensions using the json loader: https://esbuild.github.io/content-types/#json +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+This defines the list of external paths for esbuild (https://esbuild.github.io/api/#external). Instead of being bundled, the import will be preserved. +
+
+Environment variable: |
+list of string |
+
|
+
+
+
+
+
+
+Enable or disable bundle splitting (https://esbuild.github.io/api/#splitting) Code shared between multiple entry points is split off into a separate shared file (chunk) that both entry points import +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to the node_modules directory (relative to the project root). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Disable this option to allow using runtime web dependencies. When a runtime scope web dependency is used, the dependency will be present in the target app and served at runtime. When a compile only scope web dependency is used, the dependency will only be used at build time and will not be present in the target app. WARNING: Maven compile scope is considered as a runtime scope, use 'provided' for compile only. On Gradle, 'compileOnly' is compile only. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+When enabled, Quarkus will create redirections from {bundlePath}/{entryPointKey}.{js,css} to the corresponding file containing the unique hash. This is useful for fixed external access to the bundle files (fullstack microservices). +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The default charset +
+
+Environment variable: |
++ |
|
+
+
+
+
+
+
+Enable or disable this entry point. You can use this to use the map key as key and dir for this entry point. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The directory for this entry point under the web root. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The key for this entry point (use the same key as another to bundle them together). +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Indicate if this directory contains qute tags (as .html files) This is only available if the Quarkus Qute extension is in the project. +
+
+Environment variable: |
+boolean |
+
|
+
Web Bundler - Getting StartedCreate full-stack web apps and components with this Quarkus extension. It offers zero-configuration bundling and minification (with source-map) for your web app scripts (JS, JSX, TS, TSX), dependencies (jQuery, htmx, Bootstrap, Lit etc.), and styles (CSS, SCSS, SASS).
+No need to install NodeJs, it relies on a Java wrapped version of esbuild. For libraries, all the NPM catalog is accessible through Maven or Gradle dependencies.
+| + + | ++The Web Bundler has been pre-configured to reduce the complexity of web bundling. You don’t need to know all the concepts of web bundling (entry-points, loaders, …) to use this extension, it has been pre-configured with sensible defaults that you may change if needed. + | +
If you want to use this extension, you need to add the io.quarkiverse.web-bundler:quarkus-web-bundler extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.web-bundler</groupId>
+ <artifactId>quarkus-web-bundler</artifactId>
+ <version>1.3.1</version>
+</dependency>Add your web resources in src/main/resources/web:
app/**: App scripts (js, ts, jsx, tsx, …), styles (css, scss, sass) and assets (svg, jpg, gif, png, …), to be bundled and served under http://localhost:8080/static/bundle/
static/**: Any static file to be served without change under http://localhost:8080/static/
Add Web Dependencies to the pom and import them (scripts and styles):
+import $ from 'jquery';
+import 'bootstrap/dist/css/bootstrap.css';
+
+$('.hello').innerText('Hello');| + + | ++If you don’t import a Web Dependency, it won’t be bundled (dead code elimination). + | +
Install the bundle in your index.html template:
+<html>
+<head>
+ ...
+ {#bundle /}
+</head>
+</html>Will compile into something looking like this:
+<html>
+<head>
+ ...
+ <script type="text/javascript" src="/static/main-XKHKUJNQ.js"></script>
+ <link rel="stylesheet" media="screen" href="/static/main-TLNDARM3.css">
+</head>
+</html>You are all set, enjoy!
+| + + | +
+By default {#bundle /} inserts both script and style tags for main, this is configurable.
+ |
+
Web Bundler - Main ConceptsIt’s really simple, the web bundler:
+
Takes/watches your web resources and Web Dependencies.
+Bundles it with the supersonic esbuild compiler (scss are also compiled if needed) and serves them.
+Make it easy to create pages (.html) with the bundle scripts and styles using Qute or any other template engine.
+Once added in the pom.xml the dependencies are directly available through import from the scripts and styles:
+import $ from 'jquery';
+
+$('.hello').innerText('Hello');Imported dependencies scripts and styles will be bundled.
+| + + | ++Only imported dependencies (scripts and styles) will be bundled, dead code will be eliminated during the build. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name of the WireMock Dev Service. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+Environment variable: |
+int |
+8089 |
+
+
+
+
+
+
+Restart WireMock whenever Quarkus is reloaded. Otherwise, whenever files are changed in the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to root dir with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If global response templating should be enabled for WireMock, see https://wiremock.org/2.x/docs/response-templating/ +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus WireMock extension for tests and local development.
+If you want to use this extension, you need to add the io.quarkiverse.wiremock:quarkus-wiremock extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.wiremock</groupId>
+ <artifactId>quarkus-wiremock</artifactId>
+ <version>0.1.2</version>
+ <scope>test</scope>
+</dependency>| + + | +
+The extension is designed to run in dev and test mode only! Please don’t specify any attributes applicable for the prod profile, otherwise unknown property warnings will show up when executing the production build.
+ |
+
Example (default) configuration for testing and local development:
+%dev,test.quarkus.wiremock.devservices.enabled=true
+%dev,test.quarkus.wiremock.devservices.reload=false
+%dev,test.quarkus.wiremock.devservices.files-mapping=src/test/resources
+%dev,test.quarkus.wiremock.devservices.port=8089
+%dev,test.quarkus.wiremock.devservices.service-name=wiremock-server
+%dev,test.quarkus.wiremock.devservices.global-response-templating=falseIn addition, you might want to configure WireMock programmatically. To do so, please add the following dependency to the target project:
<dependency>
+ <groupId>io.quarkiverse.wiremock</groupId>
+ <artifactId>quarkus-wiremock-test</artifactId>
+ <version>0.1.2</version>
+ <scope>test</scope>
+</dependency>After that, you are able to inject a WireMock reference along with your test execution lifecycle has shown below:
@QuarkusTest
+@QuarkusTestResource(WireMockServerTestResource.class)
+class WireMockDevServiceResourceTest {
+
+ private static final String MOCK_MSG = "Hello from WireMock!";
+
+ @InjectWireMock
+ WireMock wiremock;
+
+ @Test
+ void testHelloEndpoint() {
+ Assertions.assertNotNull(wiremock);
+ wiremock.register(get(urlEqualTo("/mock-me"))
+ .willReturn(aResponse().withStatus(200).withBody(MOCK_MSG)));
+ ...
+ }
+
+}You can also reuse a @QuarkusTest as a @QuarkusIntegrationTest:
@QuarkusIntegrationTest
+public class WireMockDevServiceResourceIT extends WireMockDevServiceResourceTest {
+ // re-use Quarkus tests as integration tests
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name of the WireMock Dev Service. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+Environment variable: |
+int |
+8089 |
+
+
+
+
+
+
+Restart WireMock whenever Quarkus is reloaded. Otherwise, whenever files are changed in the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to root dir with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+If global response templating should be enabled for WireMock, see https://wiremock.org/2.x/docs/response-templating/ +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the Dev Service will listen to. If not defined, the port will be chosen randomly. +
+
+WARNING: Only ports between 1025 and 65535 are permitted. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Restart WireMock whenever Quarkus is reloaded. Otherwise, whenever files are changed in the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to root dir with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Response templating is enabled by default in WireMock 3, +with this setting response templating can be enabled globally. +
+
+Please refer to Response Templating for more details. +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus WireMock extension for tests and local development.
+This extension starts WireMock as a Dev Service, thus it is designed to run in dev and test mode only!
If you want to use this extension, you need to add the io.quarkiverse.wiremock:quarkus-wiremock dependency to your build file first.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.wiremock</groupId>
+ <artifactId>quarkus-wiremock</artifactId>
+ <version>1.3.0</version>
+ <scope>provided</scope>
+</dependency>The extension comes with most reasonable defaults.
+quarkus.wiremock.devservices.enabled=true
+quarkus.wiremock.devservices.reload=true
+quarkus.wiremock.devservices.files-mapping=src/test/resources
+quarkus.wiremock.devservices.global-response-templating=false| + + | +
+Due to its build time nature is totally fine that Quarkus prints unrecognized configuration key warnings when executing integration tests.
+ |
+
A core feature of WireMock is the ability to return HTTP responses for request matching criteria. You can configure stubs using JSON configuration files placed in the mappings and __files folders.
+The root location of these folders can be defined via quarkus.wiremock.devservices.files-mapping. By default the root location points to src/test/resources.
In addition, you might want to configure WireMock’s stubbing and request matching behavior programmatically. To do so, please add the following dependency to your target project:
<dependency>
+ <groupId>io.quarkiverse.wiremock</groupId>
+ <artifactId>quarkus-wiremock-test</artifactId>
+ <version>1.3.0</version>
+ <scope>test</scope>
+</dependency>After that, a WireMock client reference can be injected along with your test execution lifecycle as shown below:
@QuarkusTest
+@ConnectWireMock
+class WireMockDevServiceResourceTest {
+
+ private static final String MOCK_MSG = "Hello from WireMock!";
+
+ WireMock wiremock; // will be injected automatically when the test class is annotated with @ConnectWireMock
+
+ @Test
+ void testHelloEndpoint() {
+ Assertions.assertNotNull(wiremock);
+ wiremock.register(get(urlEqualTo("/mock-me"))
+ .willReturn(aResponse().withStatus(200).withBody(MOCK_MSG)));
+ ...
+ }
+
+}| + + | ++For more details please refer to the WireMock Stubbing & Verifying docs. + | +
This Quarkus extension exposes configuration keys via Java constants (WireMockConfigKey). By doing so, the config values can be accessed more easily:
@QuarkusTest
+class WireMockDevServiceResourceTest {
+
+ // WireMockConfigKey is provided by the core module and does not require the `test` module dependency
+ @ConfigProperty(name = WireMockConfigKey.PORT)
+ Integer port; // the port WireMock server is listening on
+
+}You can even access the WireMock Dev Service configuration values from within a Quarkus Integration Test:
@QuarkusIntegrationTest
+@ConnectWireMock
+class WireMockDevServiceResourceTest {
+
+ DevServicesContext devServicesContext;
+
+ @Test
+ void testWireMockDevServiceConfigPropagation() {
+ // Dev Service config gets propagated and is accessible via the ConfigProvider API
+ int port = ConfigProvider.getConfig().getValue(WireMockConfigKey.PORT, Integer.class);
+
+ // or via the Dev Service Context
+ int portDevSerCtx = Integer.parseInt(devServicesContext.devServicesProperties().get(WireMockConfigKey.PORT));
+ ...
+ }
+
+}| + + | +
+Please be aware that Dependency Injection (DI) works for specific types (DevServicesContext and WireMock) only.
+The latter in particular is only available if the class has been annotated with @ConnectWireMock.
+ |
+
You can also reuse a @QuarkusTest as a @QuarkusIntegrationTest where applicable:
@QuarkusIntegrationTest
+public class WireMockDevServiceResourceIT extends WireMockDevServiceResourceTest {
+ // re-use Quarkus tests as integration tests
+}Further more this extension supports the configuration capabilities of Quarkus. This means you can reference WireMock configuration keys
+within your custom properties via variable interpolation.
custom.config.wiremock.url=http://localhost:${quarkus.wiremock.devservices.port}/mock-me| + + | ++Please refer to Property Expressions for further details. + | +
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the Dev Service will listen to. If not defined, the port will be chosen randomly. +
+
+WARNING: Only ports between 1025 and 65535 are permitted. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Restart WireMock whenever Quarkus is reloaded. Otherwise, whenever files are changed in the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Path to root dir with
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Response templating is enabled by default in WireMock 3, +with this setting response templating can be enabled globally. +
+
+Please refer to Response Templating for more details. +
+
+Environment variable: |
+boolean |
+
|
+
Zanzibar annotations are compatible with both of Quarkus' JAX-RS implementations, RESTEasy Reactive and RESTEasy (Classic).
+The annotations are modeled after JAX-RS Role-Based Access Control annotations and will be familiar to those who have +used them. The main difference being that Zanzibar FGA annotations can dynamically determine their values from the +current HTTP request.
+Zanzibar style authorization requires 4 distinct pieces of information: the object type & object id, +relation type and the user id. The extension provides resource method annotations to configure how the +object and relation properties are determined from the current HTTP request and uses the standard authentication +features of Quarkus to determine the user.
+The resource method annotations can be placed on a single method or on a class to affect all methods of the class.
+The Zanzibar extension provides a number of annotations to determine the object type & id from the current request.
+| Annotation | +Description | +Object Id Source | +Object Type Source | +
|---|---|---|---|
|
+Dynamically inspects the HTTP request path parameters. |
+Request path parameter. |
+Annotation constant. |
+
|
+Dynamically inspects the HTTP request query parameters. |
+Request query parameter. |
+Annotation constant. |
+
|
+Dynamically inspects the HTTP request header values. |
+Request header value. |
+Annotation constant. |
+
|
+Dynamically inspects the generic HTTP request properties. |
+Request property. |
+Annotation constant. |
+
|
+Statically provides both properties in the Zanzibar annotation. |
+Annotation constant. |
+Annotation constant. |
+
While these annotations provide a large amount of options sometimes custom support will be needed; currently you can use FGARequestObject to achieve this. Any filter or other request interception method that runs before Zanzibar’s authorization filer can store a property against the current request and then extract the value using the FGARequestObject annotation.
The relation is specified using a single annotation providing the relation as a constant.
+| Annotation | +Description | +Relation Type Source | +
|---|---|---|
|
+Statically provides the relation type properties in the Zanzibar annotation. |
+Annotation constant. |
+
The user type is specified using a single annotation providing the type name as a constant.
+Certain FGA implementations require the user to be provided as an object. For example instead of
+providing a user with id some-user-id as simply some-user-id, it requires the user to be in
+an object format such as user:some-user-id (for the user type is user).
| Annotation | +Description | +Relation Type Source | +
|---|---|---|
|
+Statically provides the user type name in the Zanzibar annotation. |
+Annotation constant. |
+
| + + | +
+ User Object Type Requirements
+Currently only OpenFGA’s 1.1 schema requires users in object format. The @FGAUserType will be required for
+all endpoints when using OpenFGA.
+ |
+
The Authzed Connector provides access to Authzed server instances or their managed +authorization platform. +It relies upon the Quarkus Authzed Client.
+Currently there is no connector specific setup or configuration beyond installing the connector dependency.
+Visit the Quarkus Authzed Client project for details on configuring the client to connect to your server or the Authzed platform.
+To connect to Authzed servers you need to add the Zanzibar Authzed connector.
+For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.zanzibar</groupId>
+ <artifactId>quarkus-zanzibar-authzed</artifactId>
+ <version>1.2.0</version>
+</dependency>The connector depends on the required quarkus-zanzibar extension; its inclusion is optional.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the filter is enabled. +
+
+When enabled all endpoints must have a resolvable
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Should access to resource methods without FGA annotations be denied. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name used for authorization when the request is unauthenticated. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Maximum time an authorization check is allowed to take. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
The Quarkus Zanzibar extension provides Zanzibar style Fine Grain +Authorization (FGA) capabilities for Quarkus' HTTP subsystems. An authorization filter and dedicated +annotations are provided to provide easy integration of Zanzibar style FGA into applications.
+The extension only provides the framework and relies on dedicated connectors to communicate with specific +Zanzibar style servers.
+Supported APIs and platforms:
+Adding the quarkus-zanzibar extension to your project only provides access to the authorization and the annotations needed to configure authorization on your resource classes and methods.
To communicate with your selected server API you will need to add the Zanzibar connector for your selected server.
+Given a model object Thing, and the following simple authorization model that give every owner both
+read and write permissions.
## OpenFGA Syntax
+model
+ schema 1.1
+type user
+type thing
+ relations
+ define owner: [user]
+ ## permissions
+ define read as owner
+ define write as ownerWith a suitable authorization model initialized in your selected server, Zanzibar uses JAX-RS annotations to +define the exact authorization details for resource methods.
+Using the authorization model from above. The following resource methods allow any user to create new
+things but only users with read access to fetch them; in this example this will be the owner of the Thing.
import java.security.Principal;
+import java.util.List;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.QueryParam;
+
+import io.quarkiverse.zanzibar.Relationship;
+import io.quarkiverse.zanzibar.RelationshipManager;
+import io.quarkiverse.zanzibar.annotations.FGAPathObject;
+import io.quarkiverse.zanzibar.annotations.FGARelation;
+import io.quarkiverse.zanzibar.annotations.FGAUserType;
+import io.smallrye.mutiny.Uni;
+
+@Path("/things")
+class ThingResource {
+
+ @Inject
+ ThingRepository thingRepository;
+ @Inject (1)
+ RelationshipManager relationshipManager;
+ @Inject (2)
+ Principal principal;
+
+ @POST
+ @FGARelation(FGARelation.ANY) (3)
+ public Uni<Thing> createThing(@QueryParam("name") String name) {
+ return thingRepository.createThing(name)
+ .flatMap((thing) -> {
+ (4)
+ var relationship = new Relationship("thing", thing.getId(), "owner", principal.getName());
+ (5)
+ return relationshipManager.add(List.of(relationship))
+ .map((unused) -> thing);
+ });
+ }
+
+ @GET
+ @Path("{id}")
+ @FGAPathObject(param = "id", type = "thing") (6)
+ @FGARelation("owner") (7)
+ @FGAUserType("user") (8)
+ public Uni<Thing> getThing(String id) {
+ return thingRepository.fetchThing(id);
+ }
+}| 1 | +Inject RelationshipManager to allow adding & removing relationships. |
+
| 2 | +Inject Principal for access to the current user id. |
+
| 3 | +FGARelation.ANY allows access for any user, disregarding the authorization model. |
+
| 4 | +Create a Relationship that defines the current user as the owner of the newly created Thing. |
+
| 5 | +Add the new thing’s owner relationship to the authorization model. |
+
| 6 | +Dynamically determine the id of the Thing to authorize from the id path parameter of the current HTTP request. Additionally, set the object type to thing as defined by the authorization model. |
+
| 7 | +Check if the current user has the owner relation for the thing dynamically determined by the @FGAPathObject. |
+
| 8 | +For implementations that require it, provide the user object type. | +
Zanzibar provides a number of annotations to determine the current object id and object type. The annotations +are detailed here.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether the filter is enabled. +
+
+When enabled all endpoints must have a resolvable
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Should access to resource methods without FGA annotations be denied. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Name used for authorization when the request is unauthenticated. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Maximum time an authorization check is allowed to take. +
+
+Environment variable: |
+Duration + |
+
|
+
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
The OpenFGA Connector provides access to OpenFGA server instances or +Auth0’s managed authorization platform. +It relies upon the Quarkus OpenFGA Client.
+Currently there is no connector specific setup or configuration beyond installing the connector dependency.
+Visit the Quarkus OpenFGA Client project for details on configuring the client to connect to your server or the Authzed platform.
+To connect to OpenFGA servers you need to add the Zanzibar OpenFGA connector.
+For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.zanzibar</groupId>
+ <artifactId>quarkus-zanzibar-openfga</artifactId>
+ <version>1.2.0</version>
+</dependency>The connector depends on the required quarkus-zanzibar extension; its inclusion is optional.
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Zeebe server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Zeebe starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable dev monitor for dev-services. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev monitor will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed debug export receiver port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Disable or enable debug exporter for the test. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable debug exporter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Fixed debug export receiver port the localhost service will listen to. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn directory and subdirectories. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the job worker. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an auto scan BPMN process folder. Default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+BPMN process root folder. Default bpmn +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether a metrics is enabled in case the micrometer or micro-profile metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an opentracing is published in case the smallrye-opentracing extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
Quarkus Zeebe extension. Zeebe’s cloud-native design provides the performance, resilience, and security enterprises need to future-proof their process orchestration efforts.
+If you want to use this extension, you need to add the io.quarkiverse.zeebe:quarkus-zeebe extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.zeebe</groupId>
+ <artifactId>quarkus-zeebe</artifactId>
+ <version>0.8.0</version>
+</dependency>+In version+>=0.8.0we replaced@ZeebeWorkerwith@JobWorkerannotation. +
+In version+>=0.7.0we removed the hazelcast dependency and zeebe-simple-monitor +for test and dev services. Now we do use zeebe-test-container with debug exporter +and zeebe-dev-monitor. In test module we remove our assert API and switch to Camunda BpmnAssert +from zeebe-process-test. Test api migration:io.quarkiverse.zeebe.test.BpmnAssert→io.camunda.zeebe.process.test.assertions.BpmnAssert+
Generally speaking there are three ways to configure your quarkus project to speak with camunda: +- Local dev instance with dev services +- Shared local dev instance +- Direct interaction with Camunda SaaS/ on-premise
+You can see some exemplary configurations for each of the setups below. Please note that these are only exemplary and can be adapted to your needs.
+# enable auto load bpmn resources
+quarkus.zeebe.resources.enabled=true
+# src/main/resources/bpmn
+quarkus.zeebe.resources.location=bpmn
+# Enable zeebe Dev Service:
+quarkus.zeebe.devservices.enabled=true
+# only start devservices, if no running docker container is found
+quarkus.zeebe.devservices.shared=true
+# zeebe service name
+quarkus.zeebe.devservices.service-name=zeebe_broker
+# enable reusable zeebe test-container (https://www.testcontainers.org/features/reuse/)
+quarkus.zeebe.devservices.reuse=false
+# enable zeebe monitor Dev Service:
+quarkus.zeebe.devservices.monitor.enabled=true
+# zeebe monitor service name
+quarkus.zeebe.devservices.monitor.service-name=zeebe-dev-monitor
+# enable reusable zeebe test-container (https://www.testcontainers.org/features/reuse/)
+quarkus.zeebe.devservices.monitor.reuse=false
+# enable hot restart for bpmn subdirectories changes
+quarkus.zeebe.dev-mode.watch-bpmn-dir=true
+# enable hot restart for bpmn files changes
+quarkus.zeebe.dev-mode.watch-bpmn-files=true
+# enable hot restart for job worker changes
+quarkus.zeebe.dev-mode.watch-job-worker=truequarkus.zeebe.client.broker.gateway-address=localhost:26500
+# If you are sure that there is already an instance running, yu can directly deactivate it
+quarkus.zeebe.devservices.enabled=false
+quarkus.zeebe.devservices.shared=true
+quarkus.zeebe.devservices.monitor.serviceName=zeebe-dev-monitor
+quarkus.zeebe.devservices.serviceName=zeebe_brokerPreferably you would be using a dev instance of Camunda and not your production process engine ;)
+# Disable local dev services
+quarkus.zeebe.devservices.enabled=false
+
+# Enter your cloud credentials from the zeebe portal
+quarkus.zeebe.client.broker.gateway-address=
+# Specify a cluster id.
+quarkus.zeebe.client.cloud.cluster-id=
+# Specify a client id.
+quarkus.zeebe.client.cloud.client-id=
+# Specify a client secret to request an access token.
+quarkus.zeebe.client.cloud.client-secret=
+# Specify a cloud region.
+quarkus.zeebe.client.cloud.region=
+quarkus.zeebe.client.cloud.base-url=zeebe.camunda.io
+quarkus.zeebe.client.cloud.auth-url=https://login.cloud.camunda.io/oauth/token
+quarkus.zeebe.client.cloud.port=443
+
+# Make sure you are disabling plaintext security, otherwise connection will fail
+quarkus.zeebe.client.security.plaintext=falseWhether zeebe metrics is enabled or not is done by quarkus.zeebe.metrics.enabled build time property.
+The default is true, but shown here to indicate how it can be disabled.
quarkus.zeebe.metrics.enabled=trueYou can access the following metrics:
+camunda.job.invocations: Number of invocations of job workers (tagging the job type)
activated: The job was activated and started to process an item
completed: The processing was completed successfully
failed: The processing failed with some exception
bpmn-error: The processing completed by throwing an ZeebeBpmnError (which means there was no technical problem)
Example:
+# TYPE camunda_job_invocations counter
+# HELP camunda_job_invocations
+camunda_job_invocations_total{action="activated",type="gateway-empty-data"} 1.0
+camunda_job_invocations_total{action="completed",type="gateway-show-data"} 2.0
+camunda_job_invocations_total{action="activated",type="gateway-show-data"} 2.0
+camunda_job_invocations_total{action="completed",type="gateway-read-data"} 2.0If you already have your Quarkus project configured, you can add the quarkus-micrometer-registry-prometheus extension to your project.
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
+</dependency>Whether zeebe tracing is enabled or not is done by quarkus.zeebe.tracing.enabled build time property. The default is true, but shown here to indicate how it can be disabled.
quarkus.zeebe.tracing.enabled=true
+If you already have your Quarkus project configured, you can add the quarkus-opentelemetry-exporter-otlp extension to your project.
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-opentelemetry-exporter-otlp</artifactId>
+</dependency>Dev Services for Zeebe is automatically enabled unless:
+* quarkus.zeebe.devservices.enabled is set to false
+* quarkus.zeebe.broker.gateway-address is configured
Dev Service for Zeebe relies on Docker to start the broker. If your environment does not support Docker, you will need
+to start the broker manually, or connect to an already running broker. You can configure the broker address using
+quarkus.zeebe.broker.gateway-address.
+To activate Zeebe-Dev-Monitor Dev Service use this configuration:
+quarkus.zeebe.devservices.enabled=true
+quarkus.zeebe.devservices.monitor.enabled=trueProperty qquarkus.zeebe.devservices.monitor.enabled=true will activate the debug exporter.
You need to configure the job type via the JobWorker annotation:
@JobWorker(type = "my-job")
+public void executeMyJob() {
+ // handles jobs of type 'my-job'
+}If you don’t specify the type the method name is use as default:
@JobWorker
+public void test() {
+ // handles jobs of type 'test'
+}Or you can set a default job type:
+quarkus.zeebe.client.job.default-type=testYou can specify that you only want to fetch some variables or when executing a job, which can decrease load and improve +performance:
+@JobWorker(type="test", fetchVariables={"var1", "var2"})
+public void test(final JobClient client, final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}By using the @Variable annotation there is a shortcut to make variable retrieval simpler, including the type cast:
@JobWorker(type="test")
+public void test(final JobClient client, final ActivatedJob job, @Variable String var1) {
+ System.out.println(var1);
+ // ...
+}With @Variable or fetchVariables you limit which variables are loaded from the workflow engine.
+You can also override this with fetchAllVariables and force that all variables are loaded anyway:
@JobWorker(type="test", fetchAllVariables=true)
+public void test(final JobClient client, final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}You can also use your own class into which the process variables are mapped to (comparable with getVariablesAsType() in
+the Java Client API). Therefore, use the @VariablesAsType annotation. In the below example, Parameter refers to your own class:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p) {
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+ return param;
+}JobYou can access variables of a process via the ActivatedJob object, which is passed into the method if it is a parameter:
+@JobWorker(type="test")
+public void test(final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}You can use the @CustomHeader annotation for a parameter to retrieve custom header for a job:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p, @CustomHeader String header1, @CustomHeader("custom-header") String header2) {
+ System.out.println(header1);
+ System.out.println(header2);
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+ return param;
+}You can use the @CustomHeaders annotation for a parameter to retrieve custom headers for a job:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p, @CustomHeaders Map<String, String> headers) {
+ System.out.println(headers.get("header1"));
+ System.out.println(headers.get("custom-header"));
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+}By default, the autoComplete attribute is set to true for any job worker. In this case, the Quarkus extension will take +care about job completion for you:
+@JobWorker(type = "job1")
+public void job1(final ActivatedJob job) {
+ // ... custom code ...
+ // no need to call client.newCompleteCommand()...
+}Note that the code within the handler method needs to be synchronously executed, as the completion will be triggered +right after the method has finished.
+When using autoComplete you can:
+* Return a Map, String, InputStream, or Object, which then will be added to the process variables
+* Throw a ZeebeBpmnError which results in a BPMN error being sent to Zeebe
+* Throw any other Exception that leads in a failure handed over to Zeebe
@JobWorker(type = "job1")
+public Map<String, Object> job1(final ActivatedJob job) {
+ // ... custom code ...
+ if (ok) {
+ return responseMap;
+ } else {
+ throw new ZeebeBpmnError("Error code", "Error message");
+ }
+}Your job worker code can also complete the job itself. This gives you more control about when exactly you want to +complete the job (e.g. allowing the completion to be moved to reactive callbacks):
+@JobWorker(type = "job1")
+public void job1(final JobClient client, final ActivatedJob job) {
+ // ... custom code ...
+ client.newCompleteCommand(job.getKey()).send()
+ .exceptionally( throwable -> { throw new RuntimeException("Could not complete job " + job, throwable); });
+}Ideally, you don’t use blocking behavior like send().join(), as this is blocking call to wait for the issues command
+to be executed on the workflow engine. While this is very straightforward to use and produces easy-to-read code,
+blocking code is limited in terms of scalability.
That’s why the worker above showed a different pattern (using exceptionally), often you might also want to use the +whenComplete callback:
+ client.newCompleteCommand(job.getKey()).send()
+ .whenComplete((result, exception) -> {});This registers a callback to be executed if the command on the workflow engine was executed or resulted in an exception. +This allows for parallelism. This is discussed in more detail in +this blog post about writing good workers for Camunda Cloud.
+
+Note that when completing jobs programmatically, you must specify autoComplete = false. Otherwise, there is a race
+condition between your programmatic job completion and the Quarkus extension integration job completion, this can
+lead to unpredictable results.
+
+ZeebeBpmnErrorWhenever your code hits a problem that should lead to a BPMN error being raised, you can simply throw a ZeebeBpmnError +providing the error code used in BPMN:
+@JobWorker(type = "job1")
+public Map<String, Object> job1(final ActivatedJob job) {
+ // ... custom code ...
+ if (ok) {
+ return responseMap;
+ } else {
+ throw new ZeebeBpmnError("Error code", "Error message");
+ }
+}By default, a scheduled method is executed on the main executor for blocking tasks. As a result, a technology that is
+designed to run on a Vert.x event loop (such as Hibernate Reactive) cannot be used inside the method body. For this
+reason, a job worker method that returns java.util.concurrent.CompletionStage<?> or io.smallrye.mutiny.Uni<Void>
+or is annotated with @io.smallrye.common.annotation.NonBlocking is executed on the Vert.x event loop.
@JobWorker(type = "job1")
+public Uni<Void> job1(final ActivatedJob job) {
+ // ... custom code ...
+ // no need to call client.newCompleteCommand()...
+}The return type Uni<Void> instructs the job worker to execute the method on the Vert.x event loop.
To use the test extension, add this dependency to the project:
+<dependency>
+ <groupId>io.quarkiverse.zeebe</groupId>
+ <artifactId>quarkus-zeebe-test</artifactId>
+ <version>{version}</version>
+ <scope>test</scope>
+</dependency>
+To use the ZeebeClient and BpmnAssert in the tests use the @QuarkusTestResource(ZeebeTestResource.class) and enable this configuration:
quarkus.zeebe.devservices.enabled=trueTest example
+import io.quarkiverse.zeebe.test.ZeebeTestResource;
+import io.quarkus.test.common.QuarkusTestResource;
+import io.camunda.zeebe.client.ZeebeClient;
+
+@QuarkusTest
+@QuarkusTestResource(ZeebeTestResource.class)
+public class BaseTest {
+
+ @InjectZeebeClient
+ ZeebeClient client;
+
+ @Test
+ public void startProcessTest() {
+ ProcessInstanceEvent event = client.newCreateInstanceCommand()
+ .bpmnProcessId("test").latestVersion()
+ .variables(Map.of("k","v")).send().join();
+
+ ProcessInstanceAssert a = BpmnAssert.assertThat(event);
+ await().atMost(7, SECONDS).untilAsserted(a::isCompleted);
+ }
+}We can reuse the test for the integration test.
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+
+@QuarkusIntegrationTest
+public class BaseIT extends BaseTest {
+
+}For more information check examples in the integration-tests directory in this repo.
+The Zeebe process test embedded engine requires Java version >= 17 ++
import io.quarkiverse.zeebe.test.ZeebeTestEmbeddedResource;
+import io.quarkus.test.common.QuarkusTestResource;
+import io.camunda.zeebe.client.ZeebeClient;
+
+@QuarkusTest
+@QuarkusTestResource(ZeebeTestEmbeddedResource.class)
+public class BaseTest {
+
+ @InjectZeebeClient
+ ZeebeClient client;
+
+ @Test
+ public void startProcessTest() {
+ ProcessInstanceEvent event = client.newCreateInstanceCommand()
+ .bpmnProcessId("test").latestVersion()
+ .variables(Map.of("k","v")).send().join();
+
+ ProcessInstanceAssert a = BpmnAssert.assertThat(event);
+ await().atMost(7, SECONDS).untilAsserted(a::isCompleted);
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Zeebe server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Zeebe starts a new container.
+The discovery uses the
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable dev monitor for dev-services. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev monitor will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed debug export receiver port the dev service will listen to. +If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Disable or enable debug exporter for the test. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable debug exporter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Fixed debug export receiver port the localhost service will listen to. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn directory and subdirectories. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the job worker. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an auto scan BPMN process folder. Default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+BPMN process root folder. Default bpmn +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether a metrics is enabled in case the micrometer or micro-profile metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an opentracing is published in case the smallrye-opentracing extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Zeebe server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Zeebe starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Zeebe servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable dev monitor for dev-services. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev monitor will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Zeebe servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed debug export receiver port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Disable or enable debug exporter for the test. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable debug exporter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Fixed debug export receiver port the localhost service will listen to. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn directory and subdirectories. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the job worker. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an auto scan BPMN process folder. Default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+BPMN process root folder. Default bpmn +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether a metrics is enabled in case the micrometer or micro-profile metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an opentracing is published in case the smallrye-opentracing extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Zeebe gateway address. Default: localhost:26500 +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Client keep alive duration +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Cloud cluster ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud client secret ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specify a client secret to request an access token. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud region +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Cloud base URL +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Cloud authorization server URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud port +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Cloud credentials cache path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OAuth client secret ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specify a client secret to request an access token. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Authorization server URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Credentials cache path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OAuth connect timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+OAuth read timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Zeebe token audience +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Maximum retries for the auto-completion command. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Maximum retries for the auto-completion command. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the backoff supplier. The supplier is called to determine the retry delay after each failed request; the worker then waits until the returned delay has elapsed before sending the next request. Note that this is used only for the polling mechanism - failures in the JobHandler should be handled there, and retried there if need be. Sets the backoff multiplication factor. The previous delay is multiplied by this factor. Default is 1.5. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the jitter factor. The next delay is changed randomly within a range of +/- this factor. For example, if the next delay is calculated to be 1s and the jitterFactor is 0.1 then the actual next delay can be somewhere between 0.9 and 1.1s. Default is 0.2 +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the maximum retry delay. Note that the jitter may push the retry delay over this maximum. Default is 1000ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the minimum retry delay. Note that the jitter may push the retry delay below this minimum. Default is 50ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Client message time to live duration. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client security plaintext flag. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specify a path to a certificate with which to validate gateway requests. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Overrides the authority used with TLS virtual hosting. Specifically, to override hostname verification in the TLS handshake. It does not change what host is actually connected to. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client worker maximum active jobs. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Client worker number of threads +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Client worker default name +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Zeebe client request timeout configuration. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client worker global type +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client job timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client job pool interval +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Sets the backoff supplier. The supplier is called to determine the retry delay after each failed request; the worker then waits until the returned delay has elapsed before sending the next request. Note that this is used only for the polling mechanism - failures in the JobHandler should be handled there, and retried there if need be. Sets the backoff multiplication factor. The previous delay is multiplied by this factor. Default is 1.6. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the jitter factor. The next delay is changed randomly within a range of +/- this factor. For example, if the next delay is calculated to be 1s and the jitterFactor is 0.1 then the actual next delay can be somewhere between 0.9 and 1.1s. Default is 0.1 +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the maximum retry delay. Note that the jitter may push the retry delay over this maximum. Default is 5000ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the minimum retry delay. Note that the jitter may push the retry delay below this minimum. Default is 50ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+List of span names +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Zeebe worker enable or disable flag. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Zeebe worker handler name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Zeebe worker timeout. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Zeebe worker maximum jobs active. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Zeebe worker request timeout. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Zeebe worker poll interval. +
+
+Environment variable: |
+long |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Quarkus Zeebe extension. Zeebe’s cloud-native design provides the performance, resilience, and security enterprises need to future-proof their process orchestration efforts.
+If you want to use this extension, you need to add the io.quarkiverse.zeebe:quarkus-zeebe extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
+<dependency>
+ <groupId>io.quarkiverse.zeebe</groupId>
+ <artifactId>quarkus-zeebe</artifactId>
+ <version>1.3.0</version>
+</dependency>+In version+>=0.8.0we replaced@ZeebeWorkerwith@JobWorkerannotation. +
+In version+>=0.7.0we removed the hazelcast dependency and zeebe-simple-monitor +for test and dev services. Now we do use zeebe-test-container with debug exporter +and zeebe-dev-monitor. In test module we remove our assert API and switch to Camunda BpmnAssert +from zeebe-process-test. Test api migration:io.quarkiverse.zeebe.test.BpmnAssert→io.camunda.zeebe.process.test.assertions.BpmnAssert+
Generally speaking there are three ways to configure your quarkus project to speak with camunda: +- Local dev instance with dev services +- Shared local dev instance +- Direct interaction with Camunda SaaS/ on-premise
+You can see some exemplary configurations for each of the setups below. Please note that these are only exemplary and can be adapted to your needs.
+# enable auto load bpmn resources
+quarkus.zeebe.resources.enabled=true
+# src/main/resources/bpmn
+quarkus.zeebe.resources.location=bpmn
+# Enable zeebe Dev Service:
+quarkus.zeebe.devservices.enabled=true
+# only start devservices, if no running docker container is found
+quarkus.zeebe.devservices.shared=true
+# zeebe service name
+quarkus.zeebe.devservices.service-name=zeebe_broker
+# enable reusable zeebe test-container (https://www.testcontainers.org/features/reuse/)
+quarkus.zeebe.devservices.reuse=false
+# enable zeebe monitor Dev Service:
+quarkus.zeebe.devservices.monitor.enabled=true
+# zeebe monitor service name
+quarkus.zeebe.devservices.monitor.service-name=zeebe-dev-monitor
+# enable reusable zeebe test-container (https://www.testcontainers.org/features/reuse/)
+quarkus.zeebe.devservices.monitor.reuse=false
+# enable hot restart for bpmn subdirectories changes
+quarkus.zeebe.dev-mode.watch-bpmn-dir=true
+# enable hot restart for bpmn files changes
+quarkus.zeebe.dev-mode.watch-bpmn-files=true
+# enable hot restart for job worker changes
+quarkus.zeebe.dev-mode.watch-job-worker=truequarkus.zeebe.client.broker.gateway-address=localhost:26500
+# If you are sure that there is already an instance running, yu can directly deactivate it
+quarkus.zeebe.devservices.enabled=false
+quarkus.zeebe.devservices.shared=true
+quarkus.zeebe.devservices.monitor.serviceName=zeebe-dev-monitor
+quarkus.zeebe.devservices.serviceName=zeebe_brokerPreferably you would be using a dev instance of Camunda and not your production process engine ;)
+# Disable local dev services
+quarkus.zeebe.devservices.enabled=false
+
+# Enter your cloud credentials from the zeebe portal
+quarkus.zeebe.client.broker.gateway-address=
+# Specify a cluster id.
+quarkus.zeebe.client.cloud.cluster-id=
+# Specify a client id.
+quarkus.zeebe.client.cloud.client-id=
+# Specify a client secret to request an access token.
+quarkus.zeebe.client.cloud.client-secret=
+# Specify a cloud region.
+quarkus.zeebe.client.cloud.region=
+quarkus.zeebe.client.cloud.base-url=zeebe.camunda.io
+quarkus.zeebe.client.cloud.auth-url=https://login.cloud.camunda.io/oauth/token
+quarkus.zeebe.client.cloud.port=443
+
+# Make sure you are disabling plaintext security, otherwise connection will fail
+quarkus.zeebe.client.security.plaintext=falseWhether zeebe metrics is enabled or not is done by quarkus.zeebe.metrics.enabled build time property.
+The default is true, but shown here to indicate how it can be disabled.
quarkus.zeebe.metrics.enabled=trueYou can access the following metrics:
+camunda.job.invocations: Number of invocations of job workers (tagging the job type)
activated: The job was activated and started to process an item
completed: The processing was completed successfully
failed: The processing failed with some exception
bpmn-error: The processing completed by throwing an ZeebeBpmnError (which means there was no technical problem)
Example:
+# TYPE camunda_job_invocations counter
+# HELP camunda_job_invocations
+camunda_job_invocations_total{action="activated",type="gateway-empty-data"} 1.0
+camunda_job_invocations_total{action="completed",type="gateway-show-data"} 2.0
+camunda_job_invocations_total{action="activated",type="gateway-show-data"} 2.0
+camunda_job_invocations_total{action="completed",type="gateway-read-data"} 2.0Whether zeebe tracing is enabled or not is done by quarkus.zeebe.tracing.enabled build time property. The default is true, but shown here to indicate how it can be disabled.
quarkus.zeebe.tracing.enabled=trueIf you already have your Quarkus project configured, you can add the quarkus-opentelemetry-exporter-otlp extension to your project.
<dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-opentelemetry-exporter-otlp</artifactId>
+</dependency>Dev Services for Zeebe is automatically enabled unless:
+* quarkus.zeebe.devservices.enabled is set to false
+* quarkus.zeebe.broker.gateway-address is configured
Dev Service for Zeebe relies on Docker to start the broker. If your environment does not support Docker, you will need
+to start the broker manually, or connect to an already running broker. You can configure the broker address using
+quarkus.zeebe.broker.gateway-address.
+To activate Zeebe-Dev-Monitor Dev Service use this configuration:
+quarkus.zeebe.devservices.enabled=true
+quarkus.zeebe.devservices.monitor.enabled=trueProperty qquarkus.zeebe.devservices.monitor.enabled=true will activate the debug exporter.
You need to configure the job type via the JobWorker annotation:
@JobWorker(type = "my-job")
+public void executeMyJob() {
+ // handles jobs of type 'my-job'
+}If you don’t specify the type the method name is use as default:
@JobWorker
+public void test() {
+ // handles jobs of type 'test'
+}Or you can set a default job type:
+quarkus.zeebe.client.job.default-type=testYou can specify that you only want to fetch some variables or when executing a job, which can decrease load and improve +performance:
+@JobWorker(type="test", fetchVariables={"var1", "var2"})
+public void test(final JobClient client, final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}By using the @Variable annotation there is a shortcut to make variable retrieval simpler, including the type cast:
@JobWorker(type="test")
+public void test(final JobClient client, final ActivatedJob job, @Variable String var1) {
+ System.out.println(var1);
+ // ...
+}With @Variable or fetchVariables you limit which variables are loaded from the workflow engine.
+You can also override this with fetchAllVariables and force that all variables are loaded anyway:
@JobWorker(type="test", fetchAllVariables=true)
+public void test(final JobClient client, final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}You can also use your own class into which the process variables are mapped to (comparable with getVariablesAsType() in
+the Java Client API). Therefore, use the @VariablesAsType annotation. In the below example, Parameter refers to your own class:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p) {
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+ return param;
+}JobYou can access variables of a process via the ActivatedJob object, which is passed into the method if it is a parameter:
+@JobWorker(type="test")
+public void test(final ActivatedJob job) {
+ String var1 = (String) job.getVariablesAsMap().get("var1");
+ System.out.println(var1);
+ // ...
+}You can use the @CustomHeader annotation for a parameter to retrieve custom header for a job:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p, @CustomHeader String header1, @CustomHeader("custom-header") String header2) {
+ System.out.println(header1);
+ System.out.println(header2);
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+ return param;
+}You can use the @CustomHeaders annotation for a parameter to retrieve custom headers for a job:
@JobWorker(type = "job1")
+public void job1(@VariablesAsType Parameter p, @CustomHeaders Map<String, String> headers) {
+ System.out.println(headers.get("header1"));
+ System.out.println(headers.get("custom-header"));
+ System.out.println(p.getValue());
+ p.setValue(1);
+ // ... custom code
+}By default, the autoComplete attribute is set to true for any job worker. In this case, the Quarkus extension will take +care about job completion for you:
+@JobWorker(type = "job1")
+public void job1(final ActivatedJob job) {
+ // ... custom code ...
+ // no need to call client.newCompleteCommand()...
+}Note that the code within the handler method needs to be synchronously executed, as the completion will be triggered +right after the method has finished.
+When using autoComplete you can:
+* Return a Map, String, InputStream, or Object, which then will be added to the process variables
+* Throw a ZeebeBpmnError which results in a BPMN error being sent to Zeebe
+* Throw any other Exception that leads in a failure handed over to Zeebe
@JobWorker(type = "job1")
+public Map<String, Object> job1(final ActivatedJob job) {
+ // ... custom code ...
+ if (ok) {
+ return responseMap;
+ } else {
+ throw new ZeebeBpmnError("Error code", "Error message");
+ }
+}Your job worker code can also complete the job itself. This gives you more control about when exactly you want to +complete the job (e.g. allowing the completion to be moved to reactive callbacks):
+@JobWorker(type = "job1")
+public void job1(final JobClient client, final ActivatedJob job) {
+ // ... custom code ...
+ client.newCompleteCommand(job.getKey()).send()
+ .exceptionally( throwable -> { throw new RuntimeException("Could not complete job " + job, throwable); });
+}Ideally, you don’t use blocking behavior like send().join(), as this is blocking call to wait for the issues command
+to be executed on the workflow engine. While this is very straightforward to use and produces easy-to-read code,
+blocking code is limited in terms of scalability.
That’s why the worker above showed a different pattern (using exceptionally), often you might also want to use the +whenComplete callback:
+ client.newCompleteCommand(job.getKey()).send()
+ .whenComplete((result, exception) -> {});This registers a callback to be executed if the command on the workflow engine was executed or resulted in an exception. +This allows for parallelism. This is discussed in more detail in +this blog post about writing good workers for Camunda Cloud.
+
+Note that when completing jobs programmatically, you must specify autoComplete = false. Otherwise, there is a race
+condition between your programmatic job completion and the Quarkus extension integration job completion, this can
+lead to unpredictable results.
+
+ZeebeBpmnErrorWhenever your code hits a problem that should lead to a BPMN error being raised, you can simply throw a ZeebeBpmnError +providing the error code used in BPMN:
+@JobWorker(type = "job1")
+public Map<String, Object> job1(final ActivatedJob job) {
+ // ... custom code ...
+ if (ok) {
+ return responseMap;
+ } else {
+ throw new ZeebeBpmnError("Error code", "Error message");
+ }
+}By default, a scheduled method is executed on the main executor for blocking tasks. As a result, a technology that is
+designed to run on a Vert.x event loop (such as Hibernate Reactive) cannot be used inside the method body. For this
+reason, a job worker method that returns java.util.concurrent.CompletionStage<?> or io.smallrye.mutiny.Uni<Void>
+or is annotated with @io.smallrye.common.annotation.NonBlocking is executed on the Vert.x event loop.
@JobWorker(type = "job1")
+public Uni<Void> job1(final ActivatedJob job) {
+ // ... custom code ...
+ // no need to call client.newCompleteCommand()...
+}The return type Uni<Void> instructs the job worker to execute the method on the Vert.x event loop.
To use the test extension, add this dependency to the project:
+<dependency>
+ <groupId>io.quarkiverse.zeebe</groupId>
+ <artifactId>quarkus-zeebe-test</artifactId>
+ <version>{version}</version>
+ <scope>test</scope>
+</dependency>To use the ZeebeClient and BpmnAssert in the tests use the @QuarkusTestResource(ZeebeTestResource.class) and enable this configuration:
quarkus.zeebe.devservices.enabled=trueTest example
+import io.quarkiverse.zeebe.test.ZeebeTestResource;
+import io.quarkus.test.common.QuarkusTestResource;
+import io.camunda.zeebe.client.ZeebeClient;
+
+@QuarkusTest
+@QuarkusTestResource(ZeebeTestResource.class)
+public class BaseTest {
+
+ @InjectZeebeClient
+ ZeebeClient client;
+
+ @Test
+ public void startProcessTest() {
+ ProcessInstanceEvent event = client.newCreateInstanceCommand()
+ .bpmnProcessId("test").latestVersion()
+ .variables(Map.of("k","v")).send().join();
+
+ ProcessInstanceAssert a = BpmnAssert.assertThat(event);
+ await().atMost(7, SECONDS).untilAsserted(a::isCompleted);
+ }
+}We can reuse the test for the integration test.
+import io.quarkus.test.junit.QuarkusIntegrationTest;
+
+@QuarkusIntegrationTest
+public class BaseIT extends BaseTest {
+
+}For more information check examples in the integration-tests directory in this repo.
+The Zeebe process test embedded engine requires Java version >= 17 ++
import io.quarkiverse.zeebe.test.ZeebeTestEmbeddedResource;
+import io.quarkus.test.common.QuarkusTestResource;
+import io.camunda.zeebe.client.ZeebeClient;
+
+@QuarkusTest
+@QuarkusTestResource(ZeebeTestEmbeddedResource.class)
+public class BaseTest {
+
+ @InjectZeebeClient
+ ZeebeClient client;
+
+ @Test
+ public void startProcessTest() {
+ ProcessInstanceEvent event = client.newCreateInstanceCommand()
+ .bpmnProcessId("test").latestVersion()
+ .variables(Map.of("k","v")).send().join();
+
+ ProcessInstanceAssert a = BpmnAssert.assertThat(event);
+ await().atMost(7, SECONDS).untilAsserted(a::isCompleted);
+ }
+}Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. +
+
+When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Indicates if the Zeebe server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Zeebe starts a new container. +
+
+The discovery uses the
+
+Container sharing is only used in dev mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Zeebe servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The container image name to use, for container based DevServices providers. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable dev monitor for dev-services. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed port the dev monitor will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+The container image name to use, for container based zeebe simple monitor. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+The value of the
+
+This property is used when you need multiple shared Zeebe servers. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Optional fixed debug export receiver port the dev service will listen to. +
+
+If not defined, the port will be chosen randomly. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Disable or enable debug exporter for the test. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Enable or disable debug exporter. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Fixed debug export receiver port the localhost service will listen to. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn files. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the bpmn directory and subdirectories. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Observe changes in the job worker. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an auto scan BPMN process folder. Default true +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+BPMN process root folder. Default bpmn +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Whether a metrics is enabled in case the micrometer or micro-profile metrics extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether a health check is published in case the smallrye-health extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether an opentracing is published in case the smallrye-opentracing extension is present. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Zeebe gateway address. Default: localhost:26500 +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Client keep alive duration +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Cloud cluster ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud client secret ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specify a client secret to request an access token. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud region +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Cloud base URL +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Cloud authorization server URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Cloud port +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Cloud credentials cache path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OAuth client secret ID +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specify a client secret to request an access token. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Authorization server URL +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Credentials cache path +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+OAuth connect timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+OAuth read timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Zeebe token audience +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Maximum retries for the auto-completion command. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Maximum retries for the auto-completion command. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the backoff supplier. The supplier is called to determine the retry delay after each failed request; the worker then waits until the returned delay has elapsed before sending the next request. Note that this is used only for the polling mechanism - failures in the JobHandler should be handled there, and retried there if need be. Sets the backoff multiplication factor. The previous delay is multiplied by this factor. Default is 1.5. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the jitter factor. The next delay is changed randomly within a range of +/- this factor. For example, if the next delay is calculated to be 1s and the jitterFactor is 0.1 then the actual next delay can be somewhere between 0.9 and 1.1s. Default is 0.2 +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the maximum retry delay. Note that the jitter may push the retry delay over this maximum. Default is 1000ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the minimum retry delay. Note that the jitter may push the retry delay below this minimum. Default is 50ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Client message time to live duration. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client security plaintext flag. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specify a path to a certificate with which to validate gateway requests. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Overrides the authority used with TLS virtual hosting. Specifically, to override hostname verification in the TLS handshake. It does not change what host is actually connected to. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client worker maximum active jobs. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Client worker number of threads +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Client worker default name +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Zeebe client request timeout configuration. +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client worker global type +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Client job timeout +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Client job pool interval +
+
+Environment variable: |
+Duration + |
+
|
+
+
+
+
+
+
+Sets the backoff supplier. The supplier is called to determine the retry delay after each failed request; the worker then waits until the returned delay has elapsed before sending the next request. Note that this is used only for the polling mechanism - failures in the JobHandler should be handled there, and retried there if need be. Sets the backoff multiplication factor. The previous delay is multiplied by this factor. Default is 1.6. +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the jitter factor. The next delay is changed randomly within a range of +/- this factor. For example, if the next delay is calculated to be 1s and the jitterFactor is 0.1 then the actual next delay can be somewhere between 0.9 and 1.1s. Default is 0.1 +
+
+Environment variable: |
+double |
+
|
+
+
+
+
+
+
+Sets the maximum retry delay. Note that the jitter may push the retry delay over this maximum. Default is 5000ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+Sets the minimum retry delay. Note that the jitter may push the retry delay below this minimum. Default is 50ms. +
+
+Environment variable: |
+long |
+
|
+
+
+
+
+
+
+List of span names +
+
+Environment variable: |
+list of string |
++ |
+
+
+
+
+
+Zeebe worker enable or disable flag. +
+
+Environment variable: |
+boolean |
++ |
+
+
+
+
+
+Zeebe worker handler name. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Zeebe worker timeout. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Zeebe worker maximum jobs active. +
+
+Environment variable: |
+int |
++ |
+
+
+
+
+
+Zeebe worker request timeout. +
+
+Environment variable: |
+long |
++ |
+
+
+
+
+
+Zeebe worker poll interval. +
+
+Environment variable: |
+long |
++ |
| + + | +
+ About the Duration format
+
+
+To write duration values, use the standard
+
+You can also use a simplified format, starting with a number: +
+
+
+
+In other cases, the simplified format is translated to the
+
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Connection timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Request timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise. +
+
+Environment variable: |
+int |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Comma separated host:port pairs, each corresponding to a zk server. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Session timeout in milliseconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Connection timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Request timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Comma separated host:port pairs, each corresponding to a zk server. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Session timeout in milliseconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Connection timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Request timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Comma separated host:port pairs, each corresponding to a zk server. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Session timeout in milliseconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Whether to enable health checks. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable health checks. +
+
+Environment variable: |
+boolean |
+
|
+
Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable health checks. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Connection timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Request timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Comma separated host:port pairs, each corresponding to a zk server. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Session timeout in milliseconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode. +
+
+Environment variable: |
+boolean |
+
|
+
Stateful client to Apache ZooKeeper (https://zookeeper.apache.org/).
+ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.
+If you want to use this extension, you need to add the io.quarkiverse.quarkus-zookeeper:quarkus-zookeeper extension first.
+In your pom.xml file, add:
<dependency>
+ <groupId>io.quarkiverse.quarkus-zookeeper</groupId>
+ <artifactId>quarkus-zookeeper</artifactId>
+</dependency>This extension produces an application scoped bean for the ZooKeeper client, which can be directly injected into a managed bean:
+@ApplicationScoped
+public class ZookeeperService implements AsyncObserverExceptionHandler {
+
+ private static final Logger LOG = Logger.getLogger(ZookeeperService.class);
+
+ @Inject ZooKeeper client;
+
+ public void onZKEvent(@ObservesAsync WatchedEvent event) {
+ LOG.infof("Receiving [%s]", event.getState());
+ }
+}As shown by the example, it also provides a binding between ZooKeeper watched events and an asynch CDI bus.
+Configuration property fixed at build time - All other configuration properties are overridable at runtime
+| + | Type |
+Default |
+
|---|---|---|
+
+
+
+
+
+Whether to enable health checks. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Set the value to true to enable SASL authentication. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies the context key in the JAAS login file. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+SALS client configuration string, e.g. org.apache.zookeeper.server.auth.DigestLoginModule required username="test" password="passwd"; +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper server, when Kerberos authentication is enabled. If this configuration is provided, then the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. The format of a typical Kerberos V5 principal is primary/instance@REALM. zookeeper.sasl.client.username specifies the primary part of the server principal. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting the fully qualified domain name belonging to the address. You can disable this 'canonicalization' by setting: zookeeper.sasl.client.canonicalize.hostname=false. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Realm part of the server principal. By default it is the client principal realm. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the local credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file path to a JKS containing the remote credentials to be used for SSL connections. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the password to unlock the file. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of keys store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Specifies the file format of trust store files used to establish TLS connection to the ZooKeeper server. Values: JKS, PEM, PKCS12 or null. +
+
+Environment variable: |
+string |
++ |
+
+
+
+
+
+Connection timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Request timeout in millis. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+This switch controls whether automatic watch resetting is enabled. Clients automatically reset watches during session reconnect by default, this option allows the client to turn off this behavior by setting zookeeper.disableAutoWatchReset to true. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+If you want to connect to the server secure client port, you need to set this property to true on the client. This will connect to server using SSL with specified credentials. Note that it requires the Netty client. +
+
+Environment variable: |
+boolean |
+
|
+
+
+
+
+
+
+Specifies which ClientCnxnSocket to be used. Possible values are org.apache.zookeeper.ClientCnxnSocketNIO and org.apache.zookeeper.ClientCnxnSocketNetty . Default is org.apache.zookeeper.ClientCnxnSocketNIO . If you want to connect to server’s secure client port, you need to set this property to org.apache.zookeeper.ClientCnxnSocketNetty on client. +
+
+Environment variable: |
+string |
+
|
+
+
+
+
+
+
+In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send data on the order of kilobytes. If incoming data length is more than this value, an IOException is raised. This value of client side should keep same with the server side(Setting System.setProperty("jute.maxbuffer", "xxxx") in the client side will work), otherwise problems will arise. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Comma separated host:port pairs, each corresponding to a zk server. +
+
+Environment variable: |
+string |
+required |
+
+
+
+
+
+
+Session timeout in milliseconds. +
+
+Environment variable: |
+int |
+
|
+
+
+
+
+
+
+Whether the created client is allowed to go to read-only mode in case of partitioning. Read-only mode basically means that if the client can’t find any majority servers but there’s partitioned server it could reach, it connects to one in read-only mode. +
+
+Environment variable: |
+boolean |
+
|
+