JavaCallout policy icon Java Callout policy

About | Samples | Element reference | Error codes | Schemas | Usage notes | Related topics

What

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

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

<JavaCallout name="cityLookUp">
   <ClassName>com.apigee.CityLookup</ClassName>
   <ResourceURL>java://CityLookup.jar</ResourceURL>
</JavaCallout>

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">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

<JavaCallout> attributes

<JavaCallout name="MyJavaCalloutPolicy">
Attribute Description Default Presence
name

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.

N/A Required

<ResourceURL> element

Specifies the name and location of the main JAR file used to execute the callout. This JAR file contains compiled Java code written to the Java API exposed by the API Platform processing pipeline.  

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Default: N/A
Presence: Required
Type: String

<ClassName> element

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

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
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

Schemas

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.
  • 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.
  • 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?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)