Setting Up a Thick Client Development Environment

EJB transport protocol with WebSphere Application Server

1. Install the IBM WebSphere Application Client for WebSphere Application Server on your development client workstation.

   Note that the application client version must match the WebSphere Application Server version.

2. Set up the environment to use the Java™ Runtime Environment (JRE) that you installed in step 1. Make sure to set the JAVA_HOME environment variable and JRE bin in the path.
3. Update the sas.client.props (which you installed in step 1) with the following values: com.ibm.CORBA.securityServerHost=hostname com.ibm.CORBA.securityServerPort=portnumber com.ibm.CORBA.loginSource=none>

   where:

   • hostname is the computer that is running WebSphere Application Server and on which the Content Engine is deployed.
   • portnumber is the port number that is used by the computer that is identified by hostname (change this value if it differs from the default of 2809)

   Setting the loginSource value from prompt (the default) to none can prevent repeated login prompts for user ID and password.

When you run your program, make sure that you:

• Add the following Java Virtual Machine (JVM) argument:

  Windows: -Dcom.ibm.CORBA.ConfigURL=file:C:\IBM\WebSphere\AppClient\properties\sas.client.props

  AIX®: -Dcom.ibm.CORBA.ConfigURL=file:/usr/IBM/WebSphere/AppClient/properties/sas.client.props

  non-Windows: -Dcom.ibm.CORBA.ConfigURL=file:/opt/IBM/WebSphere/AppClient/properties/sas.client.props

• Add the appropriate JAR files by using one of the approaches that are listed:
  • Follow the WebSphere Application Server instructions for setting up and running a thick application client on a client machine. (See your WebSphere documentation. Note that WebSphere documentation refers to this environment as a "thin" client, not a thick client.)
  • Use the -Djava.ext.dirs command-line option to include the JAR files from the following directories:

    Windows: WebSphere install path\AppClient\lib, WebSphere Install path\AppClient\java\jre\lib\ext, and WebSphere Install path\AppClient\plugins

    non-Windows: WebSphere install path/AppClient/lib, WebSphere Install path/AppClient/java/jre/lib/ext, and WebSphere Install path/AppClient/plugins

    Example (Windows):

    -Djava.ext.dirs=C:\Program Files\IBM\WebSphere\AppClient\java\jre\lib\ext;C:\Program Files\IBM\WebSphere\AppClient\lib;C:\Program Files\IBM\WebSphere\AppClient\plugins

    Example (AIX):

    -Djava.ext.dirs=/usr/IBM/WebSphere/AppClient/java/jre/lib/ext:/usr/IBM/WebSphere/AppClient/lib:/usr/IBM/WebSphere/AppClient/plugins

    Example (Other non-Windows):

    -Djava.ext.dirs=/opt/IBM/WebSphere/AppClient/java/jre/lib/ext:/opt/IBM/WebSphere/AppClient/lib:/opt/IBM/WebSphere/AppClient/plugins

    The WebSphere setupClient script creates environment variables that point to the home locations of these directories. You can substitute those variables for the explicit path in your command.

    Example (Windows) -Djava.ext.dirs=%WAS_HOME%\AppClient\java\jre\lib\ext;%WAS_HOME%\AppClient\lib;%WAS_HOME%\AppClient\plugins

    Example (non-Windows) -Djava.ext.dirs=$WAS_HOME/AppClient/java/jre/lib/ext:$WAS_HOME/AppClient/lib:$WAS_HOME/AppClient/plugins

  • Explicitly add all of the JAR files in the WebSphere library and plug-in directories to your class path:

    WebSphere library directory:

    Windows: WebSphere install path\AppClient\lib

    non-Windows: WebSphere install path/AppClient/lib

    WebSphere plugin directory:

    Windows: WebSphere install path\AppClient\plugins

    non-Windows: WebSphere install path/AppClient/plugins

• Pass the correct URI to the connection.

  A typical URI is "iiop://hostname:port/FileNet/Engine", where hostname and port must match the host name and port number that is specified in the BOOTSTRAP_ADDRESS configuration parameter from the WebSphere administration console under Server > Ports.

  Tip: From a Windows command line on your client development workstation, double-check the host name by issuing a ping command. The network name of the server, returned from using ping on the client, must match the host that is specified for the BOOTSTRAP_ADDRESS.

Other issues

Based on your environment, be aware of the following issues that require additional steps to be taken:

• If you do not use UserContext.createSubject, then the caller must initialize the ORB before you make the Java Authentication and Authorization Service (JAAS) login call, as shown in the following example:

  Context ic = new InitialContext();
   ic.lookup("");

• If you use a JAAS stanza other than the FileNetP8 stanza, or if you use an authentication scheme other than user name and password, then you must supply a JAAS configuration file. You specify that file by using a standard command-line argument, as shown in the following example:

  -Djava.security.auth.login.config=jaas.conf.WebSphere

EJB transport protocol with WebLogic Application Server

1. Install a supported JRE on your development client workstation.
   Note: Both JRocket or Sun JREs are acceptable. However, JRocket with IIOP in WebLogic 9.x has known problems and is not recommended.
