Tools Guide
|
|
Tools Guide |
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 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.
You can deploy the Workbench-produced archives using:
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.
The following table lists the J2EE servers that allow you to use the Workbench rapid deploy feature and the kind of archives that you can rapid deploy with each:
|
Server |
EAR |
WAR |
EJB |
CAR |
RAR |
|---|---|---|---|---|---|
SilverStream eXtend Application Server (3.7.x, starting with 3.7.3) | |||||
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.
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.
To deploy a J2EE archive using Workbench, the archive must:
Be properly structured according to the J2EE specification (see Archive contents)
Reside in a SilverStream eXtend Workbench project (see Chapter 2, "Projects and Archives")
Before Workbench can perform the deployment, you must supply:
A server profile (see "Server profile" on page 24)
Server-specific deployment information (see Server deployment information)
Deployment settings (see Creating deployment settings)
Before Workbench can perform the deployment, Workbench must have:
Permission to write temporary files when deploying to a SilverStream server: When deploying to a SilverStream server, 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, the temporary files are created in %HOME%\.silverstream. So if you have a HOME environment variable defined, it must point to a reachable and writeable location.
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.
|
J2EE module |
Standard archive requirements |
|---|---|
|
| |
| |
| |
|
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:
|
J2EE server |
Archive |
Server deployment information |
|---|---|---|
Each type of archive uses an XML-based document called a deployment plan. The deployment plan can have any file name and can reside in any location outside the archive file. SilverStream defines a DTD for each archive type.
You use Workbench's Deployment Plan Editor to create and populate the deployment plan.
| ||
Each type of archive (except EAR) requires a special XML-based document. The EAR does not require a specific deployment document, but each individual module included in the EAR must have the appropriate WebLogic deployment document. | ||
|
| ||
Before you can deploy a Workbench project, you need to define the project's deployment settings. They provide information about the server on which you plan to deploy the project.
To create deployment settings:
Choose Project>Deployment Settings.
NOTE If you are deploying to a SilverStream 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.
In the Server Profiles tab, specify the following information:
|
Option |
What to do |
|---|---|
Select a server profile from the list or click Add to create a new profile.
| |
Select this option to make the current server profile the default profile in new projects. | |
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. |
Specify the following options for servers that support rapid deployment:
|
Option |
What to do |
|---|---|
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 not the same as the location for the server's deployment tools. It is a location on disk where you want the server to write the deployment files. Many servers require a specific directory; see "Server profile" on page 24 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.
|
Specify server-specific information:
For SilverStream eXtend Application Servers, specify the following:
|
Option |
What to do |
|---|---|
Specify the file name and disk location of the SilverStream deployment plan | |
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 | |
Specify the level of informational messages to display Values range from 0 (for no messages) to 5 (for the most messages) | |
Applies only to WARs and to EARs containing WARs Check this box when you want the deployment to ignore any errors when compiling and to deploy only those items that build successfully If this box is not checked and a compile error occurs, deployment fails | |
(Optional) Specify command-line arguments for the deployment command
If you specify multiple arguments, use spaces as the delimiters. If you want to pass VM arguments, then 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:
For IBM WebSphere servers, specify:
|
Option |
What to do |
|---|---|
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 |
Specify the name of the OC4J web-site.xml file containing the name of the Web site to bind this application to |
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:
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.
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.
Define the deployment settings for the project.
For more information, see
Creating deployment settings.
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.
When you deploy a project, Workbench uses the deployment settings to determine the J2EE server. Then:
Workbench compiles the Java files and creates an archive. (JSP files are compiled during deployment or when their URLs are invoked from a browser.)
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:
The target server's deployment command creates the appropriate deployment objects on the target server.
Workbench displays a message stating the status (success or failure) or any warning or error messages in the Deploy tab of the Output Pane.
When you create a Web Service in Workbench by using the Web Service Wizard or by using jBroker 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:
jaxrpc-api.jar and saaj-api.jar, which contain the Java API classes for XML-based RPC and SOAP processing
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.)
If you deploy to 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 the SilverStream eXtend Application Server Core Help.)
You can obtain the required JARs by copying them from the Workbench compilelib directory.
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:
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
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 © 2002, SilverStream Software, Inc. All rights reserved.