Utility Tools

CHAPTER 15

Archive Deployment

To make your J2EE application available to users, you deploy the archive on a J2EE server. This chapter describes how to deploy J2EE archives using the Novell exteNd Director development environment and includes the following topics:

• Supported J2EE servers

• Deployment types

• Deploying J2EE archives

• What happens when you deploy

• Deploying Web Services

• Undeploying archives

Supported J2EE servers

The exteNd Director development environment provides built-in support for deploying archives to the following J2EE servers:

    See the Novell exteNd Release Notes for the latest information on the supported server versions.

NOTE:   IBM WebSphere does not provide built-in support for direct deployment. You must use WebSphere's deployment tools.

Deployment types

To deploy the archives you generate in the exteNd Director development environment, you can use the following:

• Rapid deployment

• Production deployment

• External deployment tools

Rapid deployment

When developing, testing, and refining your application, you want fast turnaround—you want to make a change to your application and immediately see the result without having to redeploy the application. The exteNd Director development environment lets you do this using rapid deployment. You specify rapid deployment by simply checking a checkbox in the Deployment Settings dialog (described in Creating deployment settings). When you deploy the application, this uses the target server's native file system deployment facilities.

Rapid deployment is most useful for changes to Web applications that involve JSP pages, HTML pages, images, JARs in the WEB-INF\lib, or classes in the WEB-INF\classes directories. If you make changes to other application components (such as a WAR tag library or a deployment descriptor), exteNd Director automatically performs a full deployment.

    For more information about setting up a rapid deployment environment, see Creating deployment settings. For more information about the target server's native file system deployment, see What happens when you deploy.

exteNd Director can only support rapid deploy if this feature is supported by the application server vendor. The following table lists the J2EE servers that support a rapid deploy feature and the kind of archives that you can rapid deploy.

Production deployment

When you've completely tested your application and are ready to put it into production, you can deploy the application to the server by unchecking the rapid deploy checkbox in the deployment settings for the target server. exteNd Director uses the target server's native deployment tools to deploy the application in the appropriate production deployment directory.

External deployment tools

Alternatively, you can take your generated archives and deploy them outside of the exteNd Director development environment, using instead the deployment facilities provided by your J2EE server. That's because exteNd Director generates standard J2EE archives.

Deploying J2EE archives

To deploy a J2EE archive using the exteNd Director development environment, the archive must:

• Be properly structured according to the J2EE specification (see Archive contents)

• Reside in a project (see Projects and Archives)

You must supply:

• A server profile (see Server profile)

• Server-specific deployment information (see Server deployment information)

• Deployment settings (see Creating deployment settings)

The development environment requires:

• Access to the target server

• Permission to write to the server's deployment area

• Permission to write temporary files when deploying to a Novell exteNd Application Server or SilverStream eXtend Application Server

  exteNd Director invokes SilverCmd, which generates temporary files on disk. These files are created in the server's installation directory, unless you have defined a HOME environment variable. If you have a HOME variable defined, it must point to a reachable and writable location. The temporary file location is:

  Server	Home environment variable
  Novell exteNd Application Server	NOVELL_EXTEND_APPSERVER_HOME\.appsrv
  SilverStream eXtend Application Server	SILVERSTREAM_HOME\.silverstream

When all of these requirements are met, see Deploying a project.

Archive contents

Sun's J2EE specifications define how different J2EE archives must be packaged for deployment. Before you try to deploy, make sure that your archive meets these requirements. The following table briefly lists the requirements. For more detailed information, see the J2EE Blueprints at: java.sun.com/j2ee/docs.html.

    For more information, see J2EE Deployment Descriptor DTDs.

Server deployment information

Each J2EE server needs runtime information, and each has its own format for this information. The following table lists the deployment documents needed by each supported server:

When specifying server deployment information, you can override information in your J2EE deployment descriptors, enabling you to customize a particular deployment as needed.

Creating deployment settings

Before you can deploy a project, you need to define the project's deployment settings. They provide information about the server where you plan to deploy the project.

To create deployment settings:

1. Choose Project>Deployment Settings.

   NOTE:   If you are deploying to an exteNd application server and the project's current deployment plan is not associated with a server profile, you will be told that you need to specify one in the Deployment Settings dialog.

2. In the Server Profiles tab, specify the following information:

   Option	What to do
   Profile name	Select a server profile from the list or click New to create a new profile.     For more information on server profiles, see Server profile.
   Use this server profile as the default for all projects	Select this option to make the current server profile the default profile in new 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.

3. Select the Deployment Info tab.

