Deployment on WebLogic Server

The entity bean must run within a bean container on an application server. This stage of software development, to load the software on the target environment, is referred to as deployment . At this point, the bean provider has written the following interfaces and classes:

• Remote interface

• Remote home interface

• Local interface

• Local home interface

• Value object class

• Entity bean class

In addition to the classes and interfaces for the entity EJB, the bean provider must also write deployment descriptors to define the deployment specifications for the bean. The deployment of an entity EJB has the following steps performed by the application server:

• Generate all of the implementation classes

• Set up the JNDI tree for JNDI lookups

• Set up the connection pool

• Set up tables in the database that match the schema

All four of these steps are performed when an entity bean is deployed. The deployment of the bean simply requires the jar file containing the implementation and descriptors to be placed in the application directory on WebLogic Server. The implementation for the interfaces and abstract classes are automatically generated by WebLogic Server when the entity bean is deployed. Optionally, the tables in the database can be created automatically through a specification in the WebLogic deployment descriptor. The EJB deployment descriptor, ejb-jar.xml , was covered previously in this chapter. WebLogic Server supports additional deployment descriptors:

• weblogic-ejb-jar.xml

• weblogic-cmp-rdbms-jar.xml

Through the specification provided by the WebLogic specific deployment descriptors, the JNDI tree and relational database are configured on behalf of the deployed entity EJB.

The weblogic-ejb-jar.xml Deployment Descriptor

The primary purpose of the weblogic-ejb-jar.xml file is to specify JNDI names for the deployment of the entity bean. The JNDI names are used to set up the JNDI tree database to allow the home interface of the entity bean to be retrieved using a JNDI lookup. Session beans look up the home interface of the entity beans, and entity beans with container-managed relationships look up the home interface of the other entity beans that they contain. The major XML tags that are specified in the weblogic-ejb-jar.xml deployment descriptor are defined in Table 21.3.

Table 21.3. The Major XML Tags for the weblogic-ejb-jar.xml Deployment Descriptor

Tag	Purpose
<entity-descriptor>	This is the parent tag that contains the persistence options: <persistence-type> and <persistence-use> .
<persistence-type>	This tag specifies the services that the container can use for persistence. Multiple <persistence-type> tags can be specified. In addition to <type-identifier> and <type-version> , the <type-storage> is specified, which is the weblogic-cmp-rdbms-jar.xml persistence descriptor.
<persistence-use>	This tag specifies which of the <persistence-type> elements to use.
<jndi- name >	This tag specifies the name for the remote home interface.
<local-jndi-name>	This tag specifies the name for the local home interface.
<concurrency-strategy>	WebLogic Server allows several methods to optimize currency: Exclusive , Database , and ReadOnly .
	Exclusive places a synchronized lock on the entity bean until the transaction is committed.
	Database defers locking to the underlying datastore. This is the default for WebLogic.
	ReadOnly is used by entity beans that do not update the database, they only read from the database.
<read-timeout-seconds>	This tag specifies an interval timer that is used by the WebLogic container to call the ejbLoad() method on the entity bean every <read-timeout-seconds> . It would be used in a stock ticker application, for example.
<invalidate-target>	This tag causes another ReadOnly entity bean to become invalid when this bean gets modified.
	<invalidate-target> <ejb-name>MyReadOnlyClient<ejb-name> <invalidate-target>
<db-is-shared>	This tag is used to optimize calls to ejbLoad() . By default, WebLogic Server calls ejbLoad() at the beginning of each transaction to ensure that any updates by other entity beans are captured by this bean. If no other beans are updating the data used by this entity bean, set <db-is-shared> to false; it is true by default.
<delay-updates-until-end-of-tx>	This tag is used to optimize calls to ejbStore() . By default, WebLogic Server calls ejbStore() when a transaction is committed. To allow other entity beans to see uncommitted data, set <delay-updates-until-end-of-tx> to false, which will cause ejbLoad() to be called whenever there is an update, not just after commits. This property is true by default.
<create-default-dbms-table>	This tag is primarily used during the development stage to allow WebLogic Server to automatically create database tables. To enable this feature, set <create-default-dbms-table> to true; it is false by default.

