com.adobe.idp.dsc
Interface InvocationRequest

public interface InvocationRequest

Represents a normalized message that is sent by a client application to invoke a specific operation of a LiveCycle service that is deployed in the service container. An InvocationRequest defines the service name, the operation name, the operation parameters, and whether the operation is executed synchronously or asynchronously.

For information about sending an invocation request to a LiveCycle service, see Invoking LiveCycle Services.

Method Summary

java.lang.String	getEndPointURI() Retrieves the endpoint URI used by this invocation request.
java.lang.Object	getInputParameter(java.lang.String parameterName) Retrieves the value of the specified parameter.
java.util.Map	getInputParameters() Retrieves input parameters that are specified in the invocation request as a java.util.map object.
Context	getInvocationContext() Retrieves the com.adobe.idp.Context that is used in this invocation request.
java.lang.String	getInvocationId() Returns the identifier value of this invocation request.
java.lang.String	getOperationName() Retrieves the name of the service operation specified by this invocation request.
java.lang.Object	getProperty(java.lang.String propertyName) Retrieves the value of an invocation request property.
java.lang.Object	getProperty(java.lang.String propertyName, java.lang.Object defaultValue) Retrieves an invocation request property.
java.lang.String	getServiceExplicitVersion() Retrieves the explicit version of the LiveCycle service.
java.lang.String	getServiceName() Retrieves the LiveCycle service name that is specified in this invocation request.
java.lang.String	getServiceOriginalVersion() Retrieves the original verion of the LiveCycle service that is specified in this invocation request.
ServiceConfiguration	getTargetServiceConfiguration() Returns the target service configuration that was resolved based on the service identifier and versioning information specified in this invocation request.
boolean	isSynchronous() Determines whether the operation is going to be executed synchronously or asynchronously.
java.lang.Object	removeProperty(java.lang.String propertyName) Removes an associated property from the invocation request.
void	setClientParameters(java.util.Map parameters) Sets parameter values passed to the LiveCycle service.
void	setEndPointURI(java.lang.String endpointURI) Specifies a valid endpoint URI, which is an address that is used to reference a LiveCycle service either locally or remotely.
void	setFaultCallback(FaultCallBackInfo info) Sets a fault callback.
void	setInputParameter(java.lang.String parameterName, java.lang.Object value) Specifies an input parameter and its value.
void	setInputParameters(java.util.Map inputParameters) Copies all the values from the specified map to this invocation request's input parameters.
void	setOperationName(java.lang.String operationName) Specifies the service operation name that the client application wants to invoke.
void	setProperty(java.lang.String propertyName, java.lang.Object value) Specifies an invocation request property.
void	setResponseCallback(ResponseCallBackInfo info) Sets a response callback.
void	setServiceExplicitVersion(java.lang.String explicitVersion) Specifies the explicit version of the LiveCycle service that this invocation request is bound to.
void	setServiceName(java.lang.String serviceName) Specifies the service name that the client application wants to interact with.
void	setServiceOriginalVersion(java.lang.String originalVersion) Specifies the original version of the LiveCycle service.
void	setSynchronous(boolean synchronous) Specifies if the operation is excuted synchronously or asynchronously.

Method Detail

getServiceName

java.lang.String getServiceName()

Retrieves the LiveCycle service name that is specified in this invocation request. The service name is specified as a parameter value to the ServiceClientFactory object's createInvocationRequest method.

Returns:

The service name that is specified in this invocation request.

See Also:

setServiceName(), createInvocationRequest()

setServiceName

void setServiceName(java.lang.String serviceName)

Specifies the service name that the client application wants to interact with. The name of the service has to match the one defined in the LiveCycle Service Registry. The service name is specified as a parameter value to the ServiceClientFactory object's createInvocationRequest method. .

Parameters:

serviceName - The service name.

See Also:

InvocationRequest.getServiceName(), InvocationRequest.getEndPointURI(), setEndPointURI(), createInvocationRequest()

getOperationName

java.lang.String getOperationName()

Retrieves the name of the service operation specified by this invocation request. The operation name is specified as a parameter value to the ServiceClientFactory object's createInvocationRequest method.

Returns:

The name of the service operation that was specified in the invocation request.

See Also:

InvocationRequest.setOperationName(String), createInvocationRequest()

setOperationName

void setOperationName(java.lang.String operationName)

Specifies the service operation name that the client application wants to invoke. The name must match the service definition specified in the LiveCycle Service Registry. You can call this method to replace an existing operation name. The operation name is specified as a parameter value to the ServiceClientFactory object's createInvocationRequest method.

Parameters:

operationName - The name of the LiveCycle service operation.

See Also:

InvocationRequest.getOperationName(), InvocationRequest.getEndPointURI(), setServiceName(), setEndPointURI(), createInvocationRequest()

setEndPointURI

void setEndPointURI(java.lang.String endpointURI)

Specifies a valid endpoint URI, which is an address that is used to reference a LiveCycle service either locally or remotely. Endpoint URIs are usually in one of the following form, although a provider implementation can introduce its own scheme:

scheme://[host][:port]/[endpoint name]/[address]?[params]

For example: ejb://localhost:1099/SomeService?method=remoteMethod.

The transport provider scheme must always be specified in an endpoint URI. The host and port value in the endpoint URI is used by providers that support a socket-based protocol, such as tcp, http, and udp. For example: http://localhost:8080.

The name of an endpoint URI is used to refer to a pre-configured end point. If both host/port and the endpoint name are set, the endpoint information is used. The address value of an endpoint URI is used by providers that support addresses such as file path. For example: file:///C:/temp/files.

The params value of an endpoint URI is used to specify properties that are associated with the Transport Provider. For example: file:///inbound/myfiles?filterPattern="*.txt,*.xml".

Note the invocation request end point specification overrides the service name specification.

Parameters:

endpointURI - The invocation request endpoint URI that references a LiveCycle service.

See Also:

InvocationRequest.getEndPointURI(), InvocationRequest.getServiceName(), InvocationRequest.setServiceName(String)

getEndPointURI

java.lang.String getEndPointURI()

Retrieves the endpoint URI used by this invocation request.

Returns:

A string value that represents the endpoint URI used by this invocation request.

See Also:

InvocationRequest.getServiceName(), InvocationRequest.setServiceName(String), InvocationRequest.setEndPointURI(String)

getServiceExplicitVersion

java.lang.String getServiceExplicitVersion()

Retrieves the explicit version of the LiveCycle service.

Returns:

A string value that represents the explicit version of a LiveCycle service.

See Also:

InvocationRequest.setServiceExplicitVersion(String)

setServiceExplicitVersion

void setServiceExplicitVersion(java.lang.String explicitVersion)

Specifies the explicit version of the LiveCycle service that this invocation request is bound to. The version of the invoking service is handled in the following manner:

• No version specification: If a client application does not specify any version information the invocation request is routed to the latest version (Head) of the service.
• Explicit version specification: If the client application specifies the explicit version to bind to for a Service, then the invocation request is routed to that specific version.
• Original version specification: 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 specifid in the Original version
• If both explicit version and original version is specified, the explicit version overrides the original version.

Parameters:

explicitVersion - The explicit version of the LiveCycle service.

See Also:

InvocationRequest.setServiceOriginalVersion(String), InvocationRequest.getServiceExplicitVersion()

getServiceOriginalVersion

java.lang.String getServiceOriginalVersion()

Retrieves the original verion of the LiveCycle service that is specified in this invocation request.

Returns:

The original version of the LiveCycle service.

See Also:

InvocationRequest.setServiceOriginalVersion(String), InvocationRequest.setServiceExplicitVersion(String), InvocationRequest.getServiceExplicitVersion()

setServiceOriginalVersion

void setServiceOriginalVersion(java.lang.String originalVersion)

Specifies the original version of the LiveCycle service. The invocation request is routed to the latest version of the LiveCycle service that is compatible with the specified version. The version of the invoking service is handled in the following manner:

• Explicit version specification: If the client application specifies the explicit version to bind to for a Service, then the invocation request is routed to that specific version.
• Original version specification: 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 specifid in the Original version
• If both explicit version and original version is specified, the explicit version overrides the original version.

Parameters:

originalVersion - The service original version.

See Also:

setServiceExplicitVersion(), getServiceOriginalVersion()

getInvocationContext

Context getInvocationContext()

Retrieves the com.adobe.idp.Context that is used in this invocation request.

Returns:

the com.adobe.idp.Context that is used in this invocation request.

getInputParameters

java.util.Map getInputParameters()

Retrieves input parameters that are specified in the invocation request as a java.util.map object. Consider the following invocation request that is sent to the Encryption service to remove password-based encryption from a PDF document:

Map params = new HashMap();
FileInputStream fileInputStream = new FileInputStream("C:\\MapPasswordEncrypt.pdf");
Document inDoc = new Document ;(fileInputStream);
String myPassword = "password2";
params.put("inDocument", inDoc);
params.put("password", myPassword);
Properties connectProps = new Properties();
connectProps.put(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://localhost:1099");
connectProps.put(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
connectProps.put(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE);
ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectProps);
InvocationRequest request = myFactory.createInvocationRequest("EncryptionService", "removePDFPasswordSecurity",params,true);


In this situation, this method returns a java.util.map object that contains a com.adobe.idp.Document object that was passed to the inDocument parameter and a string value that was passed to the to the password parameter. For information about passing parameter values as part of an invocation request, see Invoking LiveCycle Services.

Returns:

A java.util.map object that contains input parameters.

See Also:

setInputParameters()

setInputParameters

void setInputParameters(java.util.Map inputParameters)

Copies all the values from the specified map to this invocation request's input parameters. Operation parameters can be any serializable object, including a com.adobe.idp.Document object, a java.util.Map object, or a list of Document objects.

Parameters:

inputParameters - Copies all of the key pair values from this map object to this invocation request's input parameters. Exisiting key pair values are overwritten by the ones specified in the map object.

getInputParameter

java.lang.Object getInputParameter(java.lang.String parameterName)

Retrieves the value of the specified parameter. Operation parameters can be any serializable object, including a com.adobe.idp.Document object, a Map object, or a list of Document objects.

Parameters:

parameterName - The name of the input parameter.

Returns:

The value of the specified input parameter.

See Also:

InvocationRequest.setInputParameter(String, Object)

setInputParameter

void setInputParameter(java.lang.String parameterName,
                       java.lang.Object value)

Specifies an input parameter and its value.

Parameters:

parameterName - The name of the specified input parameter.

value - The value of the specified input parameter.

See Also:

InvocationRequest.getInputParameter(String)

getProperty

java.lang.Object getProperty(java.lang.String propertyName)

Retrieves the value of an invocation request property.

Parameters:

propertyName - The name of the invocation request property.

Returns:

The value of the specified invocation request property. If the property does not exist, then a null value is returned.

See Also:

InvocationRequest.setProperty(String, Object)

getProperty

java.lang.Object getProperty(java.lang.String propertyName,
                             java.lang.Object defaultValue)

Retrieves an invocation request property. Properties can be arbitrary. For example, you can pass custom metadata with your request.

Parameters:

propertyName - The name of the property.

defaultValue - A default value if the property does not exist in the invocation request.

Returns:

The property value or the default value if the property does not exist.

See Also:

InvocationRequest.setProperty(String, Object)

setProperty

void setProperty(java.lang.String propertyName,
                 java.lang.Object value)

Specifies an invocation request property. Properties can be arbitrary. For example, you can pass custom metadata with your invocation request.

Parameters:

propertyName - The name of the invocation request property.

value - The value of the specified invocation request property.

See Also:

InvocationRequest.getProperty(String)

removeProperty

java.lang.Object removeProperty(java.lang.String propertyName)

Removes an associated property from the invocation request.

Parameters:

propertyName - The name of the property to remove.

Returns:

The value of the removed property.

See Also:

InvocationRequest.getProperty(String), InvocationRequest.setProperty(String, Object)

isSynchronous

boolean isSynchronous()

Determines whether the operation is going to be executed synchronously or asynchronously.

Returns:

true if the operation is executed synchronously, otherwise false.

See Also:

InvocationRequest.isSynchronous()

setSynchronous

void setSynchronous(boolean synchronous)

Specifies if the operation is excuted synchronously or asynchronously. A synchronous invocation request is blocked until the LiveCycle service finishes processing the invocation request and returns the result back to the caller.

Parameters:

synchronous - Set to true if the invocation request is a synchronous request. Set to false if the invocation request is an asynchronous request.

See Also:

InvocationRequest.isSynchronous()

setResponseCallback

void setResponseCallback(ResponseCallBackInfo info)

Sets a response callback.

setFaultCallback

void setFaultCallback(FaultCallBackInfo info)

Sets a fault callback.

setClientParameters

void setClientParameters(java.util.Map parameters)

Sets parameter values passed to the LiveCycle service.

Parameters:

parameters - A map of parameter values.

getInvocationId

java.lang.String getInvocationId()

Returns the identifier value of this invocation request.

Returns:

The identifier value of this invocation request.

getTargetServiceConfiguration

ServiceConfiguration getTargetServiceConfiguration()

Returns the target service configuration that was resolved based on the service identifier and versioning information specified in this invocation request.

Returns:

A ServiceConfiguration object that contains service configuration information.