This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The JavaCallout policy enables you to use Java to implement custom behavior that is not included out-of-the-box by Apigee policies. In your Java code, you can access message properties (headers, query parameters, content) and flow variables in the proxy flow. If you're just getting started with this policy, seeHow to create a Java callout.

Supported Java versions include: Oracle JDK 11 and OpenJDK 11

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

When

For guidelines, see "When should I use JavaCallout?" inHow to create a Java callout.

About

The JavaCallout policy lets you get and set flow variables, execute custom logic and perform error handling, extract data from requests or responses and more. This policy allows you to implement custom behavior that is not covered by any other standard Apigee policies.

Samples

Element reference

The element reference describes the elements and attributes of the JavaCallout policy.

<JavaCalloutname="MyJavaCalloutPolicy"><ClassName>com.example.mypolicy.MyJavaCallout</ClassName><ResourceURL>java://MyJavaCallout.jar</ResourceURL></JavaCallout>

<JavaCallout> attributes

<JavaCalloutname="MyJavaCalloutPolicy"enabled="true"continueOnError="false"async="false">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to thename attribute to label the policy in themanagement UI proxy editor with a different, natural-language name.

<DisplayName>PolicyDisplayName</DisplayName>

<ClassName> element

Specifies the name of the Java class that executes when the JavaCallout policy runs. The class must be included in the JAR file specified by the<ResourceURL>. See alsoHow to create a Java callout.

<JavaCalloutname="MyJavaCalloutPolicy"><ResourceURL>java://MyJavaCallout.jar</ResourceURL><ClassName>com.example.mypolicy.MyJavaCallout</ClassName></JavaCallout>

<Properties> element

Adds new properties that you can access from Java code at runtime.

<Properties><Propertyname="propName">propertyValue</Property></Properties>

<Property> element

Specifies a property you can access from Java code at runtime. You must specify a literal string value for each property; you cannot reference flow variables in this element. For a working example that uses properties, seeHow to use properties in a JavaCallout policy.

<Properties><Propertyname="propName">propertyValue</Property></Properties>

Attributes

<ResourceURL> element

This element specifies the Java JAR file that will execute when the JavaCallout policy runs.

You can store this file at the API proxy scope (under/apiproxy/resources/java in the API proxy bundle or in the Scripts section of the API proxy editor's Navigator pane), or at the organization or environment scopes for reuse across multiple API proxies, as described inResource files.

<JavaCalloutname="MyJavaCalloutPolicy"><ResourceURL>java://MyJavaCallout.jar</ResourceURL><ClassName>com.example.mypolicy.MyJavaCallout</ClassName></JavaCallout>

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, seeWhat you need to know about policy errors andHandling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Fault variables

These variables are set when this policy triggers an error. For more information, seeWhat you need to know about policy errors.

Example error response

{"fault":{"faultstring":"Failed to execute JavaCallout. [policy_name]","detail":{"errorcode":"javacallout.ExecutionError"}}}

Example fault rule

<FaultRulename="JavaCalloutFailed"><Step><Name>AM-JavaCalloutError</Name></Step><Condition>(fault.nameMatches"ExecutionError")</Condition></FaultRule>

Schemas

Compiling and deploying

For details on how to compile your custom Java code and deploy it with a proxy, seeHow to create a Java callout.

Restrictions

Below are restrictions that you need to consider when writing Java callout code:

• Most system calls are disallowed. For example, you cannot make internal file system reads or writes.
• Access to the network via sockets. Apigee restricts access to sitelocal, anylocal, loopback, and linklocal addresses.
• 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 is not supported. Those libraries are for Apigee product functionality only, and there's no guarantee that a library will be available from release to release.
• Don't useio.apigee orcom.apigee as package names in Java Callouts. Those names are reserved and used by other Apigee modules.

Packaging

Place the JAR in an API proxy under/resources/java. If your JavaCallout code relies on additional third-party libraries packaged as independent JAR files, then place those JAR files in the/resources/java directory as well to ensure that they are loaded correctly at runtime.

If you are using the management UI to create or modify the proxy, add a new resource and specify an additional dependent JAR file. If there are multiple JARs, simply add them as additional resources. You do not need to modify the policy configuration to refer to additional JAR files. Putting them in/resources/java is sufficient.

For information on uploading Java JARs, seeResource files.

For a detailed example that demonstrates how to package and deploy JavaCallout policies using Maven or javac, seeHow to create a Java callout.

Javadoc

Javadoc for writing Java callout code is includedhere on GitHub. You will need to clone or download the HTML to your system, and then simply open theindex.html file in a browser.

Usage notes and best practices

• When working with multiple JavaCallout policies, consider uploading common JARs asenvironment-scoped resources. This practice is more efficient as compared to packaging the same JARs with multiple proxy bundles when deploying to the same environment.
• Avoid packaging and deploying multiple copies or versions of the same JAR file to an environment. For example, Apigee recommends that you avoid:
  • Deploying the same JAR as part of a proxy bundle and as an environment resource.
  • Deploying one version of a JAR file as an environment resource and another as part of a proxy bundle.

  Having multiple copies of same JAR deployed can cause non-deterministic behavior at runtime because of potential ClassLoader conflicts.

• A JavaCallout policy contains no actual code. Instead, the policy references a Java 'resource' and defines the Step in the API flow where the Java code executes. You can upload your Java JAR through the Management UI proxy editor, or you can include it in the/resources/java directory in API proxies that you develop locally.
• For lightweight operations, such as API calls to remote services, we recommend using the ServiceCallout policy. SeeService Callout policy.
• For relatively simple interactions with message content, such as modifying or extracting HTTP headers, parameters, or message content, Apigee recommends using a JavaScript policy.