Cómo crear un texto destacado de Java

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

¿Qué es un texto destacado de Java?

Apigee proporciona una variedad de políticas que abordan requisitos comunes de administración de API, como la seguridad, la transformación de datos, la administración del tráfico, entre otras.

Sin embargo, hay algunos casos en los que tu API requiere un comportamiento personalizado que no se implemente en una política estándar. En estos casos, Apigee proporciona varias opciones que te permiten codificar o crear secuencias de comandos de comportamientos de la API personalizados. Un enfoque consiste en implementar el comportamiento deseado en Java.

Las versiones de Java compatibles incluyen Oracle JDK 11 y OpenJDK 11.

¿Cómo uso el código Java en un proxy?

Una política de texto destacado de Java te permite llamar a un código de Java desde el flujo de un proxy en ejecución. Tu código de Java debe implementar ciertas interfaces de Java específicas de Apigee que permitan que el código interactúe con el proxy en ejecución. Por ejemplo, existen métodos de Java para obtener y configurar encabezados, parámetros de búsqueda, variables de flujo y otras entidades dentro del contexto de flujo actual del proxy.

¿Cuándo debo usar un texto destacado de Java?

Analicemos situaciones en las que los textos destacados de Java son útiles y situaciones en las que debes considerar otros enfoques.

Primero, considera enfoques alternativos

Antes de usar un texto destacado de Java, ten en cuenta que puede haber enfoques alternativos que puedes usar en su lugar. Por ejemplo:

Para operaciones ligeras, como las llamadas a la API HTTP a servicios remotos, considera usar la política ServiceCallout. Consulta Política de texto destacado de servicio.
Para interacciones relativamente simples con el contenido del mensaje, como modificar o extraer encabezados HTTP, parámetros o contenido de mensajes, puedes usar políticas de Python o JavaScript.

Qué puedes hacer en el código de Java

Un texto destacado de Java admite estas operaciones básicas:

Examinar o manipular mensajes de solicitud o respuesta
Obtener y configurar variables de flujo. Puedes usar métodos de Java para acceder a las variables de flujo de Apigee. Si deseas acceder a la información del mapa de clave-valor (KVM), usa una política de KVM, asigna valores de KVM a las variables de flujo y, luego, podrás acceder a las variables de flujo desde el texto destacado de Java.
Llama a servicios externos
Generar fallas
Manipula mensajes de error y códigos de estado

Qué no puedes hacer en el código de Java

La mayoría de las llamadas al sistema no están permitidas. No puedes hacer lo siguiente:

Realizar operaciones de lectura ni escritura en el sistema de archivos internos. Esto significa que no puedes usar ninguno de los paquetes de Java para leer o escribir en sistemas de archivos internos. Sin embargo, puedes realizar llamadas remotas externas.
Obtener información sobre el proceso actual, la lista de procesos o el uso de CPU o memoria en la máquina.
Accede al código fuente en expressions-1.0.0.jar y message-flow-1.0.0.jar.

Si bien algunas llamadas pueden funcionar, no son compatibles y están sujetas a la inhabilitación activa en cualquier momento. Evita hacer esas llamadas en tu código.

No uses bibliotecas de Java incluidas en Apigee o no dependas de ellas. Esas bibliotecas son solo para la funcionalidad de productos de Apigee y no hay garantía de que una biblioteca esté disponible entre un lanzamiento y el siguiente. Si usas esas bibliotecas, úsalas solo en demostraciones sin producción.

Texto destacado de Hello para Java

Veamos un ejemplo básico de texto destacado de Java de Hello World. En este ejemplo, creamos un proxy simple con un texto destacado de Java que muestra una respuesta “hello world”. El proxy puede mostrar una de las dos respuestas posibles:

Si pasas un encabezado "nombre de usuario" con un valor de "nombre", el proxy muestra lo siguiente:
```
Hello, <name>!
```
Si omites el encabezado, el proxy solo muestra lo siguiente:
```
"Hello, Guest!"
```

Descarga el proyecto inicial

A fin de simplificar el proceso, tenemos un proyecto básico preparado para ti en GitHub en el repositorio api-platform-samples de Apigee.

Descarga o clona api-platform-samples en tu sistema. Si ya tienes api-platform-samples en tu sistema, realiza una pull para asegurarte de tener la versión más reciente.
En un editor de código o terminal de tu elección, ve al proyecto api-platform-samples/doc-samples/java-hello.

Escribe el código de Java

Abre el archivo fuente de Java: java-hello/callout/src/main/java/HelloJava.java. Este archivo es una versión básica de la clase principal de Java que implementaremos. Los paquetes importados son necesarios para el código de texto destacado de Java de Apigee. Estas clases proporcionan métodos que te permiten acceder al contexto de ejecución del proxy. En breve, explicaremos los pasos para compilar e implementar este código.

package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;

public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

                try {

                        // Your code here.

            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}

Reemplaza la línea comentada // Your code here por el siguiente código:
```
String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
```
Nota: Nota: El objeto MessageContext te permite acceder a entidades dentro del flujo en el que se ejecuta la política de texto destacado de Java. Supongamos que la política de texto destacado de Java está adjunta al flujo de respuesta de extremo del proxy. Con el código anterior, se obtiene el objeto HTTP Message para ese contexto de flujo. A su vez, el objeto Message te da acceso a encabezados, parámetros de búsqueda, contenido del cuerpo y variables de flujo.
Guarda el archivo.

Compila tu código con Maven

Asegúrate de haber instalado Maven:
```
mvn -version
```

Instala las dependencias JAR necesarias en tu repositorio local de Maven con uno de los siguientes métodos:

Agrega el siguiente fragmento al archivo pom.xml para descargar las dependencias JAR necesarias de Artifact Registry:

<repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>

Usa las siguientes llamadas curl para descargar las dependencias JAR necesarias de Artifact Registry:

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar

Ejecuta la siguiente secuencia de comandos java-hello/buildsetup.sh. Esta secuencia de comandos descarga las dependencias JAR necesarias del repositorio de GitHub de Apigee.

cd al directorio java-hello/callout.
Ejecuta Maven:
```
mvn clean package
```
Nota: Si recibes un error de Maven, asegúrate de estar en el directorio java-hello/callout.
Si lo deseas, verifica que el archivo JAR edge-custom-policy-java-hello.jar se copió en java-hello/apiproxy/resources/java. Esta es la ubicación requerida para los archivos JAR que deseas implementar con un proxy.

Implementa y llama al proxy

Sigue estos pasos para implementar y probar el proxy de API:

Cambia al directorio java-hello.

Comprime el paquete de proxy de API:

zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

La forma más sencilla de implementar el proxy es empaquetarlo en un archivo ZIP y subir el paquete de proxy a un entorno en tu organización de Apigee. Consulta Crea un proxy de API. Asegúrese de usar la opción Subir paquete de proxy. Consulta también Sugerencias y trucos para subir proxies de API en un paquete de proxy en la comunidad de Apigee.
Cuando el proxy se implemente, intenta llamarlo:
```
curl  https://$HOSTNAME/java-hello -H "username:Will"
```
Lo que muestra “Hello, Will!”

Acerca del proxy

Examinemos con rapidez las políticas que se usan en este proxy. Presta atención al lugar en el que se ubican las políticas en el flujo del proxy y los motivos de esa ubicación.

La política de asignación de mensajes

Se adjunta una política de asignación de mensajes al flujo de solicitud de ProxyEndpoint. Copia el encabezado del nombre de usuario de la solicitud y lo asigna a la respuesta. Esta operación permite que la política de texto destacado de Java, que se adjunta al flujo de respuesta, acceda al encabezado del nombre de usuario y compile un cuerpo de respuesta personalizado con el valor de ese encabezado.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

La política de texto destacado de Java

La política de texto destacado de Java se adjunta al flujo de respuesta. Esto se debe a que el código personalizado de Java realiza cambios en los encabezados y el mensaje de la respuesta. El elemento ClassName de la política especifica la clase principal que ejecuta la política. El elemento ResourceURL es el nombre del archivo JAR que compilaste y agregaste al directorio resources/java del proxy.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

Qué necesitas saber sobre el texto destacado de Java

A continuación, se indican los aspectos importantes que se deben tener en cuenta sobre la implementación de un texto destacado de Java:

Importa clases desde los paquetes com.apigee.flow.execution y com.apigee.flow.message. Estos paquetes deben incluirse en el archivo JAR que se empaqueta e implementa. Puedes subir tu JAR de Java con el editor de proxy de la IU de administración o puedes incluirlo en el directorio /resources/java en los proxies de API que desarrollas de manera local.
Implementa la interfaz de ejecución. Cualquier código de Java que se ejecute dentro de un proxy de API debe implementar la ejecución.
Una política de texto destacado de Java no contiene código real, En cambio, una política de texto destacado de Java hace referencia a un “recurso” de Java, que debes empaquetar en un JAR.
Nombres de paquete que se deben evitar: No uses io.apigee ni com.apigee como nombres de paquete en los textos destacados de Java. Esos nombres están reservados y son usados por otros módulos de Apigee.
Si tu texto destacado de Java depende de bibliotecas de terceros adicionales empaquetadas como archivos JAR independientes, ubica también esos archivos JAR en el directorio /resources/java para asegurarte de que se carguen de forma correcta en el entorno de ejecución.
Si hay varios JAR, solo agrégalos como recursos adicionales. No necesitas modificar la configuración de la política para hacer referencia a archivos JAR adicionales. Ubicarlos en /resources/java es suficiente.
Para obtener información sobre cómo subir JAR de Java, consulta Archivos de recursos.