Developing exteNd Director Applications

CHAPTER 20

Deploying exteNd Director Applications

This chapter provides information about deploying exteNd Director applications. It contains these sections:

• Deploying an exteNd Director project

• Testing the deployment

• What happens to exteNd Director subsystems at deployment

• Troubleshooting the deployment

• Changing your deployment configuration

• About exteNd Director database tables

Deploying an exteNd Director project

After you build and archive your project, you can deploy it to a J2EE application server. You can deploy a newly created project—you do not have to add any application-specific functionality to a project before deploying it.

The following table lists the deployment configurations supported for each exteNd Director project type:

    For more information on shared library configurations, see Changing a project's shared library configuration.

Depending on the server you are deploying to, you'll need to do some predeployment setup and possibly some post-deployment configuration.

The deployment process includes these tasks:

• Predeployment tasks

• Deployment tasks

• Post-deployment tasks

Predeployment tasks

The tasks in the following table apply to Portlet Application Projects and Director projects. Before you deploy your application, make sure of the following:

Setting up an exteNd Director database

Many of the exteNd Director subsystems require a relational database to store persistent data. Follow the steps outlined below to set up a database for use by exteNd Director:

    For a list of the exteNd Director database tables, see About exteNd Director database tables.

Setting up JARs and the server's classpath

exteNd Director requires you to use exteNd Director's version of these JARs:

• xercesImpl

• xalan

• Phaos_Crypto_FIPS

• Phaos_SSLava

• Phaos_Security_Engine

You'll need to copy the file from the exteNd Director install to a specific directory on your application server.

1. Copy each of these files from this install location:

   Copy this JAR	From this exteNd Director install directory
   xalan.jar	extend5\Director\templates\Director\library
   xercesImpl.jar
   Phaos_Crypto_FIPS	Common/jre/lib/ext
   Phaos_SSLava
   Phaos_Security_Engine

2. Place the copy of exteNd Director's version of these JARs in the proper location for your application server as described in the next table.

   NOTE:   If you are using the exteNd Application Server, these files are installed into the proper location by default, so you are not required to make any changes.

   IMPORTANT:   Restart the server after copying these files.

   Server	JAR	Instructions
   BEA WebLogic	xalan	Create a subdirectory called endorsed in the JRE used by WebLogic. For example: c:\bea\jdk141_02\jre\lib\endorsed Copy exteNd Director's xalan.jar to the endorsed directory.
   	xercesImpl	Copy to the server's \lib directory. Edit the server's start command to reference the xercesImpl.jar as the first item in the server's Classpath.
   	Phaos_Crypto_FIPS Phaos_SSLava Phaos_Security_Engine	Copy to the server's jre\lib\ext directory.
   IBM WebSphere	xalan	Copy to the server's \lib directory. (You should first save WebSphere's copy of xalan.jar to a different location.)
   	xercesImpl	Rename WebSphere's xerces.jar and move it out of the WebSphere\lib directory. Copy exteNd Director's xercesImpl.jar to WebSphere's \lib directory.
   	Phaos_Crypto_FIPS Phaos_SSLava Phaos_Security_Engine	Copy to the server's jre\lib\ext directory.
   Apache Tomcat	xalan	Copy to server's \common\endorsed directory.
   	xercesImpl	Copy to server's \common\endorsed directory.
   	Phaos_Crypto_FIPS Phaos_SSLava Phaos_Security_Engine	Copy to the server's jre\lib\ext directory.

IMPORTANT:   If you are developing on a Windows platform and deploying to a non-exteNd application server running on UNIX, copy the Phaos_Crypto_FIPS_UNIX.jar from the Common\lib\other directory to the directory for your server specified above. Rename it Phaos_Crypto_FIPS.jar.

Tomcat predeployment tasks

1. Locate the FrameworkService-conf and DirectoryService-conf files for your project type:

   Archive type	Project location
   EAR	\Library\ConfigService\ConfigService.spf\
   WAR	WEB-INF\lib\ConfigService\ConfigService.spf\

2. Make sure the following Framework services settings are correct:

   In the FrameworkService-conf config.xml file:

   Key	Value
   com.sssw.userTransaction.enable	False (unless you have a JTA extension installed)
   com.sssw.fw.datasource.jndi-name	Matches the name of the connection pools that you created to store your exteNd Director tables

   In the DirectoryService-conf config.xml file. The values for PersistManager are:

   Key	Value
   DirectoryService/realms/readable	com.sssw.fw.directory.api.EbiPersistMgrRealm
   DirectoryService/realms/writeable	com.sssw.fw.directory.api.EbiPersistMgrRealm

   The values for LDAP are:

   Key	Value
   DirectoryService/realms/readable	com.sssw.fw.directory.api.EbiJndiLdapRealm
   DirectoryService/realms/writeable	com.sssw.fw.directory.api.EbiJndiLdapRealm

   TIP:   Using the PersistManager realm causes the application database to function as the user authentication repository. The LDAP realm specifies that user authentication repository is an eDirectory server.

