Deploying an EJB

The EJB deployment process consists of the following steps:

• Get the beans from the EJB developer. In the typical case the beans and their accompanying classes, including the home and remote interfaces and any classes dependent on the bean, have been compiled and put into a JAR file--one JAR file for each bean.

• Develop a deployment descriptor for each bean.

• Run the deployejb tool, which
  • reads the deployment descriptor and the bean JAR file

  • loads the bean classes into the Oracle8i database

  • publishes the bean home interface

• Make sure that the application developer has the information he or she needs about the bean remote interface and the name of the published beans.

Write the Deployment Descriptor

The enterprise bean deployer supplies a deployment descriptor for each EJB in the application.

To make it simpler to compose the deployment descriptor, there is a text form of the descriptor, which is described in this section. You can also use the Oracle8i JServer ejbdescriptor command-line tool to convert a text form deployment descriptor to the serialized class, or to convert back from the serialized object to a text file. The ejbdescriptor is documented in "ejbdescriptor".

Text Format

The text form of the session bean descriptor follows the conventions of Java code-- the descriptor has the syntax of a Java class. It always begins with a SessionBean keyword, which is followed by the fully-qualified class name of the bean. The body of the declaration contains a list of descriptor attributes and their values. For example:

SessionBean ejb.test.server.ExampleBeanImpl

{

    <attribute>=<value>

    ...

}

In this example, ejb.test.server is the name of the package that contains the implementation of the bean class ExampleBean.

There are three different kinds of bean attributes:

• Attributes of the bean itself, such as
  • its published name

  • the names of its home and remote interfaces

  • miscellaneous attributes that can apply only to the bean as a whole, such as SessionTimeout

• Each method can have a specific set of attributes of its own. Attributes specific to a bean method deal with security and transaction support. For example, you can specify that a method of a bean should run with a different identity (user or schema name) from other methods in the same bean. Or, you can set transaction properties on a method so that it runs with different transaction properties from the rest of the bean.

  Note that the transaction and security properties can apply to the bean as a whole, or can be specified on a method-by-method basis.

• Any environment properties to be passed to the bean.

The attributes of a session bean descriptor correspond to the attributes of the class javax.ejb.deployment.SessionDescriptor and its super class javax.ejb.deployment.DeploymentDescriptor.

Table 2-2 lists the attributes that can be used in the deployment descriptor.

Table 2-2 Deployment Descriptor Attributes

BeanHomeName

RemoteInterfaceClassName

Reentrant

SessionTimeout

StateManagementType

TransactionAttribute

IsolationLevel

RunAsMode

RunAsIdentity

AllowedIdentities

The example below shows a more complete deployment descriptor than in the example earlier in this chapter:

SessionBean ejb.test.server.DatabaseWorkImpl

{

  BeanHomeName = "test/dbwork";  // this is the published name of the bean

  RemoteInterfaceClassName = ejb.test.DatabaseWork;

  HomeInterfaceClassName = ejb.test.DatabaseWorkHome;



  AllowedIdentities = {SCOTT}; 



  SessionTimeout = 30;   // in seconds

  StateManagementType = STATEFUL_SESSION;



  RunAsMode = CLIENT_IDENTITY;



  TransactionAttribute = TX_REQUIRES_NEW;

  

  // Add any environment properties that the bean requires

  EnvironmentProperties {

    prop1 = value1;

    prop2 = "value two";

  }



  public ejb.test.EmpRecord getEmployee(int e) throws TestException{ 

    RunAsMode = CLIENT_IDENTITY;      

    AllowedIdentities = { SCOTT };

  }



  public void update(int e, double s) throws TestException{ 

    RunAsMode = SPECIFIED_IDENTITY;      

    AllowedIdentities = { OTTO };

  }

}

Create a JAR File

The deployejb command-line tool creates a JAR file to use on the client side to access the bean.

Publish the Home Interface

One of the requirements that a bean provider must meet is to make the bean's home interface available for JNDI lookup, so that clients can find and activate the bean. In JServer, this is done by publishing the bean home interface in an Oracle8i database. The deployejb command-line tool takes care of this you. It publishes the bean in the instance CosNaming namespace under the name that you specify in the BeanHomeName attribute of the deployment descriptor.

