Tools Guide

CHAPTER 3    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 Workbench and includes the following topics:

• Workbench-supported J2EE servers

• Workbench deployment types

• Using Workbench to deploy J2EE archives

• What Workbench does when you deploy a project

• Deploying Web Services

• Undeploying archives

Workbench-supported J2EE servers

Workbench provides built-in support for deploying archives to the following J2EE servers:

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

Workbench deployment types

You can deploy the Workbench-produced archives using:

• Workbench rapid deployment

• Workbench production deployment

• Non-Workbench tools

Workbench 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. Workbench lets you do this using rapid deployment. You specify rapid deployment by simply checking a checkbox in Workbench's Deployment Settings dialog (described in Creating deployment settings). When you deploy the application, Workbench 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 (like a WAR tag library or a deployment descriptor), Workbench 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 Workbench does when you deploy a project.

Workbench 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.

Workbench 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. Workbench uses the target server's native deployment tools to deploy the application in the appropriate deployment directory.

Non-Workbench tools

Alternatively, you can take your Workbench-generated archives and deploy them outside Workbench with the deployment facilities provided by your J2EE server. Because the archives Workbench generates are standard, you can deploy them to any standard J2EE server.

Using Workbench to deploy J2EE archives

To deploy a J2EE archive using Workbench, the archive must:

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

• Reside in a Workbench project (see Projects and Archives)

Before Workbench can perform the deployment, you must supply:

• A server profile (see Server profile)

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

• Deployment settings (see Creating deployment settings)

Before Workbench can perform the deployment, Workbench must have:

• Access to the target server

• Permission to write to the server's deployment area

• Permission to write temporary files when deploying to a Novell or SilverStream application server: when deploying to one of these servers, Workbench 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 following table shows the temporary file location for each server.

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

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: http://java.sun.com/j2ee/docs.html.

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 Workbench-supported server:

Creating deployment settings

Before you can deploy a Workbench 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 a server profile before the Deployment Settings dialog can be displayed. Do so in the Edit Server Profiles dialog, then continue specifying the deployment settings.

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 Add to create a new profile.     For more information on server profiles, see Server profile.
   Save this profile as default	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 options 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. Uncheck it when you want to do a production deploy. What happens    When this checkbox is checked, Workbench 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    Workbench manages updates to the deployment area on subsequent rapid deploys. You do not have to do any manual procedure that you 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 and any special requirements, see What Workbench does when you deploy a project.

5. Specify server-specific information:

   For Novell 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 Workbench does when you deploy a project 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 Workbench constructs

   For BEA WebLogic servers, specify:

   Option	What to do
   WebLogic Application Name	Specify the deployment name for your application. If this is a rapid deploy, this is the directory name under the deployment directory. Workbench defaults to the project name.
   Generate Targets	Choose 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 selected. Edit the values created when the Generate Targets button is chosen. Manually type the name 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, Workbench uses only the command specified 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 constructed by Workbench.
   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 Workbench ignores the values you enter in this text box. These values are appended to the end of the deployment command constructed by Workbench. Workbench does no error checking, but error messages returned by the server will be displayed in the Workbench message area.
   debug	Check this option when you want to see the debug information produced by the WebLogic deploy tool.

   For IBM WebSphere servers, specify:

   Option	What to do
   Node Name	Specify the name of the Standard server node to install to
   JVM options	Specify command-line arguments for the server's JVM If you specify multiple arguments, use spaces as the delimiters The values entered here are appended to the end of the deployment command that Workbench constructs
   WebSphere options	Specify server specific options, using spaces to delimit them These values are appended to the end of the deployment command constructed by Workbench Workbench does no error checking, but error messages returned by the server will be displayed in Workbench's message area
   Precompile JSP	Click the checkbox (true) if you want to precompile any JSP pages before deploying to the server

   For Oracle9iAS servers, specify:

   Option	What to do
   Deployment Name	Specify the application deployment name
   Target Path	Specify the path on the server to deploy to
   JVM options	Specify command-line arguments for the server's JVM If you specify multiple arguments, use spaces as the delimiters The values entered here are appended to the end of the deployment command that Workbench constructs
   OC4J options	Specify server specific options using spaces to delimit them These values are appended to the end of the deployment command constructed by Workbench Workbench does no error checking, but error messages returned by the server will be displayed in Workbench's message area
   Website Name	Specify the name of the OC4J web-site.xml file containing the name of the Web site to bind this application to

   For SilverStream eXtend Application Servers, specify the following:

   Option	What to do
   SilverStream 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 Workbench does when you deploy a project 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 Workbench constructs

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

   OR

   Select Deploy to save the deployment settings with the project file and deploy the archive.

   If you select Deploy and you specified a user name, you are prompted for the password before deployment can continue.

