Send Docs Feedback

Java Callout policy


Enables you to use Java to implement custom behavior that is not included out-of-the-box by Apigee policies.


This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
    PostFlow Flow PreFlow PostFlow Flow PreFlow    


<JavaCallout name="cityLookUp">

The cityLookUp JavaCallout policy is delivered in the java-cookbook repository, along with other samples that support using Java to customize an API.

For java-cookbook sample usage details, see Use Java to customize an API.

Element reference

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

<JavaCallout name="MyJavaCalloutPolicy">

<JavaCallout> attributes

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

The following attributes are common to all policy parent elements.

Attribute Description Default Presence

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>


If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String


<ResourceURL> element

This element specifies the Java JAR file that will execute in the API flow. 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 in Resource files. Your code can use the objects, methods, and properties of the JavaScript object model.

<JavaCallout name="MyJavaCalloutPolicy">
Default: None
Presence: Required
Type: String

<ClassName> element

Specifies the name of the Java class that executes the callout.

<JavaCallout name="MyJavaCalloutPolicy">
Default: N/A
Presence: Required
Type: String

Error codes

The default format for error codes returned by policies is:

  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]

The JavaCallout policy type defines the following error codes:

Error Code Message
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class {0}
NoResourceForURL Could not locate a resource with URL {0}
NoAppropriateConstructor No appropriate constructor found in JavaCallout class {0}
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource {0} - {1}
JavaClassDefinitionNotFound Failed to load java class {0} definition


Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Usage notes

  • For lightweight operations, such as API calls to remote services, we recommend using the ServiceCallout policy. See Service Callout policy.
  • For relatively simple interactions with message content, such as modifying or extracting HTTP headers, parameters, or message content, you can use JavaScript or Python languages.
  • Package names: Don't use 'io.apigee' or 'com.apigee' as package names in Java Callouts. Those are reserved and used by other Apigee modules.
  • Place the JAR in an API proxy under /resources/java. If your JavaCallout 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, see Resource files.
  • System calls, for example network I/O, filesystem read/writes, current user info, process list, and CPU/memory utilization are not permitted by the security model. 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 JavaCallout.

Related topics

For samples that support using Java to customize an API, see our java-cookbook repository.

For java-cookbook sample usage details, see Use Java to customize an API.

To start writing Java for Apigee Edge, see our JavaCallout Javadocs.


Help or comments?