The weblogic-ejb-jar.xml deployment descriptor for the ShoppingCart is provided as an example in Listing 21.23.

Listing 21.23 The WebLogic Deployment Descriptor Provides the Specification for Deploying the Entity EJB on WebLogic Server

[View full width]

 <!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN' 'http  ://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'> <!-- Generated XML! --> <weblogic-ejb-jar> <weblogic-enterprise-bean> <ejb-name>ShoppingCart</ejb-name> <entity-descriptor> <pool> </pool> <entity-cache> <cache-between-transactions>False</cache-between-transactions> </entity-cache> <persistence> <persistence-use> <type-identifier>WebLogic_CMP_RDBMS</type-identifier> <type-version>7.0</type-version> <type-storage>META-INF/weblogic-cmp-rdbms-jar.xml</type-storage> </persistence-use> </persistence> <entity-clustering> </entity-clustering> </entity-descriptor> <transaction-descriptor> </transaction-descriptor> <jndi-name>cmp.ShoppingCart</jndi-name> <local-jndi-name>cmp.ShoppingCart-Local</local-jndi-name> </weblogic-enterprise-bean> <weblogic-enterprise-bean> <ejb-name>BookStore</ejb-name> <entity-descriptor> <pool> </pool> <entity-cache> <cache-between-transactions>False</cache-between-transactions> </entity-cache> <persistence> <persistence-use> <type-identifier>WebLogic_CMP_RDBMS</type-identifier> <type-version>7.0</type-version> <type-storage>META-INF/weblogic-cmp-rdbms-jar.xml</type-storage> </persistence-use> </persistence> <entity-clustering> </entity-clustering> </entity-descriptor> <transaction-descriptor> </transaction-descriptor> <jndi-name>cmp.BookEntity</jndi-name> <local-jndi-name>cmp.BookEntity-Local</local-jndi-name> </weblogic-enterprise-bean> </weblogic-ejb-jar> 

The weblogic-cmp-rdbms-jar.xml Persistence Descriptor

The weblogic-cmp-rdbms-jar.xml persistence descriptor is referenced by the weblogic-ebj-jar.xml deployment descriptor as the <type-storage> for persistence. The major XML tags that are specified in the weblogic-cmp-rdbms-jar.xml persistence descriptor are shown in Table 21.4.

Table 21.4. The Major Tags in the weblogic-cmp-rdbmc-jar.xml Persistence Descriptor

Tag	Purpose
<weblogic-rdbms-bean>	This is the parent tag that contains the specification for the persistence of the beans. The children of this tag are: <ejb-name> , <data-source-name> , <table-name> , <field-map> , and <automatic-key-generation> .
<ejb-name>	This tag must correspond to an <ejb-name> of an <entity> element in the ejb-jar.xml deployment descriptor.
<data-source-name>	This tag specifies the name of the database connection pool to use for persistence.
<table-name>	This tag specifies the name of the database table to use for persistence of this entity bean.
<field-map>	This tag maps <cmp-field> elements to <dbms-column> names.
<automatic-key-generation>	This tag is a value-added feature of WebLogic Server to generate primary keys for CMP entities.
<weblogic-rdbms-relation>	This is the parent tag that contains the specification for the persistence of the relationships. The children of this tag are: <relation-name> and <weblogic-relationship-role> .
<relation-name>	This tag maps an <ejb-relation-name> from ejb-jar.xml to this <weblogic-rdbms-relation> .
<weblogic-relationship-role>	This is the parent tag for the <relationship-role-name> and <column-map> elements.
<relationship-role-name>	This tag maps an <ejb-relationship-role-name> from ejb-jar.xml to this <weblogic-relationship-role> .
<column-map>	This tags specifies the <foreign-key-column> and <key-column> for joining the tables in this relationship.
<create-default-dbms-table>	This tag is primarily used during the development stage to allow WebLogic Server to automatically create database tables. To enable this feature, set <create-default-dbms-table> to true; it is false by default.