To deploy a Workbench project:

1. Open the Workbench project.

   Any archive that you want to deploy must be defined in a Workbench project. If you created the archive using another IDE, you must create a Workbench 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.

   The first time you select Project>Deploy Archive, you must choose from a list of server profiles. Use New on the Server Profile dialog to create a server profile if you don't already have one.

What Workbench does when you deploy a project

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

1. Workbench 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, Workbench 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	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, Workbench 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), Workbench invokes the standard/production deployment. Workbench 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: Workbench 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). Workbench 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). Workbench 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: Workbench 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 Workbench will be able to perform a rapid deploy. For more information on setting Auto-Deployment, see your WebLogic documentation. During a rapid deploy, Workbench copies the modified files to the user-specified deployment directory and touches the REDEPLOY file.
   IBM WebSphere	All supported archives	Standard/Production deploy: seappinstall Rapid deploy: Workbench copies the modified files to the user-specified deployment directory. You must use the standard deploy process the first time you deploy. You can use the rapid deploy feature on subsequent deployments. If the changes to an EAR include changes to the WAR deployment descriptor, TLD files, or files located in WEB-INF\lib or WEB-INF\classes in the WAR, you'll need to restart the server to see the changes. If you remove a file from any of the archives within the EAR, you'll need to: Stop the server Remove the class from the following: WebSphereinstalldir\AppServer\temp\ machine_name\Default_Server\ applicationname Restart the server
   Oracle9iAS	All supported archives	Standard/Production deploy: admin.jar Rapid deploy: Workbench copies the modified files to the user-specified deployment directory. You must use the standard deploy process the first time you deploy. You can use the rapid deploy feature on subsequent deployments. For rapid deployment of EARs, the deployment directory specified must be the server's \applications directory. If you are updating an EAR and the updates include changes to the WAR deployment descriptor, TLD files, or files located in WEB-INF\lib or WEB-INF\classes in the WAR, you'll need to restart the server to see the changes.
   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: Rapid deployment is supported for EARs for Version 3.7.3 and later. It supports the rapid deployment of WARs in the EAR. It works like this: When a JSP page, HTML page, CLASS file, or JAR file in a WAR within the EAR changes, Workbench 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), Workbench invokes the standard/production deployment. Workbench 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: SilverCmd QuickDeployEJB (3.7.x only) You must use the standard deploy process the first time you deploy. You can use the rapid deploy feature on subsequent deployments.
   	WAR	Standard/Production deploy: SilverCmd DeployWAR Rapid deploy for Version 3.7.3 (and later): JSP/FS During the JSP/FS process: Workbench 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). Workbench 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). Workbench updates the <deployToFileSystem> attribute automatically when you specify a rapid deploy.
   SUN RI	EAR	Standard/Production deploy: deploytool 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 If the rapid deploy directory does not exist, Workbench creates it On subsequent rapid deploys, only the changed files are copied to the deployment directory You must restart the server after a rapid deploy in order to see your changes
   Jakarta 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. Workbench displays a message stating the status (success or failure) or any warning or error messages in the Deploy tab of the Output Pane.

Deploying Web Services

When you create a Web Service in Workbench by using the Web Service Wizard or by using jBroker^TM Web 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 following archives required by jBroker Web:

• jbroker-web.jar, which contains the jBroker Web API classes

• jaxrpc-api.jar and saaj-api.jar, which contain the Java API classes for XML-based RPC and SOAP processing

• xerces.jar or another XML parser

• If the WAR uses SOAP message handlers (an advanced JAX-RPC feature), it will also require the following archives: activation.jar, commons-logging.jar, dom4j.jar, jaxp-api.jar, and saaj-ri.jar

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

• Jakarta Tomcat

• Oracle9i

If you deploy to the Novell exteNd Application Server or the 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 Workbench compilelib directory.

Undeploying archives

Depending on the deployment server, you can disable or delete deployed archives from the server from within Workbench.

Workbench 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 Workbench.

Typically, disabling leaves the files on the server but makes them unavailable, and deleting physically removes the files from the server. However, since Workbench 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 is the undeployment support for the servers supported by Workbench:

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 that Workbench issues in the Deploy tab of the Output Pane.

	Tools Guide

Copyright © 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.