Generating Deployment Descriptors

Tutorial 10: Using EJBGen to Generate EJB Deployment Descriptors

This tutorial demonstrates how to use the WebLogic Server EJBGen utility to generate deployment descriptor files and EJB source files such as the home interface file.

The demonstration uses the PhysicianSession EJB from the Physician application in MedRec. You use EJBGen to generate new EJB source files and new versions of the EJB deployment descriptor files for the Physician EJB.

You compare the original versions of the deployment descriptor files to the newly generated versions. The files are:

- ejb-jar.xml, which specifies PhysicianSessionEJB's bean, its interfaces, and its session and transaction types
- weblogic-ejb-jar.xml, which specifies PhysicianSessionEJB's pool and time-out deployment settings

EJBGen uses annotations in the bean file to generate the deployment descriptor files and the EJB Java source files. EJB files in the MedRec application are already annotated for EJBGen.

The tutorial includes the following sections:

- Prerequisites
- Procedures
- Best Practices
- The Big Picture
- Related Reading

Prerequisites

Before starting this tutorial, complete Tutorial 9: Deploying MedRec from the Development Environment. In this tutorial, it is assumed that MedRec is bundled as the tutorial_deployment application and is ready to deploy to the MedRec server, as it is at the end of Tutorial 9.

Procedures

In the following procedures you view some of the files that EJBGen generates, use EJBGen to regenerate those files, redeploy the application, and then view the newly generated files.

- Procedure 1: Deploy the application and view the deployment descriptor files.
- Procedure 2: Generate new deployment descriptor and EJB files.
- Procedure 3: Redeploy the application and view the generated files.

Procedure 1: Deploy the application and view the deployment descriptor files.

1. Set your environment by opening a command window and running setenv.cmd:

   >     c:\bea\user_projects\domains\MedRecDomain\setenv.cmd

2. Move to the physicianEar subdirectory:

   >     cd c:\medrec_tutorial\src\physicianEar

3. Redeploy the tutorial_deployment application. For example:

   >     ant -f deploy.xml

4. Open the Administration Console by navigating in a browser to http://localhost:7101/console.

5. In the left-hand panel of the Administration Console, expand Deployments-->Applications-->tutorial_deployments and click physSessionEjb.

6. In the right-hand panel, select the Descriptors tab.

7. Click the ejb-jar.xml file to view its text, so that you can compare it with the text you will use EJBGen to generate. The XML code quoted in this step and the next step is generated by EJBGen. You do not need to write it.

   The XML should appear as follows:

   >     <ejb-jar>

   >       <enterprise-beans>

   >         <session>

   >           <ejb-name>PhysicianSessionEJB</ejb-name>

   >           <home>com.bea.medrec.controller.PhysicianSessionHome</home>

   >           <remote>com.bea.medrec.controller.PhysicianSession</remote>

   >     <ejb-class>com.bea.medrec.controller.PhysicianSessionEJB</ejb-cla
   >     ss>

   >           <session-type>Stateless</session-type>

   >           <transaction-type>Container</transaction-type>

   >         </session>

   >       </enterprise-beans>

   >     </ejb-jar>

8. Click the weblogic-ejb-jar.xml file. It should read as follows:

   >     <weblogic-ejb-jar>

   >       <weblogic-enterprise-bean>

   >         <ejb-name>PhysicianSessionEJB</ejb-name>

   >         <stateless-session-descriptor>

   >           <pool>

   >             <max-beans-in-free-pool>1000</max-beans-in-free-pool>

   >             <initial-beans-in-free-pool>0</initial-beans-in-free-pool>

   >           </pool>

   >           <stateless-clustering>

   >           </stateless-clustering>

   >         </stateless-session-descriptor>

   >         <transaction-descriptor>

   >           <trans-timeout-seconds>0</trans-timeout-seconds>

   >         </transaction-descriptor>

   >         <enable-call-by-reference>True</enable-call-by-reference>

   >     <jndi-name>PhysicianSessionEJB.PhysicianSessionHome</jndi-name>

   >       </weblogic-enterprise-bean>

   >     </weblogic-ejb-jar>

Procedure 2: Generate new deployment descriptor and EJB files.

1. In the command window, change to the C:\medrec_tutorial\src\physicianEar\physSessionEjbs\com\bea\medrec\controller directory.