Tip

The <create-default-dbms-table> is not recommended for production-quality software. The database schema should be very precise and not automatically generated by WebLogic Server.

The weblogic-cmp-rdbms-jar persistence descriptor for the ShoppingCart is shown in Listing 21.24.

Listing 21.24 The WebLogic Persistence Descriptor Provides the Specification for Mapping the Entity EJB to the Relational Database Being Used by WebLogic Server

 <!DOCTYPE weblogic-rdbms-jar PUBLIC '-//BEA Systems, Inc.// DTD WebLogic 7.0.0 EJB RDBMS Persistence//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-rdbms20-persistence-700.dtd'> <!-- Generated XML! --> <weblogic-rdbms-jar> <weblogic-rdbms-bean> <ejb-name>ShoppingCart</ejb-name> <data-source-name>TxDSBookStore</data-source-name> <table-map> <table-name>ShoppingCart</table-name> <field-map> <cmp-field>cartID</cmp-field> <dbms-column>cartID</dbms-column> </field-map> <field-map> <cmp-field>customerID</cmp-field> <dbms-column>customerID</dbms-column> </field-map> </table-map> <automatic-key-generation> <generator-type>NAMED_SEQUENCE_TABLE</generator-type> <generator-name>SHOPPING_SEQ</generator-name> <key-cache-size>10</key-cache-size> </automatic-key-generation> </weblogic-rdbms-bean> <weblogic-rdbms-bean> <ejb-name>BookStore</ejb-name> <data-source-name>TxDSBookStore</data-source-name> <table-map> <table-name>bookstore</table-name> <field-map> <cmp-field>author</cmp-field> <dbms-column>bookAuthor</dbms-column> </field-map> <field-map> <cmp-field>price</cmp-field> <dbms-column>bookPrice</dbms-column> </field-map> <field-map> <cmp-field>bookID</cmp-field> <dbms-column>bookID</dbms-column> </field-map> <field-map> <cmp-field>title</cmp-field> <dbms-column>bookTitle</dbms-column> </field-map> </table-map> <weblogic-query> <query-method> <method-name>findBooksByAuthor</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </query-method> <max-elements>0</max-elements> <include-updates>False</include-updates> </weblogic-query> </weblogic-rdbms-bean> <weblogic-rdbms-relation> <relation-name>ShoppingCart-Book</relation-name> <weblogic-relationship-role> <relationship-role-name>ShoppingCart-Has-Books</relationship-role-name> <relationship-role-map> <column-map> <foreign-key-column>cart</foreign-key-column> <key-column>cartID</key-column> </column-map> </relationship-role-map> </weblogic-relationship-role> </weblogic-rdbms-relation> <create-default-dbms-tables>True</create-default-dbms-tables> </weblogic-rdbms-jar> 

Deploying Entity Beans to WebLogic Server

The implementation of an entity EJB is released as a JAR file, which contains the compiled class files for the interfaces and classes that were created to implement the entity EJB. In addition to the compiled class files, the JAR contains the ejb-jar.xml and weblogic-ejb-jar.xml deployment descriptors. If the bean is implemented using CMP, the weblogic-cmp-rdbms-jar.xml persistence descriptor must also be added to the jar file for the entity bean. The entity bean JAR can be added to an enterprise application archive (EAR) file, but this is not required to deploy the bean on WebLogic Server.