2. Add the following to your Java Naming and Directory Interface (JNDI) configuration by selecting one of the following two approaches:
   • Supply the following JVM arguments:

     -Djava.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
     -Djava.naming.provider.url=t3://hostname:7001

   • Add the following values to a jndi.properties file that is in the class path:

      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
      java.naming.provider.url=t3://hostname:7001

     Note: The jndi.properties file must be in the class path. You can either include the file in a JAR file and add the JAR file to the class path, or you can create a directory under the class path and put the file in that directory.
3. Use the t3 protocol

   Add the weblogic.jar file to the class path (or wlfullclient.jar for WebLogic version 10.x and later). Then, specify the t3 protocol by providing a URI of "t3://hostname:7001/FileNet/Engine" in the Content Engine API Connection class. Note that you can use IIOP as the protocol with wlclient.jar, but it is not recommended. IIOP is slower than and not as functional as the t3 protocol. The following code snippet illustrates how to provide the URI for the connection:

   // Get the connection.
   String uri = "t3://remotehost:7001/FileNet/Engine";
   Connection conn = Factory.Connection.getConnection(uri);

4. Specify the location of a JAAS configuration file. You specify that file by using a standard command-line argument, as shown in the following example:

   -Djava.security.auth.login.config=jaas.conf.WebLogic

   Note: The JAAS configuration files are contained in the Jace.jar file. With this command, you identify the configuration file to use.

EJB or CEWS transport protocol with JBoss Application Server

1. Install a supported JRE on your development client workstation.
2. Add the jbossall-client.jar file from the JBoss client directory (Windows: jboss-home\client, non-Windows: jboss-home/client) to the class path.
   Note: If you are using JBoss 5.x, be aware that jbossall-client.jar no longer contains every class that a client application needs. It instead contains a manifest file that refers to other JAR files. If JBoss 5.x is not installed on your development system, you must copy all JAR files from the jboss-home\client directory on the JBoss application server to your client library or copy all of the JAR files that are referenced in the jbossall-client.jar manifest to your client library. For more information about the jbossall-client.jar manifest, see your JBoss documentation.
3. Add the following values to your JNDI configuration by selecting one of the following two approaches:
   1. Supply the following JVM arguments:

      -Djava.naming.factory.initial=org.jboss.naming.NamingContextFactory
      -Djava.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
      -Djava.naming.provider.url=jnp://hostname:1099

   2. Add the following values to a jndi.properties file that is in the class path:

       java.naming.factory.initial=org.jboss.naming.NamingContextFactory
       java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
       java.naming.provider.url=jnp://hostname:1099

      Note: The jndi.properties file must be in the class path. You can either include the file in a JAR file and add the JAR file to the class path, or you can create a directory under the class path and put the file in that directory.
4. Modify your junit.properties file as follows:
   • For EJB protocol:

     jnp://hostname:1099/FileNet/Engine

   • For CEWS protocol:

     URI:  http://hostname:8080/wsi/FNCEWS40MTOM/

5. Specify the location of a JAAS configuration file. You specify that file by using a standard command-line argument, as shown in the following example:

   -Djava.security.auth.login.config=jaas.conf.JBoss

   Note: The JAAS configuration files are contained in the Jace.jar file. With this command, you identify the configuration file to use.

CEWS transport protocol (non-application-server dependent)

When you set up a thick client development machine by using the CEWS protocol, the following tasks are required:

1. After the Content Engine Client installation is performed, verify that the following JAR files are installed on the client machine: Jace.jar, log4j.jar, stax-api.jar, xlxpScanner.jar, xlxpScannerUtils.jar, and p8cel10n.jar. After a client installation, these files are in the following location. For more information, see Required Java Archive (JAR) Files:
   • Windows: C:\Program Files\IBM\FileNet\CEClient\lib
   • AIX: /usr/IBM/FileNet/CEClient/lib
   • Other non-Windows: /opt/IBM/FileNet/CEClient/lib
2. Specify the FileNetP8WSI login module for JAAS. (Note that you can use the FileNetP8WSI default stanza, which is bundled with the Jace.jar file.) You can accomplish this task in one of the two ways:
   1. Add the FileNetP8WSI stanza to a JAAS configuration file and specify a JVM command-line argument that points to the file, as shown in the following example:

      Here is the stanza that must exist in the JAAS configuration file:

      FileNetP8WSI  {
      com.filenet.api.util.WSILoginModule  required;
      };

      Here is the command-line argument to provide to the JVM that tells the system which JAAS configuration file to use:

      -Djava.security.auth.login.config=jaas.conf

      Use "FileNetP8WSI"in the constructor of the LoginContext JAAS class.

   2. Call UserContext.createSubject with a stanza name of "FileNetP8WSI":

       
      Subject subject =UserContext.createSubject(connection, "userid", "password","FileNetP8WSI");
      UserContext uc = UserContext.get();
      uc.pushSubject(sub); 
      try {
             // your code here
      }
       finally 
       { 
             uc.popSubject(); 
       }