
	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WLE Doc Home \| Getting Started \| Previous \| Next \| Contents \| Index

Building and Deploying Enterprise JavaBeans (EJBs)

This topic includes the following sections:

Overview of the EJB Building and Deploying Process

Building and deploying EJBs in the WebLogic Enterprise environment requires careful planning to define how to locate these EJBs in the WLE distributed environment.

After the Bean Provider has implemented an EJB's business logic and has produced an initial deployment descriptor, the process for building and deploying that EJB in the WLE environment includes the following steps:

When you build the EJB that has been produced by the Bean Provider, the end result is an EJB JAR file. The WLE system allows you to build two kinds of EJB JAR files:

Standard EJB JAR file

An EJB that has been built, but lacks the specific deployment information on any specific system. You typically build a standard EJB with the goal of being able to distribute that EJB to a variety of deployment environments. If you are only creating a standard EJB JAR file, you only need to perform steps 1 and 2 in this topic.

Deployable EJB JAR file

An EJB that has been built with deployment descriptor information specific to a particular deployment environment. The steps described in this chapter for building a deployable EJB JAR file specifically create an EJB that can be deployed on a WLE system, and require you to perform steps 1 through 4 in this topic.

The remainder of this topic discusses each of these steps in detail.

Steps for Building and Deploying EJBs

This section describes the steps for building and deploying EJBs in the WLE environment and also provides the following sections:

Step 1: Obtain the EJB JAR file from the bean provider.

The first step in deploying an EJB is to obtain the EJB JAR file from the Bean Provider. In addition to the class files contained in the EJB JAR file, the EJB JAR file also has a deployment descriptor for each bean in that file. The steps for producing the Bean Provider's EJB JAR file are described in the section Development Steps.

Because multiple EJBs can be joined together in a single, deployable unit, part of the assembly process is joining the EJB JAR files for each of the beans.

Step 2: Modify the deployment descriptor.

As stated in Designing and Developing Enterprise JavaBeans for the WLE System, the deployment descriptor ties together the different classes and interfaces, and is used to build the code-generated class files. It also allows you to specify some aspects of the EJB's deployment at run time.

The Bean Provider specifies some initial deployment information in the deployment descriptor. The deployer typically needs to add to or modify that information, such as shown in the following table:

The EJB's name

You may change the enterprise bean's name defined in the ejb-name element.

Values of environment entries

You may change existing values or define new values for the environment properties.

Description fields

You may change existing or create new description elements.

Binding of enterprise bean references

You may link an enterprise bean reference to another enterprise bean in the EJB JAR file. You create the link by adding the ejb-link element to the referencing bean.

Security roles

You may define one or more security roles. The security roles define the recommended security roles for the clients of the enterprise beans. You define the security roles using the security-role elements. For more information about EJB security, see Using Security in the WebLogic Enterprise online documentation.

Method permissions

You may define method permissions, which are binary relationships between the security roles and the methods of the remote and home interfaces of the EJBs. You define method permissions using the method-permission elements.

Linking of security role references

If you define security roles in the deployment descriptor, you must link the security role references declared by the Bean Provider to the security roles. You define these links using the role-link element. For more information about EJB security, see Using Security in the WebLogic Enterprise online documentation.

Changing persistent storage information, if necessary

The deployer can change the type of persistent storage used by a bean. If the persistentStoreType is file , the serialized files are created in this directory. The default file is / pstore/ bean_name .dat , where the directory pstore represents the directory from which the WLE application was started, and bean_name is the fully qualified name of the EJB with underscores (_ ) replacing the periods (. ) in the name.
If the persistentStoreType is jdbc , the container looks for additional values to determine the appropriate values for the JDBC connection. Note that if the bean's persistence is stored in a database via a JDBC connection, the system administrator needs to add this information to the UBBCONFIG file as well. For more information, see Using the JDBC Drivers in the WebLogic Enterprise online documentation.
Note that persistence information is specified in the WebLogic EJB extensions to the deployment descriptor DTD file, as described in the section Specifying Persistence Information.

To modify a deployment descriptor, you can use either of the following two methods:

The WebLogic EJB Deployer
The manual modification of the deployment descriptor in a text editor

The type of deployment descriptor you produce depends on whether you are creating a standard EJB JAR file or a deployable EJB JAR file.

