Customize serialization for Lambda Java functions - AWS Lambda
When to use custom serializationImplementing custom serializationTesting custom serialization

Customize serialization for Lambda Java functions

The Lambda Java managed runtimes support custom serialization for JSON events. Custom serialization can simplify your code and potentially improve performance.

When to use custom serialization

When your Lambda function is invoked, the input event data needs to be deserialized into a Java object, and the output from your function needs to be serialized back into a format that can be returned as the function's response. The Lambda Java managed runtimes provide default serialization and deserialization capabilities that work well for handling event payloads from various AWS services, such as Amazon API Gateway and Amazon Simple Queue Service (Amazon SQS). To work with these service integration events in your function, add the aws-java-lambda-events dependency to your project. This AWS library contains Java objects representing these service integration events.

You can also use your own objects to represent the event JSON that you pass to your Lambda function. The managed runtime attempts to serialize the JSON to a new instance of your object with its default behavior. If the default serializer doesn’t have the desired behavior for your use case, use custom serialization.

For example, assume that your function handler expects a Vehicle class as input, with the following structure:

public class Vehicle {
    private String vehicleType;
    private long vehicleId;
}

However, the JSON event payload looks like this:

{
    "vehicle-type": "car",
    "vehicleID": 123
}

In this scenario, the default serialization in the managed runtime expects the JSON property names to match the camel case Java class property names (vehicleType, vehicleId). Because the property names in the JSON event aren't in camel case (vehicle-type, vehicleID), you must use custom serialization.

Implementing custom serialization

Use a Service Provider Interface to load a serializer of your choice instead of the managed runtime’s default serialization logic. You can serialize your JSON event payloads directly into Java objects, using the standard RequestHandler interface.

To use custom serialization in your Lambda Java function

  1. Add the aws-lambda-java-core library as a dependency. This library includes the CustomPojoSerializer interface, along with other interface definitions for working with Java in Lambda.

  2. Create a file named com.amazonaws.services.lambda.runtime.CustomPojoSerializer in the src/main/META-INF/services/ directory of your project.

  3. In this file, specify the fully qualified name of your custom serializer implementation, which must implement the CustomPojoSerializer interface. Example:

    com.mycompany.vehicles.CustomLambdaSerialzer

  4. Implement the CustomPojoSerializer interface to provide your custom serialization logic.

  5. Use the standard RequestHandler interface in your Lambda function. The managed runtime will use your custom serializer.

For more examples of how to implement custom serialization using popular libraries such as fastJson, Gson, Moshi, and jackson-jr, see the custom-serialization sample in the AWS GitHub repository.

Testing custom serialization

Test your function to make sure that your serialization and deserialization logic is working as expected. You can use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) to emulate the invocation of your Lambda payload. This can help you quickly test and iterate on your function as you introduce a custom serializer.

  1. Create a file with the JSON event payload that you would like to invoke your function with then call the AWS SAM CLI.

  2. Run the sam local invoke command to invoke your function locally. Example:

    sam local invoke -e src/test/resources/event.json

For more information, see Locally invoke Lambda functions with AWS SAM.