Facilities Guide

Chapter 1   J2EE Archive Deployment

This chapter describes how to deploy J2EE-compatible archive files to a SilverStream server. It covers these topics:

• Deploying J2EE application client archives

• Deploying EJB archives

• Deploying Web Archives (WARs)

• Deploying Enterprise Archives (EARs)

• Managing deployed objects

Deploying J2EE application client archives

You use application client archive files to contain J2EE application clients (client classes and supporting files) for deployment to a J2EE server.

    To learn about J2EE application clients, see the chapter on writing J2EE application clients in the Programmer's Guide of the server's Classic Development Help.

To deploy an application client archive file to your SilverStream server:

1. Package the Java classes that implement the application client in a J2EE-compatible JAR file.

2. Write a SilverStream application client deployment plan.

3. Run SilverCmd DeployCAR.

Packaging application clients

The application client archive must comply with Sun's J2EE specification. For more information, see:

• Java 2 Platform Enterprise Edition Specification, v1.2, Chapter 9, "Application Clients"

• J2EE Blueprints

    These publications are available from the Sun Java Web site at:

  http://java.sun.com/j2ee/docs.html

Writing an application client deployment plan

The application client deployment plan includes information that the SilverStream server needs to provide the appropriate runtime environment for an application client. You supply this deployment plan as an option to the SilverCmd DeployCAR command.

Application clients that reference EJBs, environment entries, or other external resource references (such as databases) must have a deployment plan. Application clients without external references do not require one.

Requirements of the plan   Your application client deployment plan must be an XML file based on the client JAR deployment plan DTD that SilverStream provides:

  deploy_car.dtd

Your plan must:

• Include a corresponding DOCTYPE statement

• Comply with the structure documented by this DTD

    For details on writing a deployment plan XML file that meets these requirements, see the Deployment Plan DTDs chapter in the Facilities Guide:

To learn about	See
The DOCTYPE statement and structure for your application client deployment plan	Client JAR deployment plan DTD
A sample application client deployment plan you can follow	About the deployment plan DTDs
Where to find the DTD file	About the deployment plan DTDs

Editing the plan   To create and edit your application client deployment plan, you can use an XML editor or text editor of your choice.

Overview of the plan   The application client deployment plan can specify:

• Environment entries

• Bean references

• Resource references

Running SilverCmd DeployCAR

Once you have the archive file and the deployment plan, you can deploy the client application to a SilverStream server using SilverCmd DeployCAR. It deploys the archive file to the Jars subdirectory of the EJB Jars & Media directory on the SilverStream server. Once the deployed object is on the server, any application client can access it using SilverJ2EEClient. All application components are automatically available for client requests; you do not need to restart the server.

    For more information on:

• Using SilverCmd DeployCAR, see DeployCAR

• Using SilverJ2EEClient, see SilverJ2EEClient and SilverJRunner

Deploying EJB archives

You use EJB archive files to contain Enterprise JavaBeans (session beans, entity beans, and supporting files) for deployment to a J2EE server.

    To learn about EJBs, see the part on developing Enterprise JavaBeans in the Programmer's Guide of the server's Classic Development Help.

To deploy an EJB archive file to your SilverStream server:

1. Package the Java classes that implement the beans, the remote and home interfaces, the primary key classes (if necessary), and any other utility classes in a J2EE-compatible JAR file.

2. Write a SilverStream EJB deployment plan.

3. Run SilverCmd DeployEJB or deploy from the graphical SilverStream Deployment Plan Designer.

Packaging EJB components

The EJB archive must comply with Sun's Enterprise JavaBeans Specification, version 1.1.

    This publication is available from the Sun Java Web site at:

  http://java.sun.com/j2ee/docs.html

SilverStream support   The SilverStream server provides a complete set of development, packaging, and deployment tools for Enterprise JavaBeans.

For information on	See
Developing EJBs in SilverStream	The chapter on using EJBs in the Programmer's Guide of the server's Classic Development Help
Packaging EJBs using SilverStream tools	The JAR Designer chapter in the Tools Guide of the server's Classic Development Help

Writing an EJB deployment plan

The EJB deployment plan includes information that the SilverStream server's EJB container needs to provide the appropriate runtime environment for the beans. The deployment plan:

• Resolves any environment entry, resource, or bean reference dependencies

• Provides information about role mapping for the target operational environment

• Provides the container with other SilverStream-specific runtime information

Requirements of the plan   Your EJB deployment plan must be an XML file based on the EJB JAR deployment plan DTD that SilverStream provides:

  deploy_ejb.dtd

Your plan must:

• Include a corresponding DOCTYPE statement

• Comply with the structure documented by this DTD

    For details on writing a deployment plan XML file that meets these requirements, see the Deployment Plan DTDs chapter in the Facilities Guide:

To learn about	See
The DOCTYPE statement and structure for your EJB deployment plan	EJB JAR deployment plan DTD
A sample EJB deployment plan you can follow	About the deployment plan DTDs
Where to find the DTD file	About the deployment plan DTDs

Editing the plan   To create and edit your EJB deployment plan, you can use either of the following:

• An XML editor or text editor of your choice

