Invoking services using the Invocation API

You can invoke a short-lived or long-lived process using the Invocation API. When you invoke either a short-lived or long-lived process using the Invocation API, you must pass required parameter values by using a java.util.HashMap object. For each parameter to pass to a service, invoke the java.util.HashMap object’s put method and specify the name-value pair that is required by the service in order to perform the specified operation. You must specify the exact name of the parameters that belong to the service operation and a corresponding value.

A long-lived operation can only be invoked asynchronously. When invoking a long-lived process, you get back an identifier value that is used to obtain the status of the long-lived process. To obtain the status of a long-lived process, you must use classes that belong to the com.adobe.idp.jobmanager Java package. For information about these classes, see the LiveCycle ES API References.

When you invoke a service, you can specify the version that you want to invoke. The following choices are available:

No version: If a client application does not specify version information, then the invocation request is routed to the latest version of the service.

Explicit version: If the client application specifies the explicit version, then the invocation request is routed to that specific version. Setting an explicit version enables a client application to request that it is always executed against the version that it knows works (the lowest risk). More often than not, the preferable setting is the originalVersion, whereby client applications can give the service container enough information to ensure that the request is routed to a compatible version.

Original version: If the client application specifies the service's original version, the invocation request is routed to the service with the latest version that is compatible with the specified version. A service version is considered compatible with an inbound request if it has the same major version number as specified in the original version.

To specify the version to invoke, you can call the com.adobe.idp.dsc.InvocationRequest object’s setExplicitVersion(VersionAsString) or setOriginalVersion(VersionAsString) where VersionAsString is a string that combines both the major and minor version numbers separated by a decimal (for example, 1.1). For information about this object, see the LiveCycle ES API References.

Note: This section discusses how to invoke a long-lived process and a short-lived process. For information about these processes, see Understanding processes. Both of these example processes require one input value, named fileName, that specifies the name of the document to use. The value must be a string value that specifies the location of the document that the process uses.