Programmer's Guide

Chapter 23 Deploying EJBs

The SilverStream Server supports Enterprise JavaBeans that comply with the EJB 1.1 specification (Moscone).

This chapter describes deployment considerations, provides an overview of the deployment process, and includes pointers to documents that describe how to use the SilverStream tools (both GUI and command-line) to complete the deployment tasks. This chapter includes these sections:

About deployment

To deploy EJBs on the SilverStream server, you must create a deployment plan. The deployment plan provides additional deployment information for SilverStream's EJB container. The deployment plan is an XML file that complies with the deploy_ejb.DTD located in the SilverStream/DTDs directory.

You can create the deployment plan graphically using SilverStream's Deployment Plan Designer, or manually using the text editor of your choice. Once you have the deployment plan, you can deploy the EJB JAR using the Deployment Plan Designer or the SilverCmd DeployEJB command. You can deploy the same EJB JAR multiple times with different deployment plans.

The deployment plan must include:

Information about the EJB JAR
Information about each EJB in the JAR

For the EJB JAR

The deployment plan must specify:

If the JAR is enabled or disabled
The mapping of roles to security principals (when security roles exist in the deployment descriptor)

For each EJB contained in the EJB JAR:

The deployment plan must specify:

The EJB's JNDI name

For container-managed entity beans:

The deployment plan must specify:

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

Changing the deployment descriptor at deployment time

The deployment descriptor and the deployment plan are two separate XML documents. You can change many of the attributes specified in the EJB JAR's deployment descriptor (if you use the IDE) before you deploy the EJB JAR.

For more information, see the chapter on the JAR Designer in the online Tools Guide.

Enabling the EJB JAR

You can only deploy an EJB JAR in an enabled state if the deployment information is complete. If the deployment information is not complete, SilverStream saves the deployment plan, but does not enable the JAR.

For more information, on enabling EJB JARs, see the chapter on the Deployment Plan Designer or the chapter on SilverCmd (specifically the DeployEJB command). Both chapters are included in the online Tools Guide. Once deployed, you can use the SMC to enable or disable the deployed object.

Mapping security roles

The security roles specified in the deployment descriptor must be mapped to actual entities in the operational environment. Suppose that the bean developer or application assembler has defined three security roles: Administrator, Manager, and EndUser. At deployment time, these roles must be mapped to actual security groups or individual users on the target server.

For more information, on mapping security roles, see the chapter on the Deployment Plan Designer or the chapter on SilverCmd (specifically the DeployEJB command). Both chapters are included in the online Tools Guide.

Specifying JNDI names for an EJB

The JNDI name is used by the container to register the bean within the JNDI namespace. Any code that calls the bean must "find" it first using the JNDI name. A JNDI name is required for each bean in the EJB JAR.

JNDI names must be unique within a server and across servers in a cluster. You should consider using a hierarchical structure for naming your beans. You might even want to include the company name (or initials) within the hierarchy to ensure that EJBs are unique. Some examples include:

  abccorp/samples/WineDemo/Customers 
  com/sssw/samples/BankDemo/SessionBeans/AddCustomer 
  com/sssw/samples/BankDemo/EntityBeans/Customer

The JNDI lookup for the previous examples would be:

  contextEnv.lookup("RMI/samples/WineDemo/Customers"); 
  contextEnv.lookup("RMI/com/sssw/samples/BankDemo/SessionBeans/ 
     AddCustomer"); 
  contextEnv.lookup("RMI/com/sssw/samples/BankDemo/EntityBeans/ 
     Customer");

respectively.

Mapping entity beans to a data source

For container-managed entity beans, you must specify the name of the database table to which the entity bean is bound. This is the primary table for the bean.

For more information, see the chapter on the Deployment Designer or the chapter on SilverCmd (specifically the DeployEJB command) for the steps required to enable the EJB JAR. Both chapters are included in the online Tools Guide.

Mapping an entity bean's persistent fields

At deployment time, you map a CMP entity bean's persistent fields to one of the following:

A column in the primary table
A column in a related table
A different EJB

For more information on using the tools to perform each of these mappings, see the chapter on the Deployment Plan Designer or the chapter on SilverCmd (specifically the DeployEJB command) for the steps required to enable the EJB JAR. Both chapters are included in the online Tools Guide.

Mapping persistent fields to fields in the primary table

You can map the persistent fields of each entity bean to a column in the primary table. (The primary table is the table to which the entity bean is mapped.)

SilverStream also allows you to map entity beans where a persistent field represents another object. For example, suppose an entity bean contains a persistent field called m_address. This field is an EmployeeAddress object, and it has the following fields:

m_street
m_city
m_state
m_zipcode

According to the EJB specification, the field's class must have a public constructor with public member variables that are primitive, well-known, Serializable or compound.

In SilverStream, when you map m_address, you actually map each of its constituent parts to a specific database column. The m_street field might map to the database column called street, the m_city field might map to the database column called city, and so on.

Persistent fields mapped to one or more fields in the primary table are read-write.

Mapping persistent fields to fields in related tables

You can also map the persistent fields to columns in a different table as long as the column is related to the primary table. Persistent fields mapped this way are read-only.

Mapping member variables to other beans.

You can map the persistent fields of one entity bean to the persistent fields of a different entity bean. To accomplish this:

The bean developer must declare the persistent field's type as the referenced bean's remote interface.
The referenced bean must be deployed in the same EJB JAR file.
At deployment time, you can map the persistent field(s) to the referenced bean instead of a database table.
The persistent fields of the referenced bean's primary key are mapped to database columns in the primary table.

Bean references are read-write.

SilverStream supports mapping only an individual bean reference. It directly supports many-to-one and one-to-one relationships. A one-to-many relationship would look like a Collection in the referring bean. You can only implement this programmatically.

Specifying the methods that do not modify fields

SilverStream provides this as an optional performance enhancement. Each time a method is called on an entity bean, the server checks all of the bean's persistent fields to see if any of them have been modified. If they have been modified, the server writes any changes to the database as necessary. If you specify that a particular method does not modify a field, then the server does not perform this check.

Delaying instantiation

SilverStream provides this as an optional performance enhancement. This option specifies how the server will retrieve and cache data during execution of the bean's finder methods. Bean's whose instantiation is delayed are known as "lazy beans".

Here are the possible scenarios:

Scenario

Description

You set delay instantiation to true, but the finder method is not part of a transaction context (an unspecified context)

The server ignores the setting.

When you call a finder method, the server retrieves the primary key and does not cache any of the data. If your bean requires subsequent use of this data, then the server must retrieve the data at that point.

You set delay instantiation to true, and the finder method is part of a transaction context

The server retrieves only the primary key for each of the finder methods.

Any subsequent method calls on that bean causes the server to access the database again to retrieve the data and populate the fields for the bean.

Although this causes an additional trip to the database, it can be more efficient in cases where the data is large, or the application is only interested in a single record. It allows the application to do some processing to determine which record it wants.

For applications that will only access a single bean, the initial load time for all of the beans might not be worth it.

You set delay instantiation to false, and the finder method is part of a transaction context

The server retrieves the primary keys, and also retrieves all of the values for all of the persistent mapped fields for each bean.

The server caches this data.

If the client makes subsequent method calls for any of the fields, the server will not need to retrieve any additional data from the database because it has cached all of the records.

Depending on your data, this might improve or degrade your performance. It might degrade performance if the bean has a lot of fields or the field's contain large amounts of data. For example, if the beans you are retrieving contain a BLOB field and you do not need access to all of the records, then this might not be the right strategy for your application.

Scenario	Description
You set delay instantiation to true, but the finder method is not part of a transaction context (an unspecified context)	The server ignores the setting. When you call a finder method, the server retrieves the primary key and does not cache any of the data. If your bean requires subsequent use of this data, then the server must retrieve the data at that point.
You set delay instantiation to true, and the finder method is part of a transaction context	The server retrieves only the primary key for each of the finder methods. Any subsequent method calls on that bean causes the server to access the database again to retrieve the data and populate the fields for the bean. Although this causes an additional trip to the database, it can be more efficient in cases where the data is large, or the application is only interested in a single record. It allows the application to do some processing to determine which record it wants. For applications that will only access a single bean, the initial load time for all of the beans might not be worth it.
You set delay instantiation to false, and the finder method is part of a transaction context	The server retrieves the primary keys, and also retrieves all of the values for all of the persistent mapped fields for each bean. The server caches this data. If the client makes subsequent method calls for any of the fields, the server will not need to retrieve any additional data from the database because it has cached all of the records. Depending on your data, this might improve or degrade your performance. It might degrade performance if the bean has a lot of fields or the field's contain large amounts of data. For example, if the beans you are retrieving contain a BLOB field and you do not need access to all of the records, then this might not be the right strategy for your application.

As you can see, this setting is application dependent. It is set to false by default.

Specifying Finder methods

A finder method defines a Where clause. You can define a finder method as:

A SilverStream expression

This expression is a standard SilverStream expression like those used for Link clauses on forms and pages.

For more information, see the chapter on expressions in the Programmer's Guide, or the EJB section of the online Application Techniques.
A method

These are referred to as method-style finders. You might use a method-style finder when:
- Arguments are compound
- Arguments require processing
- You want to perform additional validation or error checking
- You want to include Order by, Distinct, and result count limits

Writing method-style finders

Follow these steps to create a method-style finder in an entity bean when you have its source code.

Create a method in the bean's implementation. Name the method as though it were bean-managed even though it is container-managed, that is, it must be prefaced with ejbFind as in ejbFindMethodName().
Construct the Where clause programmatically.
Use the bean's context to get the bean's home object.
Cast the home to AgoEJBEntityHome.
Call the findByExpression() method.
At deployment, mark the method as method-style rather than expression-style.

The following code snippet illustrates this technique:

  public Collection ejbFindByEmployee(EmployeeRemoteI emp)  
     throws FinderException, RemoteException 
  { 
     // Get the employee ID 
     EmployeePK epk = (EmployeePK) emp.getPrimaryKey(); 
   
     // Construct the where clause 
     String where = "Tasks.TaskEmpID=" + epk.m_id; 
   
     // Get the EJB home object 
     AgoEJBEntityHome home = (AgoEJBEntityHome) 
      m_context.getEJBHome(); 
   
     // Call the findByExpression method to perform the actual query 
     return (Collection) home.findByExpression( 
        where, // where clause 
        null, // order-by clause 
        home.FIND_COLLECTION, // intended return type 
        false, // distinct 
        0);// max returned rows 
  }

For more information and additional examples of writing method-style finders, see the EJB section of the online Application Techniques.

Subclassing beans

You might need to subclass an EJB when:

You are installing a bean on the server, but do not have its source.
You want to map a persistent field to a column in a database, but the data you are writing must first be manipulated.

Suppose that the fields require data massaging because the values in the database do not match the values expected by the bean. For example, the bean might expect a value of 1/0 and the database expects a value of M/F. Or suppose that a bean member variable is a collection of references to other beans as in a one-to-many mapping.

You can still deploy these beans on SilverStream; however, at deployment time you will need to override the bean's ejbLoad() and ejbStore() methods to fill in the unmappable fields. It might require that you add additional fields to the subclass in order to have mappable fields and removing some fields from the original bean's list of container managed fields.

SilverStream's EJB Deployment tools

You can use SilverCmd or the Deployment Plan Designer in SilverStream's IDE to deploy EJB JARs. There are no restrictions, so you can use the tool that is most convenient for you. You might choose the IDE if you are more comfortable with a graphical tool; or SilverCmd if you are more comfortable using a command line or need to deploy the same bean on multiple servers.

What happens when you deploy an EJB JAR

Regardless of the tool that 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 objects and remote JARs.

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. 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 stand-alone 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 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.

Deploying EJBs

To deploy EJBs on the SilverStream Server you can use either the SilverStream IDE or the SilverCmd DeployEJB command. Regardless of the tool, the EJB JAR must reside on the server. You can put a JAR on the server in either of these ways:

Using the Main Designer choose the Upload JAR, ZIP, or EJB popup menu option. See the JAR Designer chapter in the online Tools Guide.
Using the SilverCmd ImportMedia command. For more information, see the SilverCmd chapter in the online Tools Guide.

Once you have imported it, the EJB JAR will be visible through the Designer. Imported JARs are indicated with a yellow icon instead of blue, which indicates JARs generated by SilverStream.

Using the SilverStream IDE

The Deployment Plan Designer in the SilverStream IDE provides the graphical EJB deployment tools. You use the Deployment tab of the JAR Designer to specify the additional deployment information. You can also change any of the existing information in the deployment descriptor.

For more information, see the chapter on the Deployment Plan Designer in the online Tools Guide.

Using SilverCmd

The SilverCmd DeployEJB command uses an input file (in XML format) to specify the deployment information. It is SilverStream-specific and maps the same attributes (like JNDI name, field mappings, and so on) described earlier in this chapter. The deployment information file has its own DTD (deploy_ejb.DTD) and its own example (deploy_ejb_sample.XML) in the SilverStream\DTDs directory.

Deploying using SilverCmd has the same result as deploying with the IDE: SilverCmd creates both a deployed object and a remote JAR file in the database. Once the DeployEJB command completes, you can see these files in the IDE.

For more information, see the section on DeployEJB in the chapter on SilverCmd in the online Tools Guide.

Exporting a SilverStream EJB JAR file

You can export a SilverStream EJB JAR file for use on another 1.1-compliant server using either the SilverStream IDE or the SilverCmd command-line tool.

For more information, see the chapter on the JAR Designer or the chapter on SilverCmd (specifically the PublishToFile command) for the steps required to export the EJB JAR. Both chapters are included in the online Tools Guide.