Skip to content

Commit

Permalink
chore(v2): document use of aws-crt-client (aws-powertools#1092)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jreijn
jreijn committed Mar 14, 2024
1 parent 8f176cc commit 4036d07
Show file tree
Hide file tree
Showing 4 changed files with 147 additions and 57 deletions.
92 changes: 90 additions & 2 deletions docs/FAQs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Frequently Asked Questions

## How can I use Powertools for AWS Lambda (Java) with Lombok?

Poweretools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source.
Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. In case you want to use `Lombok` or other compile-time preprocessor for your project, it is required to change `aspectj-maven-plugin` configuration to enable in-place weaving feature. Otherwise the plugin will ignore changes introduced by `Lombok` and will use `.java` files as a source.

To enable in-place weaving feature you need to use following `aspectj-maven-plugin` configuration:

Expand All @@ -29,7 +29,7 @@ To enable in-place weaving feature you need to use following `aspectj-maven-plug

## How can I use Powertools for AWS Lambda (Java) with Kotlin projects?

Poweretools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`.
Powertools uses `aspectj-maven-plugin` to compile-time weave (CTW) aspects into the project. When using it with Kotlin projects, it is required to `forceAjcCompile`.
No explicit configuration should be required for gradle projects.

To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` configuration:
Expand All @@ -47,3 +47,91 @@ To enable `forceAjcCompile` you need to use following `aspectj-maven-plugin` con
</configuration>
```

## How can I use Powertools for AWS Lambda (Java) with the AWS CRT HTTP Client?

Powertools uses the `url-connection-client` as the default http client. The `url-connection-client` is a lightweight http client, which keeps the impact on Lambda cold starts to a minimum.
With the [announcement](https://aws.amazon.com/blogs/developer/announcing-availability-of-the-aws-crt-http-client-in-the-aws-sdk-for-java-2-x/) of the `aws-crt-client` a new http client has been released, which offers faster SDK startup time and smaller memory footprint.

Unfortunately, replacing the `url-connection-client` dependency with the `aws-crt-client` will not immediately improve the lambda cold start performance and memory footprint,
as the default version of the dependency contains low level libraries for all target runtimes (linux, macos, windows, etc).

Using the `aws-crt-client` in your project requires the exclusion of the `url-connection-client` transitive dependency from the powertools dependency.

```xml
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-parameters</artifactId>
<version>1.18.0</version>
<exclusions>
<exclusion>
<groupId>software.amazon.awssdk</groupId>
<artifactId>url-connection-client</artifactId>
</exclusion>
</exclusions>
</dependency>
```
Next to adding the `aws-crt-client` and excluding the `aws-crt` dependency (contain all runtime libraries) it's required to set a specific runtime version of the `aws-crt` dependency by specifying the classifier for your specific target runtime.
Specifying the specific target runtime makes sure all other target runtimes are excluded from the jar file, which will result in the benefit of improved cold start times.

```xml

<dependencies>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>aws-crt-client</artifactId>
<version>2.23.21</version>
<exclusions>
<exclusion>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.29.9</version>
<classifier>linux-x86_64</classifier>
</dependency>
</dependencies>
```

After configuring the dependencies it's required to specify the aws sdk http client.
Most modules support a custom sdk client by leveraging the `.withClient()` method on the for instance the Provider singleton:

```java hl_lines="11-16 19-20 22"
import static software.amazon.lambda.powertools.parameters.transform.Transformer.base64;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.services.ssm.SsmClient;
import software.amazon.lambda.powertools.parameters.ssm.SSMProvider;

public class RequestHandlerWithParams implements RequestHandler<String, String> {

// Get an instance of the SSMProvider. We can provide a custom client here if we want,
// for instance to use the aws crt http client.
SSMProvider ssmProvider = SSMProvider
.builder()
.withClient(
SsmClient.builder()
.httpClient(AwsCrtHttpClient.builder().build())
.build()
)
.build();

public String handleRequest(String input, Context context) {
// Retrieve a single param
String value = ssmProvider
.get("/my/secret");
// We might instead want to retrieve multiple parameters at once, returning a Map of key/value pairs
// .getMultiple("/my/secret/path");

// Return the result
return value;
}
}
```
It has been considered to make the `aws-crt-client` the default http client in Lambda Powertools for Java, as mentioned in [Move SDK http client to CRT](https://github.com/aws-powertools/powertools-lambda-java/issues/1092),
but due to the impact on the developer experience it was decided to stick with the `url-connection-client`.
26 changes: 13 additions & 13 deletions docs/utilities/batch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -530,19 +530,19 @@ Handlers can be provided when building the batch processor and are available for
For instance for DynamoDB:

```java
BatchMessageHandler<DynamodbEvent, StreamsEventResponse> handler = new BatchMessageHandlerBuilder()
.withDynamoDbBatchHandler()
.withSuccessHandler((m) -> {
// Success handler receives the raw message
LOGGER.info("Message with sequenceNumber {} was successfully processed",
m.getDynamodb().getSequenceNumber());
})
.withFailureHandler((m, e) -> {
// Failure handler receives the raw message and the exception thrown.
LOGGER.info("Message with sequenceNumber {} failed to be processed: {}"
, e.getDynamodb().getSequenceNumber(), e);
})
.buildWithMessageHander(this::processMessage);
BatchMessageHandler<DynamodbEvent, StreamsEventResponse> handler = new BatchMessageHandlerBuilder()
.withDynamoDbBatchHandler()
.withSuccessHandler((m) -> {
// Success handler receives the raw message
LOGGER.info("Message with sequenceNumber {} was successfully processed",
m.getDynamodb().getSequenceNumber());
})
.withFailureHandler((m, e) -> {
// Failure handler receives the raw message and the exception thrown.
LOGGER.info("Message with sequenceNumber {} failed to be processed: {}"
, e.getDynamodb().getSequenceNumber(), e);
})
.buildWithMessageHander(this::processMessage);
```

!!! info
Expand Down
85 changes: 43 additions & 42 deletions docs/utilities/large_messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,48 +97,49 @@ of amazon-sns-java-extended-client-lib.
Depending on your version of Java (either Java 1.8 or 11+), the configuration slightly changes.

=== "Maven Java 11+"
```xml hl_lines="3-7 16 18 24-27"
<dependencies>
...
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
<version>{{ powertools.version }}</version>
</dependency>
...
</dependencies>
...
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
<build>
<plugins>
...
<plugin>
<groupId>dev.aspectj</groupId>
<artifactId>aspectj-maven-plugin</artifactId>
<version>1.13.1</version>
<configuration>
<source>11</source> <!-- or higher -->
<target>11</target> <!-- or higher -->
<complianceLevel>11</complianceLevel> <!-- or higher -->
<aspectLibraries>
<aspectLibrary>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
</aspectLibrary>
</aspectLibraries>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
```

```xml hl_lines="3-7 16 18 24-27"
<dependencies>
...
<dependency>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
<version>{{ powertools.version }}</version>
</dependency>
...
</dependencies>
...
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
<build>
<plugins>
...
<plugin>
<groupId>dev.aspectj</groupId>
<artifactId>aspectj-maven-plugin</artifactId>
<version>1.13.1</version>
<configuration>
<source>11</source> <!-- or higher -->
<target>11</target> <!-- or higher -->
<complianceLevel>11</complianceLevel> <!-- or higher -->
<aspectLibraries>
<aspectLibrary>
<groupId>software.amazon.lambda</groupId>
<artifactId>powertools-large-messages</artifactId>
</aspectLibrary>
</aspectLibraries>
</configuration>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
```

=== "Maven Java 1.8"

Expand Down
1 change: 1 addition & 0 deletions docs/utilities/parameters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,7 @@ To simplify the use of the library, you can chain all method calls before a get.
.withTransformation(json) // json is a static import from Transformer.json
.withDecryption() // enable decryption of the parameter value
.get("/my/param", MyObj.class); // finally get the value
```

### Create your own Provider
You can create your own custom parameter store provider by implementing a handful of classes:
Expand Down

0 comments on commit 4036d07

Please sign in to comment.