Developing a Cross-Release Application

Only the Content Engine Java API provides cross-release class loading support. This support is not included in the Content Engine .NET API or the Process Engine API.

A cross-release application must meet the following requirements:

• The application must run with the Content Engine Java API JAR file, Jace.jar, which is included with Content Platform Engine server version 5.2.1 or higher. This API is referred to as the visible API and is used to start the application and connect to any Content Platform Engine servers of version 5.2.1 or higher.
• For connections to other versions of the Content Platform Engine server, the application must instantiate a separate Connection object for each server version, and configure each Connection object to use the Jace.jar file appropriate for that server version. These other copies of Jace.jar, from which server-appropriate implementation classes are loaded, are referred to as the implementation APIs.

  For example, if the application connects to versions 5.0 and 5.1 (in addition to 5.2.1) of the server, then the Connection objects for versions 5.0 and 5.1 must be configured to use the Jace.jar files that are included with the 5.0 and 5.1 servers.

  The implementation APIs are specified with a ConfigurationParameter instance of types CONNECTION_IMPLEMENTATION_API_LOCATION, CONNECTION_IMPLEMENTATION_API_LOCATIONS, and CONNECTION_IMPLEMENTATION_API_URLS.

  The CONNECTION_IMPLEMENTATION_API_LOCATION parameter directly specifies a single Jace.jar file for a Connection object. This parameter is not used with the other implementation configuration parameters.

  The CONNECTION_IMPLEMENTATION_API_LOCATIONS and CONNECTION_IMPLEMENTATION_API_URLS parameters are used together to map Connection URLs to paths to Jace.jar files, automatically associating a Connection object with its appropriate implementation API.

The following code snippet shows how ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_URLS and ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_LOCATIONS are used to associate Connection URLs with locations to Jace.jar files. Both provide a list of key/value pairs. For ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_URLS, the key is the Content Platform Engine connection URL and the value is a Content Platform Engine release number (fictional for this example). For ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_LOCATIONS, the key is the Content Platform Engine release number, and the value is the path to a Jace.jar file for that release.

CRCL uses these two parameters together to create a many-to-one map between Content Platform Engine Connection URLs and copies of Jace.jar for the implementation APIs. For a Connection object, the URL is used to find the corresponding implementation API JAR file. CRCL matches the value of the Content Platform Engine connection with the key of the JAR file location. In the example, CRCL matches the URL http://svr1:9080/wsi/FNCEWS40SOAP/ with /my/vault/Jace-6.0.2.3.jar, and the URL iiop://svr2:2809/FileNet/Engine with /my/vault/7.11.0.0/Jace.jar.

Any Connection with a URL that cannot be matched with a JAR location, or with a URL that is not present in the key/value mapping, falls back to using the visible API.

...
String urlMapping = "~http://svr1:9080/wsi/FNCEWS40SOAP/ ~ 6.0.2.3" +
                    "~iiop://svr2:2809/FileNet/Engine ~ 7.11.0.0";
String pathMapping = "^6.0.2.3 ^ /my/vault/Jace-6.0.2.3.jar" +
                     "^7.11.0.0 ^ /my/vault/7.11.0.0/Jace.jar";

ConfigurationParameters parameters = new ConfigurationParameters();
parameters.setParameter(ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_URLS, urlMapping);
parameters.setParameter(ConfigurationParameter.CONNECTION_IMPLEMENTATION_API_LOCATIONS, pathMapping);

To continue with this example, the client creates two Connection objects, one for Content Platform Engine release 6.0.2.3 and one for Content Platform Engine release 7.11.0.0. Each Connection is configured with the ConfigurationParameters object, mapping the URLs to the applicable implementation JARs. For each Connection, CRCL loads the server-appropriate implementation classes.

crcl.connectToSvr1(parameters);
crcl.connectToSvr2(parameters);

// Connect to svr1.
public void connectToSvr1(ConfigurationParameters parameters)
{
   svr1Conn = Factory.Connection.getConnection(<svr1Uri>, parameters);
   Subject subject = UserContext.createSubject(svr1Conn, <username>, <password>, <jaasStanza>);
   UserContext.get().pushSubject(subject);

   try 
   {
      // do work on svr1
   }
   finally
   {
      UserContext.get().popSubject();
   }
}

// Connect to svr2.
public void connectToSvr2(ConfigurationParameters parameters)
{
   svr2Conn = Factory.Connection.getConnection(<svr2Uri>, parameters);
   Subject subject = UserContext.createSubject(svr2Conn, <username>, <password>, <jaasStanza>);
   UserContext.get().pushSubject(subject);

   try 
   {
      // do work on svr2
   }
   finally
   {
      UserContext.get().popSubject();
   }
}