2. Change the suffix of PhysicianSessionEJB.ejb to .java. For example:

   >     copy PhysicianSessionEJB.ejb PhysicianSessionEJB.java

   The .ejb suffix exists to tell the wlcompile ant script to run EJBGen on the EJB source files when it first compiles MedRec as described in Tutorial 7: Compiling Applications Using the Split Development Directory.

3. Enter the following command to invoke EJBGen on physicianSessionEJB.

   1. If you are using WebLogic Server 8.1 Service Pack 1 or higher, issue the following command:

   >     java weblogic.tools.ejbgen.EJBGen PhysicianSessionEJB.java -d
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs
   >     -descriptorDir
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF

   The -d flag tells EJBGen to write the Java files to the C:\medrec_tutorial\build\physicianEar\physSessionEjbs directory. The -descriptorDir flag specifies the directory for the deployment descriptor files relative to the output directory specified with the -d flag.

   EJBGen reports on its progress as follows:

   >     Loading source file PhysicianSessionEJB.java...

   >     Constructing Javadoc information...

   >     EJBGen 2.15

   >         Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\com\bea\m
   >     edrec\controller\PhysicianSessionHome.java

   >         Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\com\bea\m
   >     edrec\controller\PhysicianSession.java

   >         Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     ejb-jar.xml

   >         Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     weblogic-ejb-jar.xml

   >         Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     ejbgen-build.xml

   1. If you are using a WebLogic Server 8.1 release earlier than Service Pack 1, your version of EJBGen does not support the -descriptorDir flag, so you will have to create the C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\directory and manually copy the generated files to it. Begin by issuing the following command:

   >     java weblogic.tools.ejbgen.EJBGen PhysicianSessionEJB.java

   EJBGen reports on its output:

   >     [Info:]  Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\\ejb-jar.
   >     xml

   >     [Info:]  Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\\weblogic
   >     -ejb-jar.xml

   >     [Info:]  Creating
   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\ejbgen-bu
   >     ild.xml13 warnings

   Next, move the newly generated descriptor files to their proper directories as listed below:

   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     ejb-jar.xml

   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     weblogic-ejb-jar.xml

   >     C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\
   >     ejbgen-build.xml

Procedure 3: Redeploy the application and view the generated files.

1. Move to the physicianEar subdirectory:

   >     cd c:\medrec_tutorial\src\physicianEar

2. Redeploy the tutorial_deployment application. For example:

   >     ant -f deploy.xml

3. Open the Administration Console by navigating in a browser to http://localhost:7101/console.

4. In the left-hand panel of the Administration Console, expand Deployments>Applications>tutorial_deployment.

5. Click physSessionEjbs. The right pane shows the configuration of the EJB module.

6. In the right pane, select the Descriptors tab.

7. Click ejb-jar.xml and weblogic-ejb-jar.xml to view them and compare them to the original versions you viewed in the first procedure.

   The new versions of PhysicianSessionHome.java and PhysicianSessionHome.java are in the C:\medrec_tutorial\build\physicianEar\physSessionEjbs\com\bea\medrec\controller directory.

Best Practices

Use EJBGen to develop the EJB component your application. You can simplify your EJB development and code maintenance by writing just the bean files and annotating them with EJBGen tags, and then generating all the remaining files—the home interface, the local interface, the deployment descriptor files—using EJBGen.

The Big Picture

The scripts that compile and deploy MedRec use EJBGen to generate most of the EJB files in the application.

The PhysicianSession bean contains all of the information necessary for EJBGen to generate the EJB descriptor files and the home interface. You can view the EJBGen annotations by opening C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF\com\bea\medrec\controller>PhysicianSession.java in a text editor.

For example, the following tags define the pool and timeout settings that you see in the generated weblogic-ejb-jar.xml:

>     /**

>      * <p>Session Bean implementation for physician functionality
>     including

>      * access MedRec web services.</p>

>      *

>      * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.

>      *

>      * EJBGen tags:

>      * @ejbgen:session

>      *   max-beans-in-free-pool = 1000

>      *   initial-beans-in-free-pool = 0

>      *   trans-timeout-seconds = 0

>      *   type = Stateless

>      *   enable-call-by-reference = True

>      *   ejb-name = PhysicianSessionEJB

>      *

>      * @ejbgen:jndi-name

>      *   remote = PhysicianSessionEJB.PhysicianSessionHome

>      */

Related Reading

- EJBGen Reference
- WebLogic Server Workshop

In the left-hand navigational area, expand the Developing Enterprise Java Beans topic to learn about using WebLogic Server Workshop to create EJBs.

- Deployment Descriptors, in Programming WebLogic Enterprise JavaBeans