Definir el controlador de las funciones de Lambda en Java

El controlador de la función de Lambda es el método del código de la función que procesa eventos. Cuando se invoca una función, Lambda ejecuta el método del controlador. La función se ejecuta hasta que el controlador devuelve una respuesta, se cierra o se agota el tiempo de espera.

En esta página, se describe cómo trabajar con los controladores de funciones de Lambda en Java, incluidas opciones para la configuración del proyecto, las convenciones de nomenclatura y las prácticas recomendadas. Esta página también incluye un ejemplo de una función de Lambda de Java que recibe información sobre un pedido, genera un recibo en un archivo de texto y coloca este archivo en un bucket de Amazon Simple Storage Service (S3). Para obtener información sobre cómo implementar la función después de escribirla, consulte Implementar funciones de Lambda Java con archivos de archivo .zip o JAR o Implementar funciones Java Lambda con imágenes de contenedor.

Configuración del proyecto de controlador de Java

Cuando se trabaja con funciones de Lambda en Java, el proceso implica escribir el código, compilarlo e implementar los artefactos compilados en Lambda. Puede inicializar un proyecto de Lambda en Java de varias maneras. Por ejemplo, puede usar herramientas como el Arquetipo de Maven para funciones de Lambda, el comando sam init de AWS SAM CLI o incluso una configuración de proyecto Java estándar en su IDE preferido, como IntelliJ IDEA o Visual Studio Code. Si lo prefiere, puede crear la estructura de archivos necesaria de forma manual.

Un proyecto típico de la función de Lambda en Java sigue esta estructura general:

/project-root
    └ src
        └ main
            └ java
                └ example
                    └ OrderHandler.java (contains main handler)
                    └ <other_supporting_classes>
     └ build.gradle OR pom.xml

Puede usar Maven o Gradle para crear su proyecto y administrar las dependencias.

La lógica del controlador principal de su función reside en un archivo Java ubicado en el directorio src/main/java/example. En el ejemplo de esta página, el nombre de este archivo es OrderHandler.java. Además de este archivo, puede incluir clases de Java adicionales según sea necesario. Al implementar la función en Lambda, asegúrese de especificar la clase de Java que contiene el método de controlador principal que Lambda debe invocar durante una invocación.

Ejemplo de código de función de Lambda de Java

El siguiente ejemplo de código de función de Lambda de Java 21 recibe información sobre un pedido, genera un recibo en un archivo de texto y coloca este archivo en un bucket de Amazon S3.

package example;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

import java.nio.charset.StandardCharsets;

/**
 * Lambda handler for processing orders and storing receipts in S3.
 */
public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {

    private static final S3Client S3_CLIENT = S3Client.builder().build();

    /**
     * Record to model the input event.
     */
    public record Order(String orderId, double amount, String item) {}

    @Override
    public String handleRequest(Order event, Context context) {
        try {
            // Access environment variables
            String bucketName = System.getenv("RECEIPT_BUCKET");
            if (bucketName == null || bucketName.isEmpty()) {
                throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
            }

            // Create the receipt content and key destination
            String receiptContent = String.format("OrderID: %s\nAmount: $%.2f\nItem: %s",
                    event.orderId(), event.amount(), event.item());
            String key = "receipts/" + event.orderId() + ".txt";

            // Upload the receipt to S3
            uploadReceiptToS3(bucketName, key, receiptContent);

            context.getLogger().log("Successfully processed order " + event.orderId() +
                    " and stored receipt in S3 bucket " + bucketName);
            return "Success";

        } catch (Exception e) {
            context.getLogger().log("Failed to process order: " + e.getMessage());
            throw new RuntimeException(e);
        }
    }

    private void uploadReceiptToS3(String bucketName, String key, String receiptContent) {
        try {
            PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

            // Convert the receipt content to bytes and upload to S3
            S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));
        } catch (S3Exception e) {
            throw new RuntimeException("Failed to upload receipt to S3: " + e.awsErrorDetails().errorMessage(), e);
        }
    }
}