LDAP predeployment tasks (eDirectory only)

If you are using an eDirectory LDAP realm configuration, you need to:

• Import a UUID auxiliary class

• (Optional) Set up your LDAP server to use SSL

Importing the UUID auxiliary class   Before you deploy a project that implements one of the LDAP application server realms, you need to import the provided auxiliary class specified in the UUID auxiliary class property in the Directory LDAP Configuration panel. exteNd Director uses this class to access portal users in the LDAP tree.

You import this class using the NDS Import Wizard in the Novell ConsoleOne^® eDirectory tool.

To import the UUID auxiliary class in ConsoleOne:

1. With the NDS container selected in ConsoleOne, select Wizards>NDS> Import/Export:

   

2. Click Import LDIF File and choose Next:

   

3. Navigate to the ldif file in your exteNd Director installation path and select it (it is located at bin/extElemImport.ldif). Click Next:

   

4. Verify the LDAP host name and port, choose Authenticated Login, and specify your administrator DN (distinguished name) and password:

   

5. Verify the information and click Finish:

   

Configuring and using SSL for LDAP connections   Complete the procedures described here if you want to connect to your LDAP realm using Secure Socket Layer (SSL).

NOTE:   SSL connections are slower than plain or clear-text connections. The initial portal connection can take up to 30 seconds to be established.

To configure the LDAP server to support SSL:

1. In ConsoleOne, open the properties on the LDAP Server object that represents the LDAP server you are using with exteNd Director.

2. Select the SSL Configuration tab.

3. In the SSL Certificate field, select an SSL Certificate object.

4. Make note of the SSL Port (typically 636).

5. Make sure the Disable SSL Port option is not checked.

6. Save the settings and refresh the NLDAP server:

   1. Open the properties of the LDAP server.

   2. Click the Refresh NLDAP Server Now button on the General page.

To export the Trusted Root Certificate:

1. Open the properties on the SSL certificate object that you configured in the preceding procedure.

2. Select the Certificates tab.

3. Select the Trusted Root Certificate subtab.

4. Click Export and save the file in binary DER format, typically named TrustedRootCert.der.

To download and install the Java Secure Socket Extension (JSSE):

This step is required only if your server is running with a JRE older than 1.4 and is not already configured to use JSSE.

Follow the installation instructions for JSSE—summarized as follows:

1. Copy JSSE.JAR, JNET.JAR, and JCERT.JAR to the server's JRE extensions directory (for example: jre/lib/ext).

2. Find and edit the java.security file, located in the lib/security directory of the server's JRE (for example: jre/lib/security/java.security).

3. Follow the directions at the beginning of the document to add the JSSE SSL provider:

   • Add a line to the security providers section using the format below, replacing name with the next provider number in succession:

     security.provider.name =com.sun.net.ssl.internal.ssl.Provider
   

To import the Trusted Root Certificate into your cacerts or jssecacerts trust store file:

1. Find the cacerts or jssecacerts file. It is located in the lib/security directory of the server's JRE (for example: jre/lib/security/cacerts).

2. Find keytool, located in the /bin folder relative to your Java home folder.

   IMPORTANT:   You must use a keytool that comes with JVM 1.3 or later.

3. Run the following command, making replacements listed below:

     keytool -import -alias aliasName -file TrustedRootCert.der -keystore cacerts -storepass changeit
   

   • Replace aliasName with a unique name for this certificate.

   • Make sure the full path for cacerts and the full path for TrustedRootCert.der are specified.

   • Note that changeit is the default keystore password. Use the appropriate keystore password if it has been changed.

To configure exteNd Director to use SSL in the Directory service:

1. Open your exteNd Director project.

2. Select Project>Director Project>Configuration.

3. Click the Directory tab and then click the Directory Ldap Options lower tab.

4. Change the LDAP host to include the SSL port for eDirectory (for example: localhost:636).

5. Make sure Use SSL is checked and click OK.

6. Rebuild your project and redeploy.

Deployment tasks

Once you've completed all the predeployment steps, you can start deployment.

• To deploy to IBM WebSphere Advanced Edition, you must use the WebSphere deployment tools; see Using IBM WebSphere deployment tools.

• To deploy to any other supported server, see Using exteNd Director deployment tools next.

Using exteNd Director deployment tools

To use the exteNd Director deployment tools, complete these deployment tasks:

Using IBM WebSphere deployment tools

