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.

Java Callout policy

What

Enables you to use Java to implement custom behavior that is not included 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.apigeesample.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.

You can add a <Property> element in configuration, then retrieve the element's value with Java at runtime.

Use the element's name attribute to specify the name with which to access the property from Java code. The <Property> element's value (the value between the opening and closing tags) is the value that will be received by the Java code.

In Java, you retrieve the policy property value by accessing it as a property of the Properties object, as in the following:

  • Configure the property. Here, the property value is the variable name response.status.code.
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
        <DisplayName>JavaCallout</DisplayName>
        <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
        <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
        <Properties>
            <Property name="source">response.status.code</Property>
        </Properties>
    </Javascript>
  • Retrieve the property with Java.
    public class MyJavaCallout implements Execution{
        public MyJavaCallout(Map<string, string> props){
            
    	    // Extract property values from map.
        }
        ...
    }

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" enabled="true" continueOnError="false" async="false" >

The following attributes are common to all policy parent elements.

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.

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

N/A Required
continueOnError

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
enabled

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
async

This attribute is deprecated.

false Deprecated

<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>
Default:

N/A

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

Presence: Optional
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

<Property> element

Specifies a property you can access from Java code at runtime.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Default: None
Presence: Optional
Type: String

Attributes

Attribute Description Default Presence
name

Specifies the name of the property.

N/A Required.

Example

 

<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">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Default: None
Presence: Required
Type: String

Error reference

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Fault handling.

Runtime errors

These errors can occur when the policy executes.

Error name Fault string HTTP status Occurs when
ExecutionError Failed to execute JavaCallout. [policy_name] 500 See fault string.

 

Deployment errors

These errors can occur when the policy executes.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

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

Variables set (Learn more) Where Example
[prefix].[policy_name].failed [prefix]: javacallout
[policy_name]: The name of the policy to check.
javacallout.JC-GetUserData.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name Matches "ExecutionError"

Example error response

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

Example fault rule

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

Schemas

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

Usage notes

  • 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. Those libraries are for Edge product functionality only, and there's no guarantee that a library will be available from release to release.
  • A Java Callout policy contains no actual code. Instead, a Java Callout 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.
  • Place the JAR in an API proxy under /resources/java. If your Java Callout 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.
  • 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.
  • 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.

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?