Deploying an EJB

The EJB deployment process consists of the following steps:

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

2. Develop the EJB deployment descriptor for each bean.

3. Create the Oracle-specific deployment descriptor.

4. Run the deployejb tool, which:
   1. reads the deployment descriptor and the bean JAR file

   2. maps the logical names defined in the EJB deployment descriptor to existing JNDI names and database tables

   3. loads the bean classes into the Oracle8i database

   4. publishes the bean home interface

5. Make sure that the application developer has the information necessary about the bean remote interface and the name of the published beans.

   Note: The deployment process is the same for iAS as it is for Oracle8i JServer. You simply have to provide the correct server for the deployment. You can choose to either deploy within the middle-tier or the database backend. If deploying to the middle-tier, you must have either an iCache or Oracle8i JVM installed in this tier. Then, pass the URL for the installed iCache or JVM to the command-line tools.

Deployment Steps

The format used to package EJBs is defined by the EJB specification. 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 necessary to deploy an EJB. The deployejb tool deploys only one bean at a time. This tool is described in Oracle8i Java Tools Reference.

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 Microsystems Java Developer's Kit compiler versions 1.1.6 or 1.2. Alternatively, you might be able to use another JCK-tested Java compiler to create EJBs to run in the Oracle8i server.

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

3. Write the Oracle deployment mapping file.

4. Create a JAR file containing the interface and implementation class files--the home interface, the remote interface, and the bean implementation--for the bean. If you have other dependent classes and resource files, it is better to create a separate JAR file for these. The deployejb tool uses this JAR file as an input file.

5. Call the deployejb tool (see Oracle8i Java Tools Reference for information on deployejb) to load and publish the JAR'd bean.

Write the Deployment Descriptor

With EJB 1.1, the deployment descriptor is now defined using XML. Sun Microsystems's provides the DTD file, which describes the required entries for defining the bean and application. The deployment descriptor was designed to contain logical names--that is, names that do not necessarily match the true name of the object loaded in JServer. These logical names are mapped to existing names through a companion deployment file--the Oracle deployment mapping file. The Oracle deployment mapping file can map the logical bean name to an existing JNDI name and map any container-managed entity bean fields to existing database columns.

Alternatively, if you use the actual JNDI and database column names within the XML deployment file, the Oracle deployment map file will be created for you automatically by deployejb.

Note: Since this chapter discusses session beans, the only fields discussed here will pertain to session beans. For a full description of the XML elements, see either Appendix A, "XML Deployment Descriptors" or the "Deployment Descriptor" chapter within the EJB 1.1 specification, located on http://www.javasoft.com.

The following example shows the sections necessary for the Employee example. This example uses logical names within the XML deployment descriptor that map to JNDI names within the Oracle deployment map file.

Example 2-1 XML Deployment Descriptor for Employee Bean

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems Inc.//DTD Enterprise JavaBeans 1.1
   //EN" "ejb-jar.dtd">
<ejb-jar>
   <enterprise-beans>
      <session>
         <description>Session Bean Employee Example</description>
         <ejb-name>Employee</ejb-name>
         <home>employee.EmployeeHome</home>
         <remote>employee.Employee</remote>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <session-type>Stateful</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>
   <assembly-descriptor>
      <security-role>
         <description>Public</description>
         <role-name>PUBLIC</role-name>
      </security-role>
      <method-permission>
         <description>public methods</description>
         <role-name>PUBLIC</role-name>
         <method>
            <ejb-name>EmployeeBean</ejb-name>
            <method-name>*</method-name>
         </method>
      </method-permission>
      <container-transaction>
         <description>no description</description>
         <method>
            <ejb-name>EmployeeBean</ejb-name>
            <method-name>*</method-name>
         </method>
         <trans-attribute>Supports</trans-attribute>
      </container-transaction>
    </assembly-descriptor>
</ejb-jar>

The following sections describes each of the pieces of the XML deployment descriptor:

XML Version Number

<?xml version="1.0"?>

DTD Filename

<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems Inc.//DTD Enterprise JavaBeans 1.1
//EN" "ejb-jar.dtd">

JAR file

The first element to be declared is the <ejb-jar> element. Within this element, you define two sections: the <enterprise-beans> section and the <assembly-descriptor> section. The <enterprise-beans> section defines the bean. The <assembly-descriptor> section defines the application's security and transaction attributes.

<ejb-jar>                            //Start of JAR file descriptor
 <enterprise-beans>                  //EJB Descriptor section
 ...                                 //Bean definition
 </enterprise-beans>
 <assembly-descriptor>               //Application Descriptor section
 ...                                 //Transaction and security definition
 </assembly-descriptor>
</ejb-jar>

Enterprise JavaBeans Element

The beans are described within the <enterprise-beans> element. This element contains information such as the type of bean, the home interface name, the remote interface name, and the bean class name.

The following segment shows the following:

• The bean is a session bean, denoted by the <session> element.

• The logical name for this bean is Employee, defined within the <ejb-name> element.

• The home, remote, and bean class names are within the employee package and are EmployeeHome, Employee, and EmployeeBean respectively.

• All session beans within JServer are stateful.

• The transaction is managed by the container, not by the bean.

     <enterprise-beans>
        <session>
           <description>Session Bean Employee Example</description>
           <ejb-name>Employee</ejb-name>
           <home>employee.EmployeeHome</home>
           <remote>employee.Employee</remote>
           <ejb-class>employee.EmployeeBean</ejb-class>
           <session-type>Stateful</session-type>
           <transaction-type>Container</transaction-type>
        </session>
     </enterprise-beans>
  

Assembly Descriptor Element

The <assembly-descriptor> element describes the security and transaction attributes for the application.

• For security, you must define the roles used within this application in the <security-role> element. These roles are assigned to certain methods within the bean within the <method-permission> element. In this example, the Employee bean allows all methods to be accessed within PUBLIC.

• For transactions, you define the type of transaction support necessary for each method within the <container-transaction> element. In this example, all methods require the Supports transactional attribute.

     <assembly-descriptor>
        <security-role>
           <description>Public</description>
           <role-name>PUBLIC</role-name>
        </security-role>
        <method-permission>
           <description>public methods</description>
           <role-name>PUBLIC</role-name>
           <method>
              <ejb-name>EmployeeBean</ejb-name>
              <method-name>*</method-name>
           </method>
        </method-permission>
        <container-transaction>
           <description>no description</description>
           <method>
              <ejb-name>EmployeeBean</ejb-name>
              <method-name>*</method-name>
           </method>
           <trans-attribute>Supports</trans-attribute>
        </container-transaction>
      </assembly-descriptor>
  

Create the Oracle Deployment Map File

If you had declared the true JNDI name within <ejb-name>, you do not have to create an Oracle deployment map file. This example used a logical name, Employee, within the XML deployment file. In this example, the JNDI name for Employee is /test/EmployeeBean.

In the Oracle deployment map file, you have the following structure:

1. Headers for XML version and DTD file.

2. EJB logical name mapped to JNDI name.

   In this example, the logical name defined within <ejb-name>--Employee--is mapped to "/test/EmployeeBean" within the <jndi-name> element.