4. Specify the following for servers that support rapid deployment:

   Option

   What to do

   Enable Rapid Deployment

   Check this box when you want to deploy the archive using the rapid deployment feature for testing. Uncheck it when you want to do a production deploy. What happens    When this checkbox is checked, exteNd Director writes files to the rapid deployment directory specified in the server profile. NOTE:   If you have not set a rapid deployment directory in the server profile, you are prompted for one. This directory is a location on disk where you want the server to write the deployment files and is defined by the application server vendor. Many servers require a specific directory; see Server profile for the list. Further action    exteNd Director manages updates to the deployment area on subsequent rapid deploys. You do not have to do any manual procedure (as you would have to when directly using the server's rapid deployment). When to use    Use rapid deployment during the development/test/refinement stage of your application development cycle. Do not use it when you deploy your application to a production environment.     For more information on rapid deployment and how each server supports this feature (plus any special requirements), see What happens when you deploy.

5. Specify server-specific information.

   For Novell exteNd application servers and SilverStream eXtend application servers, specify the following:

   Option	What to do
   Deployment Plan	Specify the file name and disk location of the deployment plan.
   Overwrite existing deployment	Check this box when you want the current deployment to overwrite any previously deployed objects of the same type and name. If you deselect this box and objects of the same name and type already exist on the server, the deployment will fail.
   Verbosity	Specify the level of informational messages to display. Values range from 0 (for no messages) to 5 (for the most messages).
   Ignore JSP compile errors	Applies only to WARs and to EARs containing WARs. Check this box when you want the deployment to ignore any errors when compiling JSP pages and to deploy only those items that build successfully. If this box is not checked and a compile error occurs, deployment fails.
   SilverCmd Flags	(Optional) Specify command-line arguments for the deployment command.     For more information on the deployment commands that are executed, see What happens when you deploy. If you specify multiple arguments, use spaces as the delimiters. If you want to pass VM arguments, you must precede them with +. For example: +Xmx256 All of the values entered here are appended to the end of the deployment command that gets constructed.

   For BEA WebLogic servers, specify:

   Option	What to do
   WebLogic Application Name	Specify the deployment name for your application; this is the name your users will use in the URL for the application. If this is a rapid deploy, this is the directory name under the deployment directory. The default is the project name.
   Generate Targets	Click this button to automatically create a list of components to deploy to the target servers specified in the server profile. The list is displayed in the Components and Targets text box.
   Components and Targets	Do one of the following: Accept the values created when the Generate Targets button is clicked. Edit the values created when the Generate Targets button is clicked. Manually type the names of the components and their target servers using proper WebLogic syntax.
   Deployment options	Choose one of these options: deploy—Deploys the application. Use this option when deploying the application for the first time. If rapid deploy is checked, this option performs a rapid deploy; otherwise, it performs a production deploy. update—Updates a deployed application. Use this option for all redeployments, updates to an already deployed archive, or to enable a disabled application. (Not available for all server versions.) undeploy—Disables the application with the option to delete it. list—Provides a list of all deployed applications on the server specified by the current project's server profile. user defined—Allows you to specify a WebLogic command. When this value is specified, exteNd Director uses only the command in the WebLogic options text field (described below).
   JVM options	Specify command-line arguments for the server's JVM using spaces to delimit the options. These values are appended to the end of the deployment command that gets constructed.
   WebLogic options	Specify server-specific options using spaces to delimit them. You must supply the complete command for the action you want the WebLogic server to perform. For example: -unprepare -name War23 Make sure that user defined (under Deployment options) is selected or exteNd Director ignores the values you enter in this text box. These values are appended to the end of the deployment command that gets constructed. exteNd Director does no error checking, but error messages returned by the server are displayed in the Output Pane.
   debug	Check this option when you want to see the debug information produced by the WebLogic deploy tool.

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

Deploying a project

To deploy a project:

1. Open the project.

   Any archive that you want to deploy must be defined in a project. If you created the archive using another IDE, you must create a project for it before you can deploy it.

2. Make sure you have the server-specific deployment information in the appropriate format and location for your target server.

       For more information, see Server deployment information.

3. Define the deployment settings for the project.

       For more information, see Creating deployment settings.

4. Select Project>Deploy Archive.

   NOTE:   The deployment fails if your server is not running.

What happens when you deploy

When you deploy a project, exteNd Director uses the deployment settings to determine the J2EE server. Then:

1. It compiles the Java files and creates an archive. (JSP files are compiled during deployment or when their URLs are invoked from a browser.)

2. When the compilation is successful, it calls the appropriate deploy command for the target server.

   The following table lists the deploy command that is called for each server:

   Server	Archive	Deploy command description
   Novell exteNd Application Server SilverStream eXtend Application Server	CAR	Standard/Production deploy: SilverCmd DeployCAR Rapid deploy: Not supported for CARs
   	EAR	Standard/Production deploy: SilverCmd DeployEAR NOTE:   To deploy individual modules from within an EAR, pass the -m option as a SilverCmd Flag. Rapid deploy: Supports the rapid deployment of WARs in the EAR. It works like this: When a JSP page, an HTML page, a CLASS file, or a JAR file in a WAR within the EAR changes, exteNd Director invokes the server's JSP/FS deployment. When other files in the EAR are changed (such as the EAR deployment plan, EAR deployment descriptor, EJB archive, client archive, WAR deployment plan, or WAR tag library), exteNd Director invokes the standard/production deployment. exteNd Director manages updates to the deployment area on subsequent rapid deploys (so you do not need to do any manual procedure that you might have to when directly using the server's rapid deployment).
   	EJB JAR	Standard/Production deploy: SilverCmd DeployEJB Rapid deploy: Not supported for EJBs
   	WAR	Standard/Production deploy: SilverCmd DeployWAR Rapid deploy: JSP/FS During the JSP/FS process: exteNd Director expands the WAR file in the server's /webapps/DBname/URL directory, where DBname is the name of the database containing the application deployed to the file system, and URL is the URL specified in the deployment plan for the application (if you have specified more than one, the first one is used). exteNd Director manages updates to the deployment area on subsequent rapid deploys (so you do not need to do anything manually that you might have to when directly using the server's rapid deployment, such as creating the RELOAD file). exteNd Director updates the <deployToFileSystem> attribute automatically when you specify a rapid deploy.
   BEA WebLogic	All supported archives	Standard/Production deploy: weblogic.deploy or weblogic.deployer (depending on the server version) Rapid deploy: The exteNd Director development environment uses the server's native utilities to provide rapid deployment of EARs, EJBs, and WARs. You'll need to enable WebLogic Auto-Deployment through the WebLogic Management console before performing a rapid deploy. For more information on setting Auto-Deployment, see your WebLogic documentation. During a rapid deploy, exteNd Director copies the modified files to the user-specified deployment directory and touches the REDEPLOY file.
   Apache Tomcat	WAR	Standard/Production deploy: copy Copies the archive to the server's \webapps directory You must restart the server after a standard deploy Rapid deploy: copy Explodes the archive then copies the contents to a deployment directory specified by the user On subsequent rapid deploys, only the changed files are copied to the deployment directory You do not need to restart the server after a rapid deploy

