JBoss Migration Guide

CHAPTER 3

Deploying an exteNd Director Project

This chapter provides information about creating, modifying, and deploying an exteNd Director project to a JBoss Application Server. It includes these sections:

 
Top of page

About the JBoss Deployment environment

Use the following table as a quick-reference to help you find the JBoss equivalent for the exteNd Application Server features you're accustomed to working with.

Topic

On the Novell exteNd Application Server use

On the JBoss Application Server use

Deployment tools

  • Director Designer

  • SilverCmd

  • Director Designer—Can be used for local deployments only. A local deployment is one where the JBoss server and Director Designer are on the same machine.

  • Native JBoss—Can be used for local and remote deployments. Copy the deployment archive (EAR, WAR, etc.) to the server's deploy directory. For example, to deploy to the default server, you'd copy the archive to:

    server\default\deploy

For more information    For more information, see Deploying to JBoss.

Deployment Plan/ Descriptors

  • Requires a deployment plan.

  • Generated automatically by the Director Designer and editable via the Deployment Plan Editor.

  • Requires application deployment descriptors. They are include:

    EAR—META-INF\jboss-app.xml

    WAR—WEB-INF\jboss-web.xml

    SAR—jboss-service.xml

    EJB—jboss.xml

  • DTDs are located in the JBoss \docs\dtd directory.

Director Designer generates the file that is appropriate for the archive type whenever you create a new project that specifies one of these realms: JBoss and JBossLDAP. For more information    For more information, see What happens when you use a JBoss realm.

If you modify an existing project, you'll need to manually create these files. See About the JBoss deployment descriptor entries for information about the required entries.

Hot deploy

Supported for all deployments.

Server does not require a shutdown.

Supported for all deployments.

Server does not require a shutdown.

Quick deploy

Supported by the Director Designer deployment tool.

Quick deploys when specified in the project's deployment settings.

Called Exploded Deployment.

  • Director Designer—Will deploy an exploded archive to the specified directory when the Quick deploy check box (under Deployment Settings) is checked.

  • Native JBoss—Copy the exploded archive to the server's deploy directory.

Undeploy

  • Director Designer

  • SilverCmd

  • SMC

  • Director Designer—Use to undeploy locally.

  • Native JBoss—Use to undeploy locally or remotely. Just delete the archive from the server's deploy directory.

 
Top of page

About the deployment steps

Use the table below as a checklist for deploying an exteNd Director project to the JBoss Application Server environment:

Step

What to do

Notes

1

Configure the JBoss environment

For more information    For more information, see Setting up the JBoss environment for an exteNd deployment.

2

Create or modify the exteNd Director project to deploy

For more information    For more information, see Setting up an exteNd Director project for a JBoss deployment.

3

Deploy

For more information, see Deploying to JBoss.

If you are migrating the project from another server, import any portal data you exported.

For more information    See the chapter on moving portal data in the Portal Guide.

For more information    For more information about moving from a test to production environment, see Developing exteNd Director Applications.

 
Top of page

Setting up the JBoss environment for an exteNd deployment

Before deploying an exteNd Director project to JBoss, make sure that you:

Step

What to do

Notes

1

Create a JBoss datasource file for your exteNd Director database.

For more information    For more information, see Working with databases.

2

Verify that the datasource's JDBC driver is in the JBoss server's lib directory.

On Linux, you'd copy the driver from this exteNd directory:

  opt/novell/extend5/mysql/jdbc

to a JBoss directory like this:

  /server/default/lib

On Windows, you'd copy the driver from this exteNd directory:

  \MySQL\jdbc\

to a JBoss directory like this:

  \server\default\lib

3

Make sure that the exteNd copies of these files are available to the Java runtime:

  • Phaos_Crypto_FIPS.jar

  • Phaos_Security_Engine.jar

  • Phaos_SSLava.jar

On Linux, copy the Phaos files from this exteNd directory:

  Common/jre/lib/ext

to the JRE directory:

  JDK/jre/lib/ext

On Windows, copy the files from this exteNd directory:

  Common\jre\lib\ext

to the JRE directory:

  JDK\jre\lib\ext

NOTE:   If you are developing on a Windows platform and deploying to a JBoss server running on UNIX, copy the Phaos_Crypto_FIPS_UNIX.jar from the Common\lib\other directory and rename it Phaos_Crypto_FIPS.jar.

4

For the all configuration only

Add an entry for the JBoss Castor.jar to the server's run.sh or run.bat file.

You'll find the JBoss Castor.jar in jboss/server/all/deploy/snmp-adaptor.sar.

NOTE:   If you don't add this you will encounter ClassCastExceptions because of conflicts between multiple versions of the Castor.jar.