Este archivo OrderHandler.java contiene las siguientes secciones de código:

Para que esta función se ejecute correctamente, su rol de ejecución debe permitir la acción s3:PutObject. Además, asegúrese de definir la variable de entorno RECEIPT_BUCKET. Tras una invocación correcta, el bucket de Amazon S3 debe contener un archivo de recibo.

Definiciones de clase válidas para los controladores de Java

Para definir su clase, la biblioteca aws-lambda-java-core define dos interfaces para los métodos de controlador. Utilice las interfaces proporcionadas para simplificar la configuración del controlador y validar la firma del método en tiempo de compilación.

La interfaz RequestHandler es un tipo genérico que toma dos parámetros: el tipo de entrada y el tipo de salida. Los dos tipos deben ser objetos. En este ejemplo, nuestra clase OrderHandler implementa RequestHandler<OrderHandler.Order, String>. El tipo de entrada es el registro Order que definimos dentro de la clase y el tipo de salida es String.

public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {
    ...
}

Cuando se utiliza esta interfaz, el tiempo de ejecución de Java deserializa el evento en un objeto con el tipo de entrada y serializa la salida en texto. Utilice esta interfaz si la serialización integrada funcione con los tipos de entrada y salida.

Para usar su propia serialización, puede implementar la interfaz RequestStreamHandler. Con esta interfaz, Lambda pasa al controlador un flujo de entrada y otrp flujo de salida. El controlador lee los bytes de la secuencia de entrada, escribe en la secuencia de salida y devuelve void. Para ver un ejemplo de esto con el tiempo de ejecución de Java 21, consulte HandlerStream.java.

Si solo trabaja con tipos básicos y genéricos (es decir String, Integer, =List o Map) en su función de Java, no necesita implementar una interfaz. Por ejemplo, si la función recibe una entrada Map<String, String> y devuelve un String, la definición de la clase y la firma del controlador pueden verse como el siguiente ejemplo:

public class ExampleHandler {
    public String handleRequest(Map<String, String> input, Context context) {
        ...
    }
}

Además, cuando no implementa una interfaz, el objeto de contexto es opcional. Por ejemplo, la definición de la clase y la firma del controlador pueden verse como el siguiente ejemplo:

public class NoContextHandler {
   public String handleRequest(Map<String, String> input) {
        ...
   }
}

Convenciones de nomenclatura de controladores

Para las funciones de Lambda en Java, si implementa la interfaz de RequestHandler o RequestStreamHandler, el método de su controlador principal debe tener handleRequest como nombre. Además, incluya la etiqueta @Override situada sobre el método handleRequest. Cuando implemente la función en Lambda, especifique el controlador principal en la configuración de la función en el siguiente formato:

En el caso de las funciones de Lambda en Java que no implementan la interfaz de RequestHandler o RequestStreamHandler, es posible utilizar cualquier nombre para el controlador. Cuando implemente la función en Lambda, especifique el controlador principal en la configuración de la función en el siguiente formato:

Definición del objeto de evento de entrada y acceso a él

El formato de entrada más común y estándar de las funciones de Lambda es JSON. En este ejemplo, la función espera una entrada similar a la siguiente:

{
    "order_id": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

Al trabajar con funciones de Lambda en Java 17 o versiones posteriores, puede definir la forma del evento de entrada esperado como un registro de Java. En este ejemplo, definimos un registro dentro de la clase OrderHandler para representar un objeto Order:

public record Order(String orderId, double amount, String item) {}

Este registro coincide con la forma de entrada esperada. Después de definir el registro, puede escribir una firma de controlador que incluya una entrada de JSON que se ajuste a la definición del registro. El tiempo de ejecución de Java deserializa automáticamente este JSON en un objeto Java. Ahora puede acceder a los campos del objeto. Por ejemplo, event.orderId recupera el valor de orderId de la entrada original.

Otros tipos de eventos de entrada

Hay muchos eventos de entrada posibles para las funciones de Lambda en Java:

Acceso y uso del objeto de contexto de Lambda

El objeto de contexto de Lambda contiene información sobre la invocación, la función y el entorno de ejecución. En este ejemplo, el objeto de contexto es de tipo com.amazonaws.services.lambda.runtime.Context y es el segundo argumento de la función del controlador principal.

public String handleRequest(Order event, Context context) {
    ...
}

Si la clase implementa la interfaz RequestHandler o RequestStreamHandler, el objeto de contexto es un argumento obligatorio. De lo contrario, el objeto de contexto es opcional. Para obtener más información sobre las firmas de controlador válidas, consulte Definiciones de clase válidas para los controladores de Java.

Si hace llamadas a otros servicios mediante el AWS SDK, el objeto de contexto es obligatorio en algunas áreas clave. Por ejemplo, para generar registros de funciones para Amazon CloudWatch, puede utilizar el método context.getLogger() a fin de obtener un objeto LambdaLogger para el registro. En este ejemplo, podemos usar el registrador para registrar un mensaje de error si el procesamiento falla por cualquier motivo:

context.getLogger().log("Failed to process order: " + e.getMessage());

Además del registro, también puede usar el objeto de contexto para supervisar las funciones. Para obtener más información acerca del objeto de contexto, consulte Uso del objeto de contexto Lambda para recuperar información de funciones de Java.

Uso de la versión 2 de AWS SDK para Java en el controlador

A menudo, utilizará las funciones de Lambda para interactuar con otros recursos de AWS o actualizarlos. La forma más sencilla de interactuar con estos recursos es utilizar la versión 2 de AWS SDK para Java.

Para agregar dependencias del SDK a su función, agréguelas al archivo build.gradle para Gradle o al archivo pom.xml para Maven. Le recomendamos que solo agregue las bibliotecas que necesite para su función. En el código de ejemplo anterior, utilizamos la biblioteca software.amazon.awssdk.services.s3. En Gradle, puede agregar esta dependencia agregando la siguiente línea en la sección de dependencias de build.gradle:

implementation 'software.amazon.awssdk:s3:2.28.29'

En Maven, agregue las siguientes líneas en la sección <dependencies> de pom.xml:

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.28.29</version>
    </dependency>

Luego, importe las dependencias directamente en la clase de Java:

import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

El código de ejemplo inicializa un cliente de Amazon S3 de la siguiente manera:

private static final S3Client S3_CLIENT = S3Client.builder().build();

En este ejemplo, inicializamos el cliente de Amazon S3 fuera de la función del controlador principal para evitar tener que inicializarlo cada vez que invocamos nuestra función. Después de inicializar el cliente del SDK, podrá usarlo para interactuar con otros servicios de AWS. El código de ejemplo llama a la API PutObject de Amazon S3 de la siguiente manera:

PutObjectRequest putObjectRequest = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

// Convert the receipt content to bytes and upload to S3
S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));

Acceso a las variables de entorno

En el código del controlador, puede hacer referencia a cualquier variable de entorno mediante el método System.getenv(). En este ejemplo, hacemos referencia a la variable de entorno RECEIPT_BUCKET definida mediante la siguiente línea de código:

String bucketName = System.getenv("RECEIPT_BUCKET");
if (bucketName == null || bucketName.isEmpty()) {
    throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
}

Uso del estado global

Lambda ejecuta su código estático y el constructor de clases durante la fase de inicialización antes de invocar la función por primera vez. Los recursos que se crean durante la inicialización permanecen en la memoria entre las invocaciones, por lo que evita tener que crearlos cada vez que invoca la función.

En el código de ejemplo, el código de inicialización del cliente S3 está fuera del método del controlador principal. El tiempo de ejecución inicializa el cliente antes de que la función gestione su primer evento, lo que puede provocar tiempos de procesamiento más largos. Los eventos posteriores son mucho más rápidos porque Lambda no necesita volver a inicializar el cliente.

Prácticas recomendadas de codificación para las funciones de Lambda

Siga las directrices de la siguiente lista para utilizar las prácticas recomendadas de codificación al crear sus funciones de Lambda: