Cómo crear un texto destacado de Java

¿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 la API requiere un comportamiento personalizado que no se implementa en una política estándar. En estos casos, Apigee brinda varias opciones que te permiten crear secuencias de comandos o programar código de comportamiento de la API personalizado. Un enfoque consiste en implementar el comportamiento deseado en Java.

Las versiones de Java compatibles incluyen Oracle JDK 7/8 y OpenJDK 7/8.

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

Una política de texto destacado de Java te permite llamar a código Java desde un flujo proxy en ejecución. Tu código Java necesita implementar determinadas interfaces Java específicas de Apigee que permiten 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 consulta, variables de flujo y otras entidades dentro del contexto de flujo actual del proxy.

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

Veamos las 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 llamadas a la API de HTTP a servicios remotos, considera usar la política ServicePostout. 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 lenguajes de Python o JavaScript.

Qué puedes hacer en código Java

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

  • Examinar o manipular mensajes de solicitudes o respuestas
  • Obtener y configurar variables de flujo. Usar métodos de Java para acceder a las variables de flujo de Apigee. Si quieres acceder a la información del mapa de clave-valor (KVM), usa una política de KVM, asigna valores de KVM a variables de flujo y, luego, accede a las variables de flujo desde el texto destacado de Java.
  • Llama a servicios externos
  • Aumento de errores
  • Manipula mensajes de error y códigos de estado

Qué no puedes hacer en el código Java

La mayoría de las llamadas al sistema no están permitidas. No puedes realizar las siguientes acciones:

  • Operaciones de lectura o escritura en el sistema de archivos interno. Esto significa que no puedes usar ninguno de los paquetes de Java para leer y escribir en sistemas de archivos internos. Sin embargo, puedes hacer 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.
  • Acceder al código fuente en ʻexpressions-1.0.0.jar` y `message-flow-1.0.0.jar`.

Si bien es posible que funcionen algunas de esas llamadas, no son compatibles y se inhabilitarán de forma activa en cualquier momento. Evita hacer 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 Java de Hello

Veamos un ejemplo básico de textos destacados de Java de Hello World. En este ejemplo, creamos un proxy simple con una solicitud de oferta de Java que muestra una respuesta de “Hello World”. El proxy puede mostrar una de 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 para principiantes

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

  1. Descarga o clona api-platform-samples en tu sistema.
  2. En una terminal o editor de código de tu elección, ve al proyecto api-platform-samples/doc-samples/java-hello.

Escribe el código de Java

  1. Abre el archivo fuente Java: java-hello/callout/src/main/java/HelloJava.java. Este es una versión preliminar de la clase principal de Java que implementaremos. Los paquetes importados son necesarios para el código destacado de Java de Apigee. Estas clases proporcionan métodos que te permiten acceder al contexto de ejecución del proxy. Repasaremos los pasos para implementar y compilar este código en breve.
    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;
                    }
            }
    
    }
    
  2. 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!");
    }
    
  3. Guarda el archivo.


Compila tu código con Maven

El proyecto está configurado para que puedas compilar con Maven. Si deseas usar javac, incluiremos un ejemplo debajo del ejemplo de Maven.

  1. Asegúrate de tener instalado Maven:

    mvn -version
    
  2. Ejecuta secuencia de comandos java-hello/buildsetup.sh. Esta secuencia de comandos instala las dependencias JAR necesarias en tu repositorio local de Maven.
  3. cd en el directorio java-hello/callout.
  4. Ejecuta Maven:

    mvn clean package
    
  5. Si lo deseas, verifica que el archivo JAR edge-custom-policy-java-hello.jar se copió a java-hello/apiproxy/resources/java. Esta es la ubicación requerida para los archivos JAR que deseas implementar con un proxy.

Compila con javac (opcional)

En la sección anterior, generas el archivo JAR de Java necesario de forma automática con un comando de Maven. Como alternativa, si deseas usar javac para compilar el código, puedes hacer algo similar al siguiente (desde el directorio java-hello). Los archivos JAR necesarios se proporcionan para el directorio java-hello/lib.

  1. cd en api-platform-samples/doc-samples/java-hello.
  2. Asegúrate de tener javac en tu ruta de acceso.

    javac -version
    
  3. Ejecuta el siguiente comando de javac:

    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
    
    Esto crea com/apigeesample/HelloJava.class.
  4. Crea un archivo JAR que contenga la clase compilada en el directorio apiproxy/resources/java. Esta es la ubicación requerida para los archivos JAR que deseas implementar con un proxy. Para ello, ejecuta el siguiente comando en el directorio java-hello (no olvides el punto al final).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
    

Implementa y llama al proxy

Se proporciona una secuencia de comandos de implementación en el directorio ./java-hello. Antes de ejecutarlo, debes realizar una configuración rápida.

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

    El mensaje muestra el mensaje "Hello, Will!

Acerca del proxy

Examinemos rápidamente las políticas que se usan en este proxy. Presta atención a dónde se ubican las políticas en el flujo de proxy y por qué.

La política de asignación de mensajes

Una política de asignación de mensajes se adjunta al flujo de solicitudes de ProxyEndpoint. Copia el encabezado del nombre de usuario de la solicitud y lo asigna a la respuesta. Esta operación permite la política de texto destacado de Java, que se adjunta al flujo de respuesta, para acceder al encabezado del nombre de usuario y crear 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 textos destacados de Java

La política de texto destacado de Java se adjunta al flujo de respuesta. Esto se debe a que el código Java personalizado realiza cambios en los encabezados y el mensaje de 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 creaste 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é necesita saber acerca de los textos destacados 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 se deben incluir en el archivo JAR que se empaqueta y se implementa. Puedes subir tu JAR de Java con el editor de proxy de 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 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 ningún 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 paquetes que se deben evitar: No uses io.apigee ni com.apigee como nombres de paquete en textos destacados de Java. Estos están reservados y usados por otros módulos de Apigee.
  • Si tu texto destacado de Java se basa en bibliotecas de terceros adicionales empaquetadas como archivos JAR independientes, coloca también esos archivos JAR en el directorio /resources/java para asegurarte de que se carguen correctamente 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. Ponerlos en /resources/java es suficiente.
  • Para obtener información adicional sobre cómo subir archivos JAR de Java, consulta Archivos de recursos.