<!DOCTYPE weblogic-ejb-extensions SYSTEM "weblogic-ejb-extensions.dtd" >

Specifying the Module Initializer Class

Server application startup and shutdown can be handled automatically by the EJB container. However, if you have special server initialization or shutdown requirements, use the module-initializer-class-name element in the WebLogic EJB extensions to the deployment descriptor DTD to specify the name of the module initializer object.

The syntax for specifying a module initializer object for handling the initialize and release methods is similar to that for CORBA and RMI. However, with the CORBA and RMI models, the startup and shutdown information is specified in an XML file and is serialized by the buildjavaserver command. For EJB deployment, XML elements for startup and shutdown procedures are specified together with the other elements in the WebLogic EJB extensions to the deployment descriptor DTD, and you process them using the ejbc command. The WLE EJB container parses the XML at run time and performs the startup and shutdown processing. See the section Step 5: Configure the EJB application. for a complete description of startup and shutdown handling in WLE.

XML DTD Syntax

<!ELEMENT module-initializer-class (module-initializer-class-name*))>
<!ELEMENT module-initializer-class-name (#PCDATA)>

Example

<weblogic-ejb-extensions>
. . .
	<module-initializer-class>
		<moduleinitializer-class-name>ServerImpl
		</moduleinitializer-class-name>
	</module-initializer-class>
</weblogic-ejb-extensions>

Registering Names for the EJB Home Classes

A name for the EJB home class must be registered in the global WLE JNDI namespace. This allows Java clients to perform a lookup on the JNDI name for the EJB home and gain access to the object. The name for the EJB home class can be different than the <ejb-name> element specified in the standard EJB XML. The <ejb-name> in the standard deployment descriptor must be unique only among the names of the EJBs in the same EJB JAR file. However, the JNDI name must be unique among all global home or factory names in a WLE domain; this includes EJB homes, CORBA factories, and RMI named objects.

XML DTD Syntax

<!ELEMENT jndi-name (#PCDATA)>

Example

<weblogic-ejb-extensions>
  <weblogic-version>
    WebLogic Enterprise Server 5.0
  </weblogic-version>
  <weblogic-enterprise-bean>
    <ejb-name>
      oracle
    </ejb-name>
    <weblogic-deployment-params>
    
      <max-beans-in-free-pool>
        20
      </max-beans-in-free-pool>
      <max-beans-in-cache>
        1000
      </max-beans-in-cache>
      <idle-timeout-seconds>
        5
      </idle-timeout-seconds>
      <!-- JNDI name that is associated with this EJB;
           used for lookup -->
      <jndi-name>
        oracle.OracleHome
      </jndi-name>
              .
              .
              .
</weblogic-ejb-extensions>

Specifying Persistence Information

The WLE EJB container provides container-managed persistence. The code for implementing the persistence is generated by the ejbc command based on the deployment descriptors. The persistence store can be a flat file or it can be a database managed with a JDBC connection pool. For the EJB state to fully cooperate in a WLE global transaction, configure the EJB to use the JDBC-managed database store provided in WLE. Use file-based persistence only during development and prototyping.

The standard deployment descriptor created by the Bean Provider normally specifies:

The fields in the EJB that are to be persistent, via the cmp-field element
Information about the primary key

However, you, as the deployer, need to specify additional information for mapping an EJB to its persistent store via the WebLogic EJB extensions to the deployment descriptor DTD.

File-based Persistence

The following code shows the WebLogic EJB extensions to the deployment descriptor DTD for specifying file-based persistence:

<!--
Persistence store descriptor. Specifies what type of persistence store
EJB container should use to store state of bean.
-->
<!ELEMENT persistence-store-descriptor (description?,
(persistence-store-file |
persistence-store-jdbc)?)>
<!--
Persistence store using file. Bean is serialized to a file.
Mainly used to store state of Stateful Session Beans.
-->
<!ELEMENT persistence-store-file (description?,
persistence-store-directory-root
?)>
<!--
Root directory on File system for storing files per bean.
-->
<!ELEMENT persistence-store-directory-root (#PCDATA)>

The information supplied for the persistence-store-directory-root element is used by the EJB container to store all instances of the EJB, with the ejb-name element converted to a directory name.

Database-stored Persistence

The following code shows the WebLogic EJB extensions to the deployment descriptor DTD for specifying a JDBC connection for database-stored persistence:

<!--
Persistence store is any RDBMS. JDBC driver is used to talk to database.
Required for CMP.
-->
<!ELEMENT persistence-store-jdbc (description?, pool-name, user?, password?,
driver-url?, driver-class-name?, table-name, attribute-map,
finder-descriptor*)>

<!-- Required for CMP -->
<!ELEMENT pool-name (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT user (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT password (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT driver-url (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT driver-class-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT table-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT attribute-map (description?, attribute-map-entry+)>

<!-- Required for CMP -->
<!ELEMENT attribute-map-entry (bean-field-name, table-column-name)>

<!-- Required for CMP -->
<!ELEMENT bean-field-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT table-column-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT finder-descriptor (description?, method?, query-grammar?)>

<!-- Required for CMP -->
<!ELEMENT query-grammar (#PCDATA)>

The EJB instances are stored in a database that has been previously set up with a JDBC connection pool, which is identified by the pool-name element. The table-name and attribute-map elements map the EJB fields to the appropriate table columns in the database.

Finder descriptors are the WLE implementation of the EJB find methods. The finder-descriptor elements are pairs of method signatures and expressions. You specify a method signature in the EJBHome interface, and you specify the method's expression in the deployment descriptor via the query-grammar element. The finder methods return an enumeration of EJBs. For more information about specifying finder descriptors, see the EJB XML Reference in the WebLogic Enterprise online documentation.

Example

The following WebLogic EJB extensions to the deployment descriptor DTD fragment specify automatic saving using JDBC persistence of two fields of an entity bean (accountId and salary ) to a database table (emp ) using a connection pool (pool1 ), shown in boldface type:

<weblogic-ejb-extensions>
  <weblogic-version>
    WebLogic Enterprise Server 5.0
  </weblogic-version>
  <weblogic-enterprise-bean>
    <ejb-name>
      oracle
    </ejb-name>
    <weblogic-deployment-params>
    
      <max-beans-in-free-pool>
        20
      </max-beans-in-free-pool>
      <max-beans-in-cache>
        1000
      </max-beans-in-cache>
      <idle-timeout-seconds>
        5
      </idle-timeout-seconds>
      <!-- JNDI name that is associated with this EJB;used for lookup -->
      <jndi-name>
        oracle.OracleHome
      </jndi-name>
                   
      <!-- This is CMP EJB. Specify persistence information -->
      <persistence-store-descriptor>
        <persistence-store-jdbc>
          <!-- Pool name is looked up by the EJB source -->
          <pool-name>
            jdbc/pool1
          </pool-name>
          <!-- *** DATABASE INFORMATION SPECIFIC TO 
                   INSTALLATION SITE *** -->
          <!-- Default user URL is for Oracle 8i-->
          <user>
            scott
          </user>
          
          <!-- Default password URL is for Oracle 8i-->
          <password>
            tiger
          </password>
          <!-- Default driver URL is for Oracle 8i,
               and default instance Beq-Local is used
          -->
          <driver-url>
            jdbc:weblogic:oracle:Beq-Local
          </driver-url>
          <table-name>
            emp
          </table-name>
          
          <!-- CMP Fields and database table column mapping-->
          <attribute-map>
            <attribute-map-entry>
              <bean-field-name>
                accountId
              </bean-field-name>
              <table-column-name>
                empno
              </table-column-name>
            </attribute-map-entry>
            <attribute-map-entry>
              <bean-field-name>
                salary
              </bean-field-name>
              <table-column-name>
                sal
              </table-column-name>
            </attribute-map-entry>
          </attribute-map>
          
          <!-- Finder Specifications -->
          <finder-descriptor>
            <method>
              <ejb-name>
              oracle
              </ejb-name>
              <method-name>
                findAccount(double salaryEqual)
              </method-name>
            </method>
            <query-grammar>
              (= salary $salaryEqual)
            </query-grammar>
          </finder-descriptor>
        </persistence-store-jdbc>
      </persistence-store-descriptor>
    </weblogic-deployment-params>
  </weblogic-enterprise-bean>
</weblogic-ejb-extensions>