Dropping an EJB

Drop an EJB from the database by following these steps:

• Using the bean JAR file that contains the class files for the bean, run the dropjava tool to delete those classes from the database.

• Use the session shell tool to remove the bean home interface name from the published object name space.

See Chapter 6, "Tools" for documentation of the dropjava and session shell tools.

Handling Transactions

Enterprise JavaBeans are inherently transactional. In the normal, easiest-to-code cases, transaction support is handled for the bean by the EJB container. This way, you do not need to code explicit transaction methods in the bean, or call transaction services from the client.

EJBs have declarative transaction support. This means that the bean deployer can specify, in the deployment descriptor, the transaction attributes for a bean, or even for an individual method in a bean. For example, if the deployment descriptor for a bean declares that the bean has the transaction attribute TX_REQUIRES_NEW, then the bean container starts a transaction before each method call to the bean, and attempts to commit the transaction when the method ends.

TransactionAttribute

The bean deployer declares the transaction handling characteristics of a bean in the deployment descriptor. This is specified in the transaction attribute, which has six possible values:

• TX_NOT_SUPPORTED

• TX_REQUIRED

• TX_SUPPORTS

• TX_REQUIRES_NEW

• TX_MANADATORY

• TX_BEAN_MANAGED

"Transaction Management for EJBs" describes the semantics of these attribute values.

Access Control

The EJB deployment descriptor allows you to specify access control lists. Access control can be specified either on the entire bean, or on individual methods of the bean.

In the text form of the deployment descriptor, specify the AllowedIdentities attribute with a list containing usernames, roles, or a mixture of the two. Only users or users with the roles specified in the AllowedIdentities attribute can access the bean, or the methods that are restricted by the attribute. For example:

AllowedIdentities = {SCOTT};  // only SCOTT can access the bean

AllowedIdentities = {PUBLIC}; // all users can access the bean





public int Rmethod (int p1, double p2) throws TestException{ 

    RunAsMode = CLIENT_IDENTITY;      

    AllowedIdentities = { ROGERS };   // only ROGERS can invoke this method

}

When you specify method access control, the method must be a public business method of the bean, or the ejbCreate() method.

Transaction Isolation Level

The transaction isolation level attribute is not supported in this release. On the basis of recent informal communication from Sun Microsystems, it is likely that this attribute will not be supported in future EJB specifications, as part of the EJB descriptor.

Session Synchronization

An EJB can optionally implement the session synchronization interface, to be notified by the container of the transactional state of the bean. Use this interface to save the bean state in the database at transaction boundaries. "session Synchronization" describes this interface.

Deployment Steps

The format used to package EJBs is defined by the EJB specification. The format is adaptable--you can use it to distribute a single EJB or to distribute a complete server-side application made up of tens or even hundreds of beans. This section describes the steps that the EJB developer and the EJB deployer take to compile, package, and deploy an EJB. Oracle8i supplies a deployment tool, deployejb, that automatically performs most of the steps required to deploy an EJB. This tool is described in "deployejb". Deployejb deploys only one bean at a time.

To deploy an EJB, follow these four steps:

1. Compile the code for the bean. This includes:
   • the home interface

   • the remote interface

   • the bean implementation

   • all Java source files dependent on the bean implementation class (this dependency is normally taken care of by the Java compiler)

     Use the standard client-side Java compiler to compile the bean source files. A bean typically consists of one or more Java source files, and might have associated resource files.

     Oracle8i supports the Sun Java Developer's Kit version 1.1.6 compiler. You might be able to use another JCK-tested Java compiler to create EJBs to run in the Oracle8i server, but Oracle only supports JDK 1.1.6.

2. Write a deployment descriptor for the EJB. See Programming Restrictions for specific information about creating deployment descriptors.

3. Create a JAR file consisting of the interface and implementation class files for the bean: the home interface, the remote interface, and the bean implementation. If there are many other dependent classes and resource files, it is better to create a separate JAR file for these. This JAR file is used as an input file by deployejb.

4. Call the deployejb tool (see "deployejb") to load and publish the JAR'd bean.