Before the entity bean can be deployed to WebLogic Server, the JDBC DataSources or Tx DataSources and associated connection pools that the entity bean has been configured to use must exist and be operational. This is especially important if you have enabled the <create-default-dbms-tables> tag in the weblogic-cmp-rdbms-jar.xml persistence deployment descriptor to create the database tables the CMP entity bean will use. Also, if you are deploying a CMP entity bean, the sequence table the EJB container will use to auto-generate keys will also need to exist in the target database. Only once WebLogic Server and target database have been configured correctly, the JAR or EAR file can be deployed to WebLogic Server using the weblogic.Deployer tool, WebLogic Builder or the Administration Console.

To showcase the deployment of CMP entity beans, the following steps will explain how to successfully deploy the ShoppingCart EJB ( BookEntity and ShoppingCart CMP entity beans) developed in this chapter to WebLogic Server.

Step 1: Start and Configure Your Target Database

To enable you to quickly and easily deploy the ShoppingCart EJB example, the Pointbase database that comes bundled with WebLogic Server will be used as the target database. The Pointbase database uses the concept of schemas to allow you to create unique database environments, while running under one database server instance. Schemas are created for each unique database user. Hence each database user can create and manipulate database tables in their own schema. The database user and schema that will be used in the Pointbase database for the ShoppingCart EJB example will be "PBPUBLIC."

The approach taken in this example is to start the Pointbase database with the WebLogic Server instance you are using. Using this approach you can leverage the startup parameters for the Pointbase database already provided in your StartExampleServer script file located in the %BEA_HOME%\weblogic700\samples\server\config\examples directory.

Note

The %BEA_HOME% directory is the root directory of the BEA software installation, for example c:\bea.

An example of these startup parameters is provided in Listing 21.25.

Listing 21.25 The Startup Parameters for the Pointbase Database to be Copied into Your WebLogic Server Startup Script

 @rem ***************************************************************** @rem PointBase and examples domain specific configuration set SAMPLES_HOME=C:\bea\weblogic700\samples set POINTBASE_HOME=%SAMPLES_HOME%\server\eval\pointbase set COMMON_CLASSES=%SAMPLES_HOME%\server\stage\common @rem Add PointBase classes to the classpath, so we can start the @rem database. set CLASSPATH="C:\bea\weblogic700\server\lib\ webservices .jar; C:\bea\jrockit70sp2_131\lib\tools.jar;%POINTBASE_HOME%\lib\pbserver42ECF183.jar; %POINTBASE_HOME%\lib\pbclient42ECF183.jar;%CLIENT_CLASSES%;%SERVER_CLASSES% ;%COMMON_CLASSES%;%CLIENT_CLASSES%\utils_common.jar" @rem Start PointBase 4.2. start "PointBase" cmd /c ""C:\bea\jrockit70sp2_131\bin\java" -classpath %CLASSPATH% com.pointbase.net.netServer /port:9092 /d:3 /pointbase.ini="%SAMPLES_HOME%\server\config\examples\pointbase.ini"" > "%SAMPLES_HOME%\server\config\examples\pointbase.log" 2>&1 @rem ************************************************************************ 

Listing 21.25, as it pertains to your WebLogic Server environment, should be copied into your WebLogic Server startup script to ensure the Pointbase database starts with your WebLogic Server instance. Once you restart your WebLogic Server, you will see a command shell appear, as illustrated in Figure 21.2, indicating the Pointbase database server has started.

Figure 21.2. A successful starting of the Pointbase database.

The final aspect of configuring your Pointbase database for the ShoppingCart EJB example is creating the sequence table that will be used to store key values for the auto-generation of primary keys. This sequence table must contain a single row with a single column named "SEQUENCE" of datatype INTEGER (SEQUENCE INT). The SEQUENCE column holds the current sequence value.

The name of the sequence table to create for the ShoppingCart EJB example is specified by the <automatic-key-generation> tag in the weblogic-cmp-rdbms-jar persistence descriptor, as shown in Listing 21.26.

Listing 21.26 Specifying Automatic Key Generation for a Named Sequence Table

 <automatic-key-generation> <generator-type>NAMED_SEQUENCE_TABLE</generator-type> <generator_name>SHOPPING_SEQ</generator-name> <key-cache-size>100</key-cache-size> </automatic-key-generation> 