3. The target server's deployment command creates the appropriate deployment objects on the target server.

4. exteNd Director displays a message stating the status (success/failure) or any warning/error messages in the Output tab of the Output Pane.

Deploying Web Services

When you create a Web Service in the exteNd Director development environment by using the Web Service Wizard or by using the Novell exteNd Web Services SDK directly, a servlet is generated to handle access to that Web Service (from HTTP SOAP requests). As a result, a WAR is required to package your Web Services (one or more per WAR) for deployment to a J2EE server where they will run.

You deploy that WAR in the usual way (as described earlier in this chapter). In addition, you must make sure it has runtime access to the archives required by the Web Services SDK:

How you set up this access depends on the type of J2EE server you use:

If you deploy to one of the following servers, you must add the required JARs to the server's classpath. (Consult your server documentation to learn about adding to the classpath.)

• BEA WebLogic

• IBM WebSphere

• Apache Tomcat

If you deploy to the Novell exteNd Application Server or SilverStream eXtend Application Server there's no need to add the required JARs to the server's classpath as long as you include them in the WEB-INF/lib directory of your WAR. If you don't include the required JARs in the WAR, you must add them to the server's AGCLASSPATH environment variable or specify them with the classpathJars deployment plan element. (For more information about AGCLASSPATH and classpathJars, see your server's help.)

You can obtain the required JARs by copying them from the Novell exteNd tools\compilelib directory.

Undeploying archives

Depending on the deployment server, you can disable or delete deployed archives on the server from within the exteNd Director development environment.

exteNd Director doesn't directly perform the undeployment; it calls server facilities to do the work. So, for example, if a server supports deletion but not disabling of archives, then you can delete but not disable archives from the development environment.

Typically, disabling leaves the files on the server but makes them unavailable, and deleting physically removes the files from the server. However, since exteNd Director simply executes the server's undeployment facility, exactly what happens depends on the server. For example, undeploying an application that had been deployed with rapid deployment does not necessarily delete or rename the deployment directory; the server might just delete the references to that application from its metadata. See your server documentation for information about exactly what happens when you undeploy an archive.

Here's a summary of the server undeployment support provided in the exteNd Director development environment:

To undeploy an archive:

1. With the project open, select Project>Undeploy Archive.

   NOTE:   The menu item is disabled if the deployment server does not provide an undeploy feature.

   The dialog that displays depends on the type of server specified in your project's deployment settings:

   • If your deployment server supports both disabling and deleting archives, you are asked which action you want to perform

   • If your deployment server supports only disabling archives, you are asked to confirm the disabling action

   • If your deployment server supports only deleting archives, you are asked to confirm the deletion

2. Respond to the dialog.

   The archive is either disabled or deleted. You can see the commands issued by looking in the Output tab of the Output Pane.

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