On Linux, add the following right after the line: "JBOSS_ENDORSED_DIRS="$JBOSS_HOME/lib/endorsed"

  #####################################
  # Novell extend settings for all config #
  ###########################################
  if [ "$*" = "-c all" ]; then
  if [ "x$JBOSS_CLASSPATH" = "x" ]; then
  JBOSS_CLASSPATH=$JBOSS_HOME/server/all/deploy/snmp-adaptor.sar/castor.jar
  else
  JBOSS_CLASSPATH=$JBOSS_CLASSPATH:$JBOSS_HOME/server/all/deploy/snmp-adaptor.sar/castor.jar
  fi
  fi

On Windows, add the following right after the line: "JBOSS_ENDORSED_DIRS="$JBOSS_HOME/lib/endorsed"

  rem########################################
  rem#Novell extend settings for all config #
  rem#########################################
  if "%*" == "-c all" (
  if "%JBOSS_CLASSPATH%" == "" (
  set JBOSS_CLASSPATH=%JBOSS_HOME%\server\all\deploy\snmp-adaptor.sar\castor.jar
  ) else (
  set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%JBOSS_HOME%\server\all\deploy\snmp-adaptor.sar\castor.jar
  )
  )

5

(Optional) To enable contextual searching, configure Autonomy.

See the section on configuring your environment for conceptual searching in the Content Search Guide.

 
Top of page

Setting up an exteNd Director project for a JBoss deployment

The procedures that you'll follow for setting up your project for JBoss deployment vary depending on the type of project you are working with.

 
Top of section

Working with existing projects

If you are migrating an existing project from a different application server type to JBoss, you'll:

Step

Action

Notes

1

Backup your existing project

Export the portal data (such as container, shared, personal pages, and portlets).

For more information    See the chapter on moving portal data in the Portal Guide.

2

Change the project's security realm

Follow the procedure outlined in To change the project's security realm:.

3

Change the project's Framework Datasource specification

Follow the procedure outlined in To change the project's Director Framework Datasource for JBoss:.

4

Create a jboss-app.xml file for an EAR project or a jboss-web.xml file for a WAR project

The exteNd deployments require only the <loader-repository> element described in About the JBoss deployment descriptor entries.

For more information about the contents of the JBoss deployment descriptors in general, see your JBoss documentation.

5

Rebuild and archive the project

See the chapter on projects and archives in Utility Tools.

NOTE:   After you deploy the project on the JBoss application server, you'll need to import the portal pages and portlets that you exported in Step 1 above. See the chapter on moving portal data in the Portal Guide for instructions.

Procedures for changing existing projects

Procedure To change the project's security realm:

  1. With the project open, choose Project>Director>Configuration.

  2. Choose Directory.

    JBossRealmExisting

  3. Choose JBoss or JBossLDAP from the dropdown.

    Realm configuration

    Description

    JBoss

    Read and write access to the JBoss application server security realm.

    This realm uses the exteNd Director database as the users store.

    JBossLDAP

    Read and write access to the JBoss application server realm using an LDAP server.

    This realm authenticates the user through a JBoss JAAS module.

    If you choose this realm, click the Directory LDAP Options tab and complete that panel as well. For more information, see Developing exteNd Director Applications.

  4. Click OK.

    NOTE:   When you choose one of the JBoss realms, the Director Designer modifies the JBoss server's /conf/login-config.xml file. You can learn more about what it adds in the What happens when you use a JBoss realm.

Procedure To change the project's Director Framework Datasource for JBoss:

  1. With the project open, choose Project>Director>Configuration.

  2. Choose Framework.

    JBossDatasourceExisting

  3. Make sure the Director Framework Datasource is prefaced with the string java:/. For example:

      java:/ExpressPortal

    This corresponds to the <jndi-name> node in the name-ds.xml file described in Setting up an exteNd Director project for a JBoss deployment. It is necessary because JBoss puts all deployed datasources in the java domain of the JNDI tree.

 
Top of section

Working with new projects

There are two exteNd Director project specifications that require JBoss Application Server-specific entries. They occur when:

NOTE:   The instructions in this section describe just the panels where you'll make JBoss-specific choices. See Developing exteNd Director Applications for information about other project configuration options.

JBoss-specific new project specifications

Procedure To specify the new project's security realm:

For more information    For more information about the JBoss realms, see What happens when you use a JBoss realm.

Procedure To specify the new project's Director Framework Datasource:

What happens when you use a JBoss realm

When you choose one of the JBoss realms, the Director Designer:

About the JBoss deployment descriptor entries