3. The identity that this bean will run under.
   1. The <run-as> element defines the identity that the bean runs under within the <mode> element. The possible values can be the following:

   • CLIENT_IDENTITY--The bean runs as the client.

   • SPECIFIED_IDENTITY--The bean runs as the specified identity. This identity is defined in a <security-role> element. See Appendix A, "XML Deployment Descriptors" for details.

   • SYSTEM_IDENTITY--The bean runs as the DBA or ROOT for the server. For an Oracle8i server, the bean would run as SYS.

   • The <method> element under the <run-as> element defines the methods that run under the <mode> identity.

   In this example, all methods within the EmployeeBean run as the client.

   Example 2-2 Oracle Deployment Map File for Employee

   <?xml version="1.0"?>
   <!DOCTYPE oracle-descriptor PUBLIC "-//Oracle Corporation.//DTD Oracle 1.1//EN"
   "oracle-ejb-jar.dtd">
   <oracle-descriptor>
     <mappings>
       <ejb-mapping>
         <ejb-name>Employee</ejb-name>
         <jndi-name>/test/EmployeeBean</jndi-name>
       </ejb-mapping>
     </mappings>
     <run-as>
       <description>no description</description>
       <mode>CLIENT_IDENTITY</mode>
       <method>
         <ejb-name>EmployeeBean</ejb-name>
         <method-name>*</method-name>
        </method>
     </run-as>
   </oracle-descriptor>
   

Create a JAR File

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

 deployejb -user scott -password tiger -service sess_iiop://dbserver:2481:orcl \
  -descriptor employee.xml -oracledescriptor oracle_employee.xml \

  -temp /tmp/ejb -generated empClient.jar employee.jar

One of the tasks that the deployejb tool performs is to create a JAR file with the required stubs and skeletons, which is used by the client at execution time. Unless this JAR file name is specified in the <ejb-client-jar> element in the XML deployment descriptor, the default name for this JAR file is server_generated.jar. This JAR file must be included in the CLASSPATH for client execution.

Note: If your application uses any circular method references between beans, you will have to load the referred bean first using loadjava, then invoke deployejb for the JAR file. A circular method reference is when any method in bean A references a method in bean B and any method within bean B references any method in bean A. Even though they are different methods, the loading resolution fails when it cannot find the referenced bean already loaded within the database. If you load bean B using loadjava, the load resolution succeeds.

Publish the Home Interface

A bean provider must make the bean's home interface available for JNDI lookup so that clients can find and activate the bean. However, when you create the JAR file with the deployejb command-line tool, this tool publishes the bean in the JNDI namespace under the <jndi-name> element name that you specify in the Oracle deployment mapping file.

Dropping an EJB

Drop an EJB from the database by following these steps:

• Run the dropjava tool to delete the classes from the database. Provide the original bean JAR file that contains the class files for the bean.

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

See Oracle8i Java Tools Reference for documentation of the dropjava and session shell tools.

Run the Example

To run this example, execute the client class using the client-side JVM. For this example, you must set the CLASSPATH for the java command to include:

• the standard Java library archive (classes.zip)

• any class files the client ORB uses, such as those in VisiBroker for Java vbjapp.jar and vbjorb.jar

• the Oracle8i-supplied JAR files: mts.jar and aurora_client.jar

If you are using JDBC, include one of the following JAR files:

• classes111.zip for JDBC 1.1 support

• classes12.zip for JDBC 1.2 support

If you are using SSL, include one of the following JAR files:

• javax-ssl-1_1.jar and jssl-1_1.jar for SSL 1.1 support

• javax-ssl-1_2.jar and jssl-1_2.jar for SSL 1.2 support

You can locate these libraries in the lib and jlib directories under the Oracle home location in your installation.

The following invocation of the JDK java command runs this example.

Note: The UNIX shell variable $ORACLE_HOME might be represented as %ORACLE_HOME% on Windows NT. The JDK_HOME is the installation location of the Java Development Kit (JDK).

% java -classpath .:$(ORACLE_HOME)/lib/aurora_client.jar			|

	:$(ORACLE_HOME/lib/mts.jar		|

	:$(ORACLE_HOME)/jdbc/lib/classes111.zip:		|

	$(ORACLE_HOME)/lib/vbjorb.jar:		|

	$(ORACLE_HOME)/lib/vbjapp.jar:$(JDK_HOME)/lib/classes.zip 		|

		Client 	|

		sess_iiop://localhost:2481:ORCL 	|

		/test/myEmployee 	|

		scott tiger 

---