Setting connection properties

Invoking scenarios
Client application invoking a stand-alone LiveCycle instance
Client application invoking clustered LiveCycle instances

You set connection properties to invoke LiveCycle when using the Java API. When setting connection properties, specify whether to invoke services remotely or locally, and also specify the connection mode and authentication values. Authentication values are required if service security is enabled. However, if service security is disabled, it is not necessary to specify authentication values. (See Disabling Service Security.)

The connection mode can either be SOAP or EJB mode. The EJB mode uses the RMI/IIOP protocol, and the performance of the EJB mode is better than the performance of the SOAP mode. The SOAP mode is used to eliminate a J2EE application server dependency or when a firewall is located between LiveCycle and the client application. The SOAP mode uses the https protocol as the underlying transport and can communicate across firewall boundaries. If neither a J2EE application server dependency or a firewall is an issue, it is recommended that you use the EJB mode.

To successfully invoke a LiveCycle service, set the following connection properties:

DSC_DEFAULT_EJB_ENDPOINT: If you are using the EJB connection mode, this value represents the URL of the J2EE application server on which LiveCycle is deployed. To remotely invoke LiveCycle, specify the J2EE application server name on which LiveCycle is deployed. If your client application is located on the same J2EE application server, then you can specify localhost. Depending on which J2EE application server LiveCycle is deployed on, specify one of the following values:
- JBoss: jnp://<ServerName>:1099 (default port)
- WebSphere: iiop://<ServerName>:2809 (default port)
- WebLogic: t3://<ServerName>:7001 (default port)
DSC_DEFAULT_SOAP_ENDPOINT: If you are using the SOAP connection mode, this value represents the endpoint to where an invocation request is sent. To remotely invoke LiveCycle, specify the J2EE application server name on which LiveCycle is deployed. If your client application is located on the same J2EE application server, you can specify localhost (for example, http://localhost:8080.)
- The port value 8080 is applicable if the J2EE application is JBoss. If the J2EE application server is IBM® WebSphere®, use port 9080. Likewise, if the J2EE application server is WebLogic, use port 7001. (These values are default port values. If you change the port value, use the applicable port number.)
DSC_TRANSPORT_PROTOCOL: If you are using the EJB connection mode, specify ServiceClientFactoryProperties.DSC_EJB_PROTOCOL for this value. If you are using the SOAP connection mode, specify ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL.
DSC_SERVER_TYPE: Specifies the J2EE application server on which LiveCycle is deployed. Valid values are JBoss, WebSphere, WebLogic.
- If you set this connection property to WebSphere, the java.naming.factory.initial value is set to com.ibm.ws.naming.util.WsnInitCtxFactory.
- If you set this connection property to WebLogic, the java.naming.factory.initial value is set to weblogic.jndi.WLInitialContextFactory.
- Likewise, if you set this connection property to JBoss, the java.naming.factory.initial value is set to org.jnp.interfaces.NamingContextFactory.
- You can set the java.naming.factory.initial property to a value that meets your requirements if you do not want to use the default values.
Note: Instead of using a string to set the DSC_SERVER_TYPE connection property, you can use a static member of the ServiceClientFactoryProperties class. The following values can be used: ServiceClientFactoryProperties.DSC_WEBSPHERE_SERVER_TYPE, ServiceClientFactoryProperties.DSC_WEBLOGIC_SERVER_TYPE, or ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE.
DSC_CREDENTIAL_USERNAME: Specifies the LiveCycle user name. For a user to sucessfully invoke a LiveCycle service, they need the Services User role. A user can also have another role that includes the Service Invoke permission. Otherwise, an exception is thrown when they attempt to invoke a service. If service security is disabled, it is not necessary to specify this connection property. (See Disabling Service Security.)
DSC_CREDENTIAL_PASSWORD: Specifies the corresponding password value. If service security is disabled, it is not necessary to specify this connection property.
DSC_REQUEST_TIMEOUT: The default request timeout limit for the SOAP request is 1200000 milliseconds (20 minutes). Sometime, a request can require longer time to complete the operation. For example, a SOAP request that retrieves a large set of records can require a longer timeout limit. You can use the ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT to increase the request call timeout limit for the SOAP requests.

Note: Only SOAP-based invocations support the DSC_REQUEST_TIMEOUT property.

To set connection properties, perform the following tasks:

Create a java.util.Properties object by using its constructor.
To set the DSC_DEFAULT_EJB_ENDPOINT connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
- The ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT enumeration value
- A string value that specifies the URL of the J2EE application server that hosts LiveCycle
Note: If you are using the SOAP connection mode, specify the ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT enumeration value instead of the ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT enumeration value.
To set the DSC_TRANSPORT_PROTOCOL connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
- The ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL enumeration value
- The ServiceClientFactoryProperties.DSC_EJB_PROTOCOL enumeration value
Note: If you are using the SOAP connection mode, specify the ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL enumeration value instead of the ServiceClientFactoryProperties.DSC_EJB_PROTOCOL enumeration value.
To set the DSC_SERVER_TYPE connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
- The ServiceClientFactoryProperties.DSC_SERVER_TYPE enumeration value
- A string value that specifies the J2EE application server that hosts LiveCycle (for example, if LiveCycle is deployed on JBoss, specify JBoss).
  
  To set the DSC_CREDENTIAL_USERNAME connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
- The ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME enumeration value
- A string value that specifies the user name required to invoke LiveCycle
  
  To set the DSC_CREDENTIAL_PASSWORD connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
- The ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD enumeration value
- A string value that specifies the corresponding password value

Setting the EJB connection mode

The following Java code example sets connection properties to invoke LiveCycle deployed on JBoss and using the EJB connection mode.

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://localhost:1099"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting the EJB connection mode for WebLogic

The following Java code example sets connection properties to invoke LiveCycle deployed on WebLogic and using the EJB connection mode.

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "t3://localhost:7001"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebLogic"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting the EJB connection mode for WebSphere

The following Java code example sets connection properties to invoke LiveCycle deployed on WebSphere and using the EJB connection mode.

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "iiop://localhost:2809"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebSphere"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting the SOAP connection mode

The following Java code example sets connection properties in SOAP mode to invoke LiveCycle deployed on JBoss.

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Note: If you select the SOAP connection mode, ensure to include additional JAR files in your client application’s class path.

Setting connection properties when service security is disabled

The following Java code example sets connection properties required to invoke LiveCycle deployed on JBoss Application Server and when service security is disabled. (See Disabling Service Security.)

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://localhost:1099"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");

Note: All Java Quick Starts associated with Programming with LiveCycle show both EJB and SOAP connection settings.

Setting the SOAP connection mode with custom request timeout limit

Properties ConnectionProps = new Properties(); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);           
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password"); 
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT, "1800000"); // Request timeout limit 30 Minutes

Using a Context object to invoke LiveCycle

You can use a com.adobe.idp.Context object to invoke a LiveCycle service with an authenticated user (the com.adobe.idp.Context object represents an authenticated user). When using a com.adobe.idp.Context object, you do not need to set the DSC_CREDENTIAL_USERNAME or DSC_CREDENTIAL_PASSWORD properties. You can obtain a com.adobe.idp.Context object when authenicating users by using the AuthenticationManagerServiceClient object’s authenticate method.

The authenticate method returns an AuthResult object that contains the results of the authentication. You can create a com.adobe.idp.Context object by invoking its constructor. Then invoke the com.adobe.idp.Context object’s initPrincipal method and pass the AuthResult object, as shown in the following code:

Context myCtx = new Context();  
myCtx.initPrincipal(authResult);

Instead of setting the DSC_CREDENTIAL_USERNAME or DSC_CREDENTIAL_PASSWORD properties, you can invoke the ServiceClientFactory object’s setContext method and pass the com.adobe.idp.Context object. When using a LiveCycle user to invoke a service, ensure that they have the role named Services User that is required to invoke a LiveCycle service.

The following code example shows how to use a com.adobe.idp.Context object within connection settings that are used to create an EncryptionServiceClient object.

//Authenticate a user and use the Context object within connection settings 
// Authenticate the user 
String username = "wblue"; 
String password = "password"; 
AuthResult authResult = authClient.authenticate(username, password.getBytes()); 
 
//Set a Content object that represents the authenticated user 
//Use the Context object to invoke the Encryption service 
Context myCtx = new Context();  
myCtx.initPrincipal(authResult); 
 
//Set connection settings 
Properties connectionProps = new Properties(); 
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://hiro-xp:1099"); 
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_EJB_PROTOCOL); 
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE); 
                         
//Create a ServiceClientFactory object 
ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps); 
myFactory.setContext(myCtx); 
                         
//Create an EncryptionServiceClient object 
EncryptionServiceClient encryptClient  = new EncryptionServiceClient(myFactory);

Note: For complete details about authenticating a user, see Authenticating Users.

Invoking scenarios

The following invoking scenarios are discussed in this section:

A client application running in its own Java virtual machine (JVM) invokes a stand-alone LiveCycle instance.
A client application running in its own JVM invokes clustered LiveCycle instances.

Client application invoking a stand-alone LiveCycle instance

The following diagram shows a client application running in its own JVM and invoking a stand-alone LiveCycle instance.

In this scenario, a client application is running in its own JVM and invokes LiveCycle services.

Note: This scenario is the invoking scenario on which all Quick Starts are based.

Client application invoking clustered LiveCycle instances

The following diagram shows a client application running in its own JVM and invoking LiveCycle instances located in a cluster.

This scenario is similar to a client application invoking a stand-alone LiveCycle instance. However, the provider URL is different. If a client application wants to connect to a specific J2EE application server, the application must change the URL to reference the specific J2EE application server.

Referencing a specific J2EE application server is not recommended because the connection between the client application and LiveCycle is terminated if the application server stops. It is recommended that the provider URL reference a cell-level JNDI manager, instead of a specific J2EE application server.

Client applications that use the SOAP connection mode can use the HTTP load balancer port for the cluster. Client applications that use the EJB connection mode can connect to the EJB port of a specific J2EE application server. This action handles the Load Balancing between cluster nodes.

WebSphere

The following example shows the contents of a jndi.properties file that is used to connect to LiveCycle that is deployed on WebSphere.

java.naming.factory.initial=com.ibm.websphere.naming. 
WsnInitialContextFactory 
java.naming.provider.url=corbaloc::appserver1:9810,:appserver2:9810

WebLogic

The following example shows the contents of a jndi.properties file that is used to connect to LiveCycle that is deployed on WebLogic.

java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory 
java.naming.provider.url=t3://appserver1:8001, appserver2:8001

JBoss

The following example shows the contents of a jndi.properties file that is used to connect to LiveCycle that is deployed on JBoss.

java.naming.factory.initial= org.jnp.interfaces.NamingContextFactory 
java.naming.provider.url= jnp://appserver1:1099, appserver2:1099, 
appserver3:1099

Note: Consult your administrator to determine the J2EE application server name and port number.