When the JBoss deployment descriptors are created, entries are added for the <loader-repository> node. They are described in the following table:

Archive type

Deployment descriptor entry

WAR

In WEB-INF/jboss-web.xml:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.4//EN"
  "http://www.jboss.org/j2ee/dtd/jboss-web_4_0.dtd">
  <jboss-web>
  <class-loading java2ClassLoadingCompliance="true">
  <loader-repository>com.novell:loader=MyWar.war
  <loader-repository-config>java2ParentDelegation=true</loader-repository-config>
  </loader-repository>
  </class-loading>
  </jboss-web>

EAR

In META-INF/jboss-app.xml:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-app_4_0.dtd">
  <jboss-app>
      <loader-repository>com.novell:loader=MyEAR.ear
  <loader-repository-config>java2ParentDelegation=true</loader-repository-config>
      </loader-repository>
  </jboss-app>

About the <application-policy> node

The JBoss Application Server needs to know which JAAS module to use for logging an exteNd user in to JBoss. It uses the <application-policy> entry in the /conf/login-config.xml file to determine this. The Director Designer adds an <application-policy> node to the server's login-conf.xml file, at deployment time, when your project includes both of the following:

NOTE:   When the JBoss server and Director Designer are not on the same machine, the attempt to add the <application-policy> node fails and you must add it manually.

The Director Designer generates the <application-policy> node (per realm) as follows:.

Realm

Default <application-policy> node

JBoss realm

 
  <application-policy name="extend">
     <authentication>
     <login-module code="com.sssw.fw.server.jboss.jaas.LoginModule"
     flag="required" />
     </authentication>
  </application-policy>

JBossLDAP

 
  <application-policy name="extendLDAP">
     <authentication>
     <login-module code="com.sssw.fw.server.jboss.jaas.JndiLoginModule"
     flag="required" />
     </authentication>
  </application-policy>

The value that Director Designer uses for the <application-policy>'s name attribute is taken from the DirectoryService/jboss/application-policy property (located in the project's DirectoryService-conf\config.xml file). The value of this property is automatically set to extend or extendLDAP when a new project is created in one of the JBoss realms, or when the realm of an existing project is changed to one of the JBoss realms.

 
Top of page

Deploying to JBoss

After you've set up your JBoss environment and the exteNd Director project, you are ready to deploy.

NOTE:   To use the Director Designer to deploy to a JBoss server, the Director Designer must be installed on the same machine as the JBoss server.

This section describes the steps for deploying to both a local and remote JBoss application server.

Step

What to do

Notes

1

Build and archive the project

See the chapter on projects and archives in Utility Tools.

2

For a local deploy only

Create a JBoss server profile and deployment settings for your project

See the procedure To create JBoss deployment settings (for local deployments only):.

For a remote deploy only

Add an <application-policy> node to the server's login-config.xml for each project that you deploy

See About the <application-policy> node. The <application-policy> node you add should follow the same rules as Director Designer uses.

3

Deploy the archive

For local deployments, see the chapter on deploying a project in Utility Tools.

For remote deployments, copy the archive to the server's \deploy directory.

4

Test the deployment

Open a browser. Type the URL for the exteNd Director application context. For example:

  http://localhost:8080/ExpressPortal

Redeploying   When you redeploy a project to the JBoss all or default configurations, you might encounter a java.io.NotSerializableException. This message is informational only. If you want to prevent this error from occurring you can do the following before redeploying:

  1. Remove the server's tmp and work directories.

  2. Restart the server.

Procedure To create JBoss deployment settings (for local deployments only):

  1. In the Director Designer, choose Project>Deployment Settings.

    Option

    What to do

    Profile name

    Select a JBoss server profile from the list or click New to create a new profile.

    If you create a new profile, complete the fields as follows:

    • Server profile—Provide a meaningful profile name.

    • Server type—Select the JBoss entry.

    • Deployment tools directory—Browse to the \deploy directory for the server configuration that you want to deploy to.

    • Rapid deployment directory—Browse to the \deploy directory for the server configuration that you want to deploy to.

    • Server name—Specify the host name:port or the IP address.

    For more information    For more information on server profiles, see the chapter on deploying a project in Utility Tools.

    Use this server profile as the default for all projects

    Select this option to make the current server profile the default profile for your projects.

    User name and Password

    If you have a secure server, fill in the User name and Password text boxes with an authorized user name and password for the server.

  2. To enable rapid deployment, select the Deployment Info tab.

    Option

    What to do

    Enable Rapid Deployment

    Check this box when you want to deploy an exploded archive in the server's \deploy directory.

    NOTE:   This feature is recommended for testing.

  3. Click OK to store the deployment settings with the project file.


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