• The SilverStream Deployment Plan Designer (for EJB JARs that reside on the SilverStream server or those built using InLine Standard)

  The Deployment Plan Designer automatically includes the appropriate DOCTYPE statement and constructs XML that complies with the EJB JAR deployment plan DTD.

      For more information, see the chapter on the Deployment Plan Designer in the Tools Guide of the server's Classic Development Help.

Overview of the plan   The following table summarizes the information you can include in the EJB deployment plan:

For this component	The plan specifies
EJB JAR	Enabled or disabled Mapping of security roles to principals in the target environment (when security roles are specified in the deployment descriptor)
Each EJB (regardless of type)	The JNDI name Whether it is secured using SSL, and if so, what cipher suites it supports Resource references EJB references Environment entries
Stateless session beans	The size of the instance pool (if any)
Container-managed entity beans	The data source for each bean The data mapping for each persistent field The mapping of finder methods to SilverStream expressions or existing methods Whether to delay instantiation of the EJB Which methods do not modify database fields

Deploying an EJB JAR

After you package your EJB components in the archive file and create the deployment plan, you are ready to deploy the EJB JAR using either the SilverCmd DeployEJB command or the graphical Deployment Plan Designer.

What happens when you deploy an EJB JAR

Regardless of the tool you use to deploy the EJB JAR, the output of the deployment process is the same. At deployment time, the SilverStream server constructs a deployed object and a remote EJB JAR in the SilverStream database. The original EJB JAR is not actually deployed; it just provides the raw materials for the construction of the deployed object and remote JAR.

The deployed object includes the implementation classes for the bean's remote and home interfaces. It is used only by the SilverStream server.

The remote JAR file includes stub or reference classes that you can use to call the server-side implementation classes. For convenience, the remote JAR also includes each bean's home and remote interface and any classes directly referenced by them. For example, it includes any classes referenced as parameters or return values. In general, the remote JAR includes any of the classes a caller needs to use the bean.

All clients should use the remote JAR. This includes SilverStream clients within the same server, forms served to SilverJRunner by the same server, SilverStream clients within another SilverStream server, and standalone Java programs. You need to include this remote JAR in SilverStream forms, pages, and business objects. You need to add this JAR to your path if you are accessing EJBs from an external client.

    For more information on:

• Using SilverCmd DeployEJB, see DeployEJB

• Deploying EJB JARs using the Deployment Plan Designer, see the chapter on the Deployment Plan Designer in the Tools Guide of the server's Classic Development Help

Restructuring EJB JAR files after deployment

If you deploy an EJB JAR then later restructure the EJB JAR file (or restructure a utility JAR file referenced by the EJB JAR), note the following:

If you	Then you must
Restructure your EJB JAR by making any of the following changes: By creating a utility JAR and changing the EJB JAR's manifest class-path attribute to refer to the utility JAR By removing a utility JAR and removing the reference to it in the EJB JAR's manifest class-path attribute By creating an EJB client JAR and adding an <ejb-client-jar> tag to the EJB JAR's deployment descriptor By removing an EJB client JAR and removing the <ejb-client-jar> tag from the EJB JAR's deployment descriptor	Do the following: Resave and redeploy the EJB JAR. Resave any objects (such as pages, servlets, or forms) that reference the EJB remote JAR. Resave and redeploy any EARs or WARs that reference the EJB remote JAR in their deployment plans. (Rebuilding the application database will not accomplish this.)
Restructure a utility JAR referenced by the EJB by making any of the following changes: By creating a sub-utility JAR and changing the utility JAR's manifest class-path attribute to refer to the sub-utility JAR By removing a sub-utility JAR and removing the reference to the sub-utility JAR in the utility JAR's manifest class-path attribute

Deploying Web Archives (WARs)

A Web Archive file is a logical grouping of static HTML pages, servlets, JavaServer Pages (JSPs), and other resources (images, sounds, and so on) that comprise a complete application.

    To learn about JSPs, see the chapter on using JavaServer Pages in the Programmer's Guide of the server's Classic Development Help.

To deploy a Web Archive file to your SilverStream server:

1. Package the JSP source files for the application (these can include standard servlet classes and other supporting Java components, HTML documents, images, and any other files required by the application) in a J2EE-compatible WAR file.

2. Write a SilverStream WAR deployment plan.

3. Run SilverCmd DeployWAR.

Packaging a Web application

The WAR must comply with Sun's Java Servlet Specification, v2.2.

    This publication is available from the Sun Java Web site at:

  http://java.sun.com/j2ee/docs.html

Writing a WAR deployment plan

The WAR deployment plan includes information about the contents of the WAR file and how it should be managed in the SilverStream server environment. You supply this deployment plan as an option to the SilverCmd DeployWAR command.

Requirements of the plan   Your WAR deployment plan must be an XML file based on the WAR deployment plan DTD that SilverStream provides:

  deploy_war.dtd

Your plan must:

• Include a corresponding DOCTYPE statement

• Comply with the structure documented by this DTD

    For details on writing a deployment plan XML file that meets these requirements, see the Deployment Plan DTDs chapter in the Facilities Guide:

To learn about	See
The DOCTYPE statement and structure for your WAR deployment plan	WAR deployment plan DTD
A sample WAR deployment plan you can follow	About the deployment plan DTDs
Where to find the DTD file	About the deployment plan DTDs

Editing the plan   To create and edit your WAR deployment plan, you can use an XML editor or text editor of your choice.

Overview of the plan   The WAR deployment plan can specify:

• One or more URLs for the WAR file

• Whether the WAR file is enabled or disabled

• Mappings for deployment descriptor values such as environment variables, EJB references, resource references, and role references

Deploying a WAR file

After you package your Web application components in the archive file and create the deployment plan, you are ready to deploy the WAR using the SilverCmd DeployWAR command.

What happens when you deploy a WAR

DeployWAR deploys a WAR file to a SilverStream server. As part of the deployment process, DeployWAR compiles all of the JSPs in the WAR into Java source files and then compiles these Java sources. It adds the result to the WAR file and uploads the WAR file to the server. (It does not include the Java source files in the WAR.)

    For more information on using SilverCmd DeployWAR, see DeployWAR.

Deploying Enterprise Archives (EARs)

An Enterprise Archive (EAR) represents a J2EE application rather than a single J2EE module. It's a collection of one or more of the J2EE deployable modules described earlier in this chapter (application clients, EJBs, WARs), packaged in a JAR file with the .EAR file extension.

To deploy an Enterprise Archive file to your SilverStream server:

1. Package the application components (application client JAR files, EJB JAR files, WAR files) in a J2EE-compatible EAR file. Note that each component (and the EAR itself) must include a deployment descriptor.

2. Write a SilverStream EAR deployment plan.

3. Run SilverCmd DeployEAR.

Packaging an enterprise application

The following diagram shows how the components are combined to create an EAR before deployment:

The EAR must comply with Sun's J2EE specification. For more information, see Java 2 Platform Enterprise Edition Specification, v1.2, Chapter 8, "Application Assembly and Deployment".

    This publication is available from the Sun Java Web site at:

  http://java.sun.com/j2ee/docs.html

Writing an EAR deployment plan

An EAR deployment plan provides a top-level view of the application's contents as well as the details for each J2EE deployable module (application client, EJB, WAR) that will be contained in the EAR. It's really a concatenation of the deployment plans for each of the J2EE modules it contains.

You create the EAR deployment plan by copying the elements from these module deployment plans into it. (See the appropriate sections in this chapter for discussions of the other deployment plans.)

Requirements of the plan   Your EAR deployment plan must be an XML file based on the EAR deployment plan DTD that SilverStream provides:

  deploy_ear.dtd

Your plan must:

• Include a corresponding DOCTYPE statement

• Comply with the structure documented by this DTD

    For details on writing a deployment plan XML file that meets these requirements, see the Deployment Plan DTDs chapter in the Facilities Guide:

To learn about	See
The DOCTYPE statement and structure for your EAR deployment plan	EAR deployment plan DTD
A sample EAR deployment plan you can follow	About the deployment plan DTDs
Where to find the DTD file	About the deployment plan DTDs

Editing the plan   To create and edit your EAR deployment plan, you can use an XML editor or text editor of your choice.

Running SilverCmd DeployEAR

DeployEAR performs these tasks:

1. Opens the EAR file and extracts all of the files to a local temporary directory

2. For each application client archive, EJB archive, or Web archive, DeployEAR performs the corresponding SilverCmd DeployXXX command to deploy that archive to the server

    For more information on using SilverCmd DeployEAR, see DeployEAR.

Managing deployed objects

You can perform the following on a J2EE deployed object:

• Shutdown and restart

• Enable and disable

• Delete

Shutting down and restarting deployed objects

Shutting down a deployed object makes the object inactive. After a server restart, the deployed object will be active again.

    For information on shutting down and restarting an EJB object, see the chapter on Maintaining the Server in the Administrator's Guide.

NOTE   You cannot shut down or restart EARs, WARs, or application clients.

Enabling and disabling deployed objects

When you disable a deployed object, you make it inactive (that is, clients cannot access it). After a server restarts, the object is still disabled. It remains disabled until specifically enabled.

EJBs   You can disable a deployed EJB using:

• The SMC

• SilverCmd DeployEJB

    For more information on enabling and disabling an EJB deployed object using the SMC, see the chapter on Maintaining the Server in the Administrator's Guide.

WARs and EARs   You can disable WARs and EARs by setting the deployment plan <isEnabled> to false and then redeploying the archive. You cannot disable or enable a WAR or EAR using the SMC.

Deleting deployed objects

Deleting a deployed object removes it from the SilverStream server. A deleted item must be redeployed before it is accessible by any clients. You can delete an item in one of these ways:

• Using the SilverCmd Delete command (see Delete)

• Using the SilverStream Designer

To delete a deployed object in the SilverStream Designer:

1. Open the SilverStream Designer and access the EJB Jars & Media directory.

2. Choose the deployed object to delete.

3. Press Delete.

Facilities Guide

Copyright © 2001, SilverStream Software, Inc. All rights reserved.