Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Use Java to customize an API

Apigee Edge provides a range of out-of-the-box policies that address common API management requirements such as security, data transformation, traffic management, and others.

However, there are some cases where your API requires custom behavior that is not implemented in a standard policy. In these cases, Apigee provides several options that enable developers to script or code customized API behavior. One approach is to implement the desired behavior in Java.

This cookbook demonstrates how to create a simple JavaCallout policy that executes custom Java code within the context of a proxy flow.

For the supported versions of Java, see Supported software.

What does the sample code do?

A proxy calls a target service that returns a simple JSON response. The Java Callout policy is placed on the target response flow. The Java code converts the headers and content of the response to uppercase letters. It's a simple example; however, it illustrates how to get custom Java code working in the context of an API proxy on Edge.

Try the sample code

Follow these steps to deploy the sample proxy to Edge and execute it:

  1. Download or clone the Apigee sample repository from GitHub.
  2. Follow the one-time setup steps (if you have not done so previously).
  3. cd to api-platform-samples/doc-samples/java-cookbook.
  4. Execute ./deploy.sh.
  5. Execute ./invoke.sh.

The response looks something like this:

< HTTP/1.1 200 OK
< Date: Tue, 09 May 2017 20:31:08 GMT
< Content-Type: APPLICATION/JSON; CHARSET=UTF-8
< Content-Length: 68
< Connection: keep-alive
< Access-Control-Allow-Origin: *
< ETag: W/"44-RA5ERT/MMLIK54NVBWBSZG"
< X-Powered-By: APIGEE
< Server: Apigee Router
<
* Curl_http_done: called premature == 0
* Connection #0 to host willwitman-test.apigee.net left intact
{"FIRSTNAME":"JOHN","LASTNAME":"DOE","CITY":"SAN JOSE","STATE":"CA"}

Proxy flow

This is a shot of the trace tool showing the flow of the proxy:

 

 

Proxy structure

This is the structure of the proxy. Note that it includes a JAR file in the apiproxy/resources/java directory. The JAR is required. We provide it for the sample, but if you are doing custom work, you need to build it yourself and copy it into this location.

java-cookbook

    apiproxy
        java-cookbook.xml
    policies
        responseUppercase.xml
    proxies
        default.xml
    resources
        java
            ResponseUppercase.jar
    targets
        default.xml

About the Java code

The Java Callout policy runs the following Java code, which converts response headers and the response body to uppercase. Note that the program uses Apigee-specific packages. These packages provide objects and methods that you can use to interact directly with the proxy flow. Methods exist that let you get and set flow variables, headers, message content, and more.

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;

import java.util.Set; 

public class ResponseUppercase implements Execution{
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        try {
            Set headers = messageContext.getMessage().getHeaderNames();
            for (String header : headers) {
                String h = messageContext.getMessage().getHeader(header).toUpperCase();
                messageContext.getMessage().setHeader(header, h);
            }
            String content = messageContext.getMessage().getContent();
            messageContext.getMessage().setContent(content.toUpperCase());
            return ExecutionResult.SUCCESS;
        } catch (Exception e) {
                return ExecutionResult.ABORT;
        }
    }
}

What you can do in Java code

Java callout code can:

  • examine or manipulate any aspect of the request or response message
  • raise faults
  • set or retrieve context variables

The most important things to remember about the Java implementation are:

  • Imports classes from the com.apigee.flow.execution and com.apigee.flow.message packages. These packages must be included in the JAR file that is packaged and deployed. For information on uploading Java JARs, see Resource files and Java Callout policy. In the cookbook sample download, you can find these packages in doc-samples/java-cookbook/lib.
  • Implements Execution. Any Java code that is executed within an API proxy must implement Execution. 

What you cannot do in Java code

  • Most system calls are disallowed. For example, you cannot perform local network I/O, or filesystem reads or writes. The callout cannot get information about the current process, the process list, or CPU/memory utilization on the machine. Although some such calls may be functional, they are unsupported and liable to be actively disabled at any time. For forward compatibility, you should avoid making such calls in your code.
  • Reliance on Java libraries that are included with Apigee Edge is not supported, though Apigee Java Callout samples may use them purely to make them work as non-production illustrations. Those libraries are for Edge product functionality only, and there's no guarantee that a library will be available from release to release.

Examine the sample proxy

We leave it to you to open the proxy and examine the files. Here is the Java Callout policy. Note how it references the class that the callout executes and the JAR file. All Java Callout policies follow this pattern. See also Java Callout policy.

<JavaCallout name="responseUppercase">         
    <ClassName>com.apigeesample.ResponseUppercase</ClassName>         
    <ResourceURL>java://ResponseUppercase.jar</ResourceURL> 
</JavaCallout>

Get Help

For help, see Apigee Customer Support.

Help or comments?