In Listing 21.26,

• <generator-type> specifies the name of the sequence table to create in your database.

• <key-cache-size> specifies how many keys the EJB container will fetch in a single DBMS call.

Note

For improved performance, BEA recommends that you set this value to a number greater than one. This setting reduces the number of calls to the database to fetch the next key value.

To easily create a table named "SHOPPING_SEQ" in your Pointbase database, follow these steps:

1. From a command prompt, set your Java environment, for example by executing the setEnv script provided in your WebLogic domain folder.

2. Change the directory to the following:

     %BEA_HOME%\weblogic700\samples\server\eval\pointbase\tools  

3. Execute the following command to launch the Pointbase Console:

     StartPointBaseConsole  

4. In the displayed login screen, as shown in Figure 21.3, enter "PBPUBLIC" for the User and Password entry field. Click OK.

   Figure 21.3. The Pointbase Login Screen.

   

5. Execute the following SQL statement to create the SHOPPING_SEQ sequence table:

     CREATE SHOPPING_SEQ (SEQUENCE int);  

6. Enter a row into the newly created SHOPPING_SEQ table using the following SQL statement:

     INSERT INTO SHOPPING_SEQ VALUES (0);  

Your Pointbase database is now configured to be used with the ShoppingCart EJB example.

Step 2: Configure the JDBC Connection Pools Tx DataSource in Your WebLogic Server

The ShoppingCart EJB example will use a JDBC connection pool named CMPBeanPool to serve as a pool of database connections to your target Pointbase database using a Tx DataSource named TxDSBookStore .

To configure your CMPBeanPool connection pool in your WebLogic Server:

1. Start the Administration Console.

2. From the Administration Console, expand the JDBC node in the left pane.

3. Click the Connection Pools node, which will display all the connection pools defined in your domain in the right pane.

4. Click the Configure a New JDBC Connection Pool text link. A new page will display in the right pane (Configuration, General tab) allowing you to configure a new connection pool.

5. Enter the following values to configure your connection pool

   • Name = CMPBeanPool

   • URL = jdbc:pointbase:server://localhost/demo

   • Driver Classname = com.pointbase.jdbc.jdbcUniversalDriver

   • Properties = user=PBPUBLIC, password=PBPUBLIC

6. Click Create to create the CMPBean connection pool. This new instance is added under the Connection Pools node in the left pane.

7. Click the Targets tab and assign the CMPBean connection pool to your WebLogic Servers or clusters.

8. Click Apply.

For an illustrated and detailed guide to creating a JDBC connection pool, see "Configuring and Using Connection Pools," p. 427 .

To configure your "TxDSBookStore" Tx DataSource in your WebLogic Server:

1. Start the Administration Console

2. In the left pane of the Administration Console, click to expand the JDBC node.

3. Click the Tx DataSources node. The Tx DataSources table displays in the right pane showing all the data sources defined in your domain.

4. Click the Configure a New JDBC Tx DataSource text link. A new page displays in the right pane showing the Configuration tab for creating a new Tx DataSource.

5. Enter the following values in the Configuration tab:

   • Name = TxDSBookStore

   • JNDI Name = TxDSBookStore

   • Pool Name = CMPBeanPool

6. Click Create to create the TxDSBookStore Tx DataSource.

7. Click the Targets tab and assign the TxDSBookStore Tx DataSource to your WebLogic Servers or clusters.

8. Click Apply.

Your CMPBean connection pool and TxDSBookStore Tx DataSource is now configured for the ShoppingCart EJB example against the Pointbase database.

Step 3: Deploying the ShoppingCart EJB Example to Your WebLogic Server

To deploy the ShoppingCart EJB example to your WebLogic Server, the ShoppingCart and BookEntity CMP entity beans, the Customer class, and the associated deployment descriptors must be compiled and packaged into a JAR file named ShoppingCart.jar using the following steps:

Note

The Customer class is used to unit test the API for the ShoppingCart and BookEntity entity beans later in this chapter.

1. Set your Java environment by executing a set environment script, for example the setEnv WebLogic Server script.

2. Execute the following command from your working directory to compile your Java source code:

     javac -d . *.java  

3. Package your compiled class files and deployment descriptors into a deployable JAR file using the following command:

     jar cvf ShoppingCart.jar com META-INF  

Once you have generated the ShoppingCart.jar module, you can deploy this JAR file to WebLogic Server via the Administration Console using the following steps:

1. Start the Administration Console.

2. In the left pane of the Administration Console, click to expand the Deployments node.

3. Click the EJB node. The EJB Deployments table displays in the right pane showing all the EJBs deployed in your domain.

4. Click the Configure a New EJB text link. A new page displays in the right pane showing the steps to deploy a J2EE application or module (ShoppingCart) to your WebLogic Server.

   Step 1 involves ensuring the ShoppingCart.jar file is on the same file system as the Administration Server of your WebLogic domain.

   Step 2 involves using the Administration Console to locate the ShoppingCart.jar file you want to deploy. Once you have located the ShoppingCart.jar file, use the [select] link next to that file, as illustrated in Figure 21.4.

   Figure 21.4. Selecting the ShoppingCart.jar module for deployment.

   

   Step 3 involves selecting the WebLogic Servers or clusters you want to deploy the ShoppingCart module to and assigning a WebLogic name to the module within the context of the WebLogic environment, as illustrated in Figure 21.5.

   Figure 21.5. Selecting the WebLogic Name and target WebLogic Servers for the ShoppingCart module.

   

5. Click Configure and Deploy to deploy the ShoppingCart module to your WebLogic Server(s).

Once the ShoppingCart EJB example has been deployed, you will see a Deployment Status By Target screen in the Administration Console indicating the success or failure of the deployment. Figure 21.6 shows a successful deployment of the ShoppingCart module to its target WebLogic Server.

Figure 21.6. A successful deployment of the ShoppingCart module to the target WebLogic Server.

For further information on deployment in the WebLogic Server, see Chapter 27, "Packaging, Assembling and Deploying J2EE Applications," p. 953 .

Once the ShoppingCart module is deployed, the associated tables it uses (BOOKSTORE and SHOPPINGCART) will automatically be created by the EJB container. You can validate the creation of these table using the Catalog option in the Pointbase Console, as illustrated in Figure 21.7.

Figure 21.7. Using the Pointbase Console to validate the creation of the ShoppingCart tables.

Testing the Deployment of the ShoppingCart Module

The ShoppingCart.jar includes the Customer class which can be used to unit test the API for the ShoppingCart and BookEntity EJBs. The Customer class is run as a standard Java application and uses localhost as the hostname for JNDI lookups. For this reason it must be run on the same system as the WebLogic Server you deployed the ShoppingCart to.

Note

The source code for the Customer class was shown in Listing 21.21.

This test program takes four command-line arguments: title, author, price, and bookID. The constructor creates a BookEntity EJB using the command-line arguments as BookEntityVO data. The main() method then invokes the purchase() method which adds the same BookEntityVO() to a ShoppingCart . If any exceptions are thrown, the error message is displayed; otherwise a thank you message is displayed for purchasing the book.

To run this test application against the ShoppingCart example:

1. Open a Command Prompt window and set your Java environment.

2. Set the CLASSPATH to include the location of the ShoppingCart.jar , for example using the following statement:

     Set CLASSPATH=ShoppingCart.jar;%CLASSPATH%  

3. Run the application using the following command, as shown in Figure 21.8.

   Figure 21.8. The Customer class is used to unit the API for the ShoppingCart EJB.

   

     java com.objectmind.BookStore.Customer "WebLogic Platform 7.0" "Jatinder Prem" 50.0 1