To deploy to WebSphere Advanced Edition, you must use the WebSphere Advanced Administrative Console—you cannot use the exteNd Director deployment tools. Here are the general steps to follow when using the console. For more details, see the IBM documentation.

Post-deployment tasks

After deployment you need to:

* If you redeployed on a shared library server, and also copied new or updated existing JARs in the shared library directory, you'll need to restart the server after the redeployment.

Novell exteNd Application Server

If you are using connection pools to access the exteNd Director database, you do not need to perform any post-deployment tasks—so you can skip this section.

If you used the deprecated AddDatabase feature to access the exteNd Director database, you'll need to perform the procedure that follows. (Because the deployment procedure adds tables to the exteNd Director database, the schema changes render the server's snapshot of the database schema out of sync. To fix this, you need to synchronize the database schema.)

To synchronize the database schema:

1. While the server is running, start the Server Management Console (SMC).

2. Select the Databases panel.

3. In Settings for database, select your exteNd Director database.

4. Click Synchronize Database Schema.

IBM WebSphere

You'll need to do these postdeployment tasks only if your project does either of the following:

• Uses the WebSphere custom realm (at project creation, you chose WebSphere as your realm). Because this acts as a custom registry, you'll need to make the custom registry entries described in the following procedures.

• Uses an LDAP realm (at project creation, you chose LDAP as the realm). You'll just need to follow the procedure To define global security:.

To define general properties:

1. In the Custom User Registry, define the following properties with the values shown:

   Property	Value
   Server User ID	admin
   Server Password	admin
   Custom Registry Classname	com.sssw.fw.server.websphere.realm.EboWebSphereRealm
   Ignore case	Not selected

2. Click Save.

To define Custom User Registry Custom properties:

1. Define these values:

   Name	Value
   driver	Enter the JDBC driver class name used to connect to the exteNd Director database. This is not the Datasource class name. For example, the JDBC driver class name for the Microsoft SQL Server type 4 driver is: com.microsoft.jdbc.sqlserver.SQLServerDriver For Oracle Thin Driver: oracle.jdbc.OracleDriver
   url	The JDBC URL to connect to the exteNd Director database. For example, for Microsoft SQL Server type 4 driver: jdbc:microsoft:sqlserver://host:port;user=myuser;password=secret;databasename=Directordatabase For Oracle Thin Driver: jdbc:oraclce:thin:@wd40:1521:ocl
   user	Enter the username that you used when you added that database to the server.
   password	Enter the password.

2. Click Save.

To define global security:

1. Define these values:

   Property	Value
   Enabled	Selected
   Enforce Java 2 security	Not selected NOTE:   If you want to use Java 2 security, change the value to selected and configure the Java security policy file.
   Active User Registry	Custom or LDAP

2. Click Save.

3. Restart the server for all property settings to take effect.

Testing the deployment

To test the deployed application:

1. In your browser, try the URLs that match your deployment configuration:

   Server	URL
   Novell exteNd—deployed to SilverMaster	http://server:port/context/portal For example: http://localhost/ExpressPortal/portal
   BEA WebLogic
   IBM WebSphere
   Novell exteNd—deployed to non-SilverMaster	http://server:port/database/context/portal For example: http://localhost/MyDatabase/MyPortal/portal

   Variables in the URLs In this procedure, the variables have these meanings:

   • server is the name of your application server.

   • port is the port number for your application server. The defaults are:

     Server	Default port
     Novell exteNd	80 (Windows) 8080 (UNIX) 83 (NetWare)
     Tomcat	8080
     WebLogic	7001
     WebSphere	9080

   • database is the database to which you deployed the archive (Novell exteNd only)

   • context is the namespace for the exteNd Director application, which you specified in the Project Wizard

What happens to exteNd Director subsystems at deployment

At deployment, exteNd Director applications are compiled, archived, and deployed to the specified server (described in the deployment chapter of Utility Tools). For applications that rely on one or more exteNd Director subsystems, there are additional activities that occur (without user intervention) at deployment. They are described in the following sections:

• How the subsystems register themselves with the Framework

• How the subsystems access persistent data

• How the subsystems access application resources

How the subsystems register themselves with the Framework

To make its services available, a subsystem must register itself with the Framework. The process of self-registration involves loading configuration and service information into the Framework. Once this information has been loaded, the appropriate factories can produce the correct implementations for each requested service. The registration process is initiated by the boot servlet, which starts up automatically when you deploy an exteNd Director EAR or restart your application server. An autostart servlet must be the first servlet to load within an exteNd Director EAR.

Boot process   During the framework boot process, the boot servlet starts up the base factory for the framework, which performs these operations:

1. Reads the config.xml file for each subsystem into the framework's memory space.

   The config.xml file sets the configuration properties for a subsystem. It is typically located in the subsystem-name-conf subdirectory of the ConfigService.spf.

2. Performs any database processing required for each subsystem. For each subsystem that needs to load data into a database, the base factory creates the schema and loads the data, if necessary.

   Each subsystem that requires database processing delivers scripts for creating the schema and loading the data. These scripts are located in the database subdirectory of the subsystem-name-conf subdirectory of the ConfigService.spf.

       For more information about how the subsystems perform database processing, see How the subsystems access persistent data.

3. Reads the services.xml file for each subsystem into the framework's memory space.

   The services.xml file sets properties for each of the services associated with a subsystem. It is located in the subsystem-name-conf subdirectory of the ConfigService.spf.

4. Notifies subsystem-specific service loaders that the main processing is done.

5. Starts all autostart services listed in services.xml files.

   Autostart services have a startup property value of A (for automatic). Those services that have a startup element of M (for manual) are not started.

How the subsystems access persistent data

The following subsystems depend on a database to store persistent information:

• Content Management

• Directory

• Security

• User

• Workflow

After the Framework boot servlet reads the config.xml file for each subsystem, it performs any database processing required for the subsystems. The boot servlet checks the config.xml file to determine if it needs to create the schema and load data. It does this by examining the following configuration properties:

For example, the config.xml file for the Directory subsystem has these settings for the db-load-on-startup and test-db-on-startup properties:

  <property>
   <key>DirectoryService/db-load-on-startup</key>
   <value>true</value>
  </property>
  <property>
   <key>DirectoryService/test-db-on-startup</key>
   <value>AUTHGROUPS</value>
  </property>

When database processing is required for a subsystem, the boot servlet executes the scripts in the database subdirectory of the subsystem-name-conf subdirectory of the ConfigService.spf.

NOTE:   Do not edit the database scripts provided with the exteNd Director subsystems. These scripts should be used as they are.

How the subsystems access application resources

exteNd Director subsystems often require access to application resources that are not stored in a database or defined in the configuration and service elements for the subsystems. Resource sets provide a known location for these resources. A resource set holds definitions for rules, pageflows, portlets, styles, and various descriptors that implement features provided by exteNd Director subsystems. It can also hold Java classes and images for your application.

Resource sets are also a tool for streamlining development, because they can be configured to load resources from disk as well as from a deployed JAR. This dynamic loading of resources allows you to modify and test changes without having to redeploy the whole exteNd Director EAR.

    For information on how to use resource sets, see Using the Resource Set in an exteNd Director Application.

Troubleshooting the deployment

This section contains troubleshooting for the following categories:

• General troubleshooting

• Troubleshooting BEA WebLogic deployments

General troubleshooting

Problem	Cause	Solution
You encounter the following error: Server Console Trace: ------------------------- WARNING: This portal app context, Director51, does not match the portal.context property set in the PortalService-conf/config.xml file. Only one portal per data base is allowed. Data has been loaded using the previous portal context. To correct this you must revert back to the previous portal name of, null, please consult the documentation. java.lang.reflect.InvocationTargetException	Your application server is configured to use shared libraries and an exteNd Director portal is already deployed—you are attempting to deploy another application that includes a portal.	In a shared library environment, you are restricted to a single deployed portal. You have two options. You can: Change the server and project configuration to nonshared library so that you can deploy multiple portals.     For more information, see Changing a project's shared library configuration. OR Complete the following steps (that will undeploy your already deployed portal so that you can deploy the new project. Use your server's tools to undeploy the archive containing the existing exteNd Director portal. Create a new exteNd Director database for the new portal, and create a new connection pool for it. Build the project for the new portal (and a deployment plan if needed). Choose Project>Director>Shared Lib. Click Copy JARs and copy the shared library JARs to the appropriate location for your server. NOTE:   If you do not perform this step, the application server will still contain references to the previously deployed portal's configuration, and you'll get the same error. Deploy the archive.

Troubleshooting BEA WebLogic deployments

  -ms64m -mx64m

  -ms64m -mx256m

TIP:   Be sure to check the Release Notes for additional information about configuring WebLogic for exteNd Director.

Changing your deployment configuration

When you configure an exteNd Director application, you make choices based on the application server you plan to use. If you want to deploy the application to a different server later, there are several things to change. All changes can be made using exteNd Director editors.

    For details on making changes, see the procedures in Reconfiguring exteNd Director Projects.

The items you need to change are as follows:

About exteNd Director database tables

The exteNd Director database tables hold information that the subsystems need to persist.

NOTE:   The items listed are reserved for exteNd Director's use. This listing is provided for informational purposes only.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...