Setting the Execution Context of a Service

Summary of steps
Set the execution context of a service using the Java API

The security of a service can be either enabled or disabled. When disabled, a service operation can be invoked without specifying a user name and password. That is, when setting connection properties that are required to invoke LiveCycle operations, you do not need to specify a user name and corresponding password. (See Setting connection properties).

When the security of a service is enabled, the user who is invoking a service operation must be authenticated and authorized to invoke the service. Otherwise, the service container denies the invocation request. (See Disabling Service Security.)

A service can originate from a process created by using Workbench. By default, the way that each service (that is part of the process) is invoked depends on whether the process is a short-lived process or a long-lived process. For a short-lived process, the user’s context is used to invoke each service that is part of the process (this is known as the execution context). For a long-lived process, a system context is used to invoke each service that is part of the process. For information about long-lived and short-lived processes, see Understanding LiveCycle Processes.

Using the LiveCycle Java API, you can specify the execution context in which each service (that is part of a process) is invoked. This execution context is used regardless of whether the process is a long-lived process or a short-lived process. Three types of execution context exists:

Run-As Invoker: The context of the invoker is used as the execution context for each service that is part of a process.
Run-As System: The system context is used as the execution context for each service that is part of a process. This setting is the current default setting for long-lived processes.
Run-As Named User: A specific LiveCycle user is specified in the configuration. When invoked, all actions performed by the process are performed as if by that user rather than by the user that initially invoked the process.

LiveCycle checks the execution context for authorization on a service operation before an invocation request proceeds. LiveCycle also checks the execution context of a service and changes it to the execution context that is set before proceeding with an invocation request.

LiveCycle performs the following tasks in response to an invocation request:

Checks whether security is disabled for the service, sets the execution context (if set), and lets the invocation request proceed.
Checks whether the service operation has anonymous access enabled (from the component.xml file).
Checks whether the execution context is authorized to invoke the service.

If the execution context for a service is not set, the default behavior is used. For a short-lived process, the identifier of the user who invokes the process is used. For a long-lived process, the system context is used.

Summary of steps

To set the execution context of a service, perform the following tasks:

Include project files.
Create a ServiceRegistryClient API object.
Reference a service.
Set the execution context.

Note: You cannot set the execution context of a service by using web services.

Include project files

Include necessary files in your development project. If you are creating a client application by using Java, include the necessary JAR files.

The following JAR files must be added to your project’s class path:

adobe-livecycle-client.jar
adobe-usermanager-client.jar
commons-codec-1.3.jar
commons-collections-3.1.jar
commons-discovery.jar
commons-logging.jar
adobe-utilities.jar (required if LiveCycle is deployed on JBoss)
jbossall-client.jar (required if LiveCycle is deployed on JBoss)

For information about the location of these JAR files, see Including LiveCycle Java library files.

Create a ServiceRegistryClient API object

Before you can programmatically set the execution context of a service, create a ServiceRegistryClient object.

Reference a service

To set the execution context of a service, the service must be referenced. For example, assume that you want to set the execution content of a service named EncryptDocument. In this situation, you must reference the EncryptDocument service.

Set the execution context

You can set the execution context to Run-As Invoker, Run-As system, or Run-as named user. After the specified execution context is set, it is used when the process is invoked. For example, assume that you set the execution context for the EncryptDocument service to Run-As Invoker. In this situation, the context of the invoker is used as the invocation context for each service that is part of the EncryptDocument process.

Set the execution context of a service using the Java API

Set the execution context of a service by using the Java API:

Include project files.

Include client JAR files, such as adobe-livecycle-client.jar, in your Java project’s class path.
Create a ServiceRegistryClient API object.
- Create a ServiceClientFactory object that contains connection properties.
- Create a ServiceRegistryClient object by using its constructor and passing a ServiceClientFactory object.
Reference a service.

Reference the service for which an execution context is set by invoking the ServiceRegistryClient object’s getHeadActiveConfiguration method and passing a string value that specifies the name of the service. If multiple service versions exist, the latest version (referred to as the head version) is returned. This method returns a ServiceConfiguration object that represents the service.
Set the execution context.
- Create a ModifyServiceConfigurationInfo object by using its constructor.
- Set the service identifier value by invoking the ModifyServiceConfigurationInfo object’s setServiceId method and passing the service identifier value (pass the return value of the ServiceConfiguration object’s getServiceId method).
- Set the major version of the service by invoking the ModifyServiceConfigurationInfo object’s setMajorVersion method and passing the major version value (pass the return value of the ServiceConfiguration object’s getMajorVersion method).
- Set the minor version of the service by invoking the ModifyServiceConfigurationInfo object’s setMinorVersion method and passing the minor version value (pass the return value of the ServiceConfiguration object’s getMinorVersion method).
- Set the execution context of the service by invoking the ModifyServiceConfigurationInfo object’s setRunAsConfiguration method and passing a ServiceConfiguration enumeration value that specifies the execution context type. For example, to set Run-As Invoker, pass ServiceConfiguration.RUN_AS_INVOKER.
- Invoke the ServiceRegistryClient object’s modifyConfiguration method and pass the ModifyServiceConfigurationInfo object.