MyEclipse EJB 2.x Tutorial (Using XDoclet)

Outline

1. Preface

This document was written using MyEclipse, and the JBoss 3.2.5 application server, although later versions of JBoss are supported and will operate similarly. All screenshots are based upon the default user interface settings for MyEclipse and Windows XP. If you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.

2. Introduction

This Tutorial presents the basic features, concepts, and techniques for rapidly getting started in the development of EJB 2.0-compliant J2EE Enterprise Java Beans using the MyEclipse EJB Tools.

Please note, if you are using EJB 3.0-compliant Enterprise Java Beans, MyEclipse also has sophisticated tools for their development as well. However, for information on EJB 3.0 development you should really stop reading this tutorial and read our EJB 3.0 Overview or EJB 3.0 Tutorial instead.

Specifically, this document presents how to:

• Create a MyEclipse EJB Project
• Create a Session EJB
• Configure an EJB Project to use XDoclet attribute-oriented programming capabilities (optional, recommended)
  • Use XDoclet code generation to create EJB and Home interfaces, lookup utilities, and J2EE and application server specific deployment descriptors
• Package and deploy a Session EJB

3. Requirements

Below is a list of software requirements need to replicate the examples presented in this document:

1. MyEclipse (see Resources for a download link)
2. JBoss Application Server (see Resources for a download link)

4. MyEclipse EJB Project and Tools Overview

Before we begin, here's a quick word about MyEclipse EJB Projects and Tools. First, what is a MyEclipse EJB Project and why is it important?

A MyEclipse EJB Project is:

A basic Eclipse Java project that includes a META-INF directory and additional metadata required by the MyEclipse EJB Tools, such as the EJB Creation Wizards and the MyEclipse Deployment Services. Thus, standard Eclipse and 3rd party Java tools may be used within a MyEclipse EJB Project.   

You can distinguish MyEclipse EJB Projects from other project types by the project icon,  . Figure 1 depicts the structure of an example EJB project that we will create during this document. Note the META-INF folder located under the src folder and the metadata files. META-INF is a special J2EE directory that contains the Java MANIFEST.MF file, the standard EJB deployment descriptor (ejb-jar.xml) and application server specific deployment descriptors, e.g., jboss.xml. The MyEclipse New EJB Project Wizard creates the META-INF folder as a child of a Java source folder to enable it for deployment to your favorite application server that supports an EJB container.

Figure 1. Example EJB Project

Also depicted in Figure 1 are the project's metadata files. Note these files are typically hidden in the default Eclipse views due to the default use of the .* filename filter that hides dot prefixed files. The .project and .classpath files are standard Eclipse project information files. The .mymetadata and .xdoclet files are MyEclipse metadata files and are required for MyEclipse tools to function properly. Do not delete or modify these files. Also, if your project is managed by a source-code management tool such as CVS be sure to include all these files as part of the project.

MyEclipse EJB Development Tools include:

• EJB Creation Wizard
• EJB XDoclet Attribute-oriented programming environment
  • Java editor enhancements to support code completion for XDoclet annotations and J2EE APIs
  • Auto-generation of EJB and Home interfaces and lookup utilities
  • ejb-jar.xml and application server specific deployment descriptor generation
• XML editor for deployment descriptor customization
• EJB Deployment Services

A special note about attribute-oriented programming and XDoclet technology: MyEclipse provides sophisticated support for attribute-oriented programming using XDoclet technology and tools for EJB 2.0 development (see References ). MyEclipse EJB Tools, such as the EJB wizards and code generation features, rely on XDoclet for much of their operation. For example, the EJB Creation Wizard generates XDoclet 1.2 compliant EJB bean classes for Session, Entity, and Message-driven EJB's.  XDoclet is then employed to auto-generate and maintain the bean's home and remote interfaces as well as the ejb-jar.xml deployment descriptor.

While you are not required to use MyEclipse XDoclet capabilities in your development process for EJB 2.0 development, we believe the productivity gains from doing so for EJB 2.0 development far exceed counter arguments against the use of attributes. We support our recommendation for the use of attribute annotations by noting that: 1) native attribute support have been incorporated into the the Java SDK, and 2) attribute annotations are the primary mechanism employed by the EJB 3.0 specification and greatly simplify EJB definition and maintenance efforts.

5. Creating an EJB Project

This section introduces the steps for creating an example EJB Project named "firstejb".

1. Launch the EJB project wizard by clicking on the EJB Project option from the new toolbar menu:
   
   
   Figure 2.  Opening EJB Project wizard
   
   
2. Enter firstejb into the Project Name field
3. Select J2EE 1.3 option for Specification Level.

The remaining fields are prepopulated from the MyEclipse EJB Project Template. This template is defined under the MyEclipse J2EE Project preferences.  Table-1 describes each of the fields for the New J2EE EJB Project wizard shown in Figure 3.

Figure 3. New EJB Project creation details

Table 1.  New EJB Project wizard field definitions

5. Select Finish

Completing the wizard creates and configures the firstejb EJB Project. Figure 5 depicts the structure of the new project from the MyEclipse perspective. To open the MyEclipse perspective, from the MyEclipse menubar select Window > Open Perspective > Other and select the MyEclipse perspective, . The Java Package Explorer will be automatically opened as part of the perspective.  However, if you close it for some reason, you can manually reopen it by selecting Window > Show View > Java > Package Explorer.

Figure 4 depicts the new EJB project structure. Newly created EJB projects will not include a default ejb-jar.xml file. There are 2 reasons for this: 1) the deployment descriptor will be created later using  XDoclet technology and 2) a valid ejb-jar.xml file requires at least 1 EJB definition. At this point in the process, no EJB's exist and a corresponding ejb-jar.xml file would appear in your project with an error marker as a result. The alternative is a simple warning message in the Problems view that identifies that the required ejb-jar.xml deployment descriptor does not yet exist in your project.  This file will be created later in this tutorial.

Figure 4.  EJB Project layout

6. Creating a Session EJB - Part-1

EJB development in MyEclipse uses a combination of EJB wizards and integrated XDoclet support.  Every EJB consists of 3 basic parts:

1. The EJB Remote interface class that declares the business operations that are available to a client
2. The EJB implementation class, also known as the bean class, that contains the business logic
3. The EJB Home interface class, which controls the bean's life-cycle

The bean class is the primary implementation concern since it provides the EJB's functionality. From the bean class using XDoclet annotations, the bean's Remote and Home interfaces can be automatically generated as well as the EJB's entry within the ejb-jar.xml deployment descriptor. In this 2-part example, we demonstrate the process for creating a stateless session bean known as the Trader EJB. Part-1 focuses on the use of the MyEclipse EJB Creation Wizard and XDoclet support to create a basic deployable Trader EJB. Part-2 will introduce the process for implementation of business services or functions to the Trader EJB.

The example Trader EJB will provide simplified services for the sale and purchase of stocks. Because the scope of this document is a quick introduction to MyEclipse EJB development features, the Trader EJB does not address transactions or integration of enterprise resources such as databases or message queues.

We begin by creating the Trader bean implementation class using the EJB Creation Wizard. Following creation of the Trader bean class, we will demonstrate how to generate the Remote and Home interfaces as well as the ejb-jar.xml entry for the bean.  

1. From the main workbench window select File > New > Other to open the New Resource Wizard.
2. Expand the  J2EE > EJB folder and select  Session EJB as shown in Figure 5.
   
   
   Figure 5. New EJB wizard
   

3. Select Next.
   This will present a form for the new Session Bean's details (see Figure 6)
4. 
   
4. In the Source Folder field, ensure that the source folder within your EJB project is entered correctly since this is where your new EJB class will be placed.
   

5. In the Package field, enter the full package name for the Trader bean class, e.g., com.genuitec.trader.ejb. Use the "Browse..." button to view and select an existing package. If the package does not exist it will be created as part of the completion process.

NOTE: XDoclet's default configuration requires the package name end with '.ejb'. Other package suffixes may be used, but doing so requires updating the project's EJB XDoclet settings manually before generation.

6. In the Name field enter TraderBean.
   

   This is the name of the EJB bean implementation class that will be created. The "Bean" suffix is a convention used to identify bean implementation classes.  The EJB wizard will remove this suffix when creating the XDoclet tags for related EJB files.

7. Choose default values for all remaining fields.
   
   
   Figure 6.  New Session EJB details
   

9. Select Finish

Completing this wizard results in the creation of the TraderBean implementation class. The Java editor will be automatically opened on this class as shown in Figure 7.  Note how the EJB Creation Wizard automatically inserted XDoclet EJB tags that define the EJB interface and deployment details.  

10. Browse the resulting TraderBean.java code in the Java editor.

Figure 7. TraderBean source with XDoclet tags

11. Revise the TraderBean XDoclet jndi-name tag to be more consistent with examples used in other MyEclipse documentation.

7. Using XDoclet EJB Facilities

Before continuing to Part-2 of the Trader EJB development process, we need to introduce the steps for the configuration and use of XDoclet EJB features. The benefit of XDoclet  technology is that a tag processor is able to analyze source files annotated with XDoclet information and generate dependent source code and configuration resources specific to the annotations. XDoclet relies on an ANT script to specify its execution environment and code generation tasks. An XDoclet tag consists of an annotation model that maps 1 or more annotations to corresponding ANT subtasks. MyEclipse allows you to configure and customize the subtasks to execute and their default operating values.

By default, MyEclipse EJB projects are not automatically configured to use XDoclet features. This section presents the steps for enabling and configuring the firstejb  EJB project with XDoclet support and executing XDoclet code generation to derive the Trader EJB's dependent source code and deployment components.

7.1 XDoclet EJB Configuration

We begin by adding the Standard EJB XDoclet configuration to the firstejb project. The end goal of this section is to produce the XDoclet configuration that will be used to create the ANT script that MyEclipse will execute to generate the additional EJB artifacts required to deploy the Trader EJB.

7.1.1 Basic EJBDoclet Configuration 

1. Open the MyEclipse project properties page.  Right-click the firstejb  project in the Package Explorer View and select Properties > MyEclipse-XDoclet (see Figure 8)

Figure 8. MyEclipse-XDoclet configuration page

2. Select the  Add Standard  button.
3. Select Standard EJB configuration followed by OK as shown in Figure 9. 

In addition to the preconfigured XDoclet modules provided by MyEclipse you may create your own custom XDoclet configurations. The process for integrating a custom XDoclet module is beyond the scope of this document.

Figure 9. Adding Standard EJB configuration

Once the Standard EJB module has been added to the list, use the mouse to select it to reveal the doclets it contains.  Notice that the ejbdoclet appears in lower left-hand list. The subdoclets under the ejbdoclet's contain both required and optional subtasks. Many of the subtasks are not applicable to a simple stateless session bean such as Trader EJB.


Figure 10. Default subtasks for Standard ejbdoclet

4. Remove unneeded subtasks by right-clicking each subtask in the lower left panel and selecting Remove. 
5. Continue this process until only the subtasks shown in Figure 11 remain.  Each of the items in this configuration represent EJB XDoclet subtasks. A link to a detailed description of @ejbdoclet and its subtasks is provided in the Resources section. 
6. (Optional) If a non-default source folder was specified when the project was created you must update the project relative path attributes of the following elements ejbdoclet > destDir, deploymentdescriptor > destDir and fileset > src tasks. Select each of these elements in the bottom left panel and then review and revise their respective properties in the lower right panel.

Figure 11. XDoclet EJB subtasks required by Trader EJB

7. Configure this project's XDoclet build file policy by selecting the corresponding Build page.
   
   Note: If this is a new project, the Build policy is set to the default policy, so you may skip to step 9.
   
   
8. Select Use dynamic build specification  policy as shown in Figure 12. 
   
   If you are using an existing project that already contains XDoclet configurations, you can choose to delete unnecessary xdoclet-build.xml file.  It is no longer needed.  For a more detailed explanation of these new policies see Table 2. By default new projects are set to use the dynamic build policy.  You can modify this default by going to Window > Preferences > MyEclipse > XDoclet > Build preference page.
   
   
   Figure 12. XDoclet Build File Policy Configuration
   
   Table 2 - Description of XDoclet build policies
   
   

   Field	Description
   Use dynamic build specification [Recommended]	Instructs the XDoclet processor to dynamically interpret its build specification directly from a project's XDoclet configuration properties. No xdoclet-build.xml file is created or required. This policy is recommended since the current project build environment is always used.
   Use xdoclet-build.xml file	Instructs the MyEclipse-XDoclet Property Manager to generate a new xdoclet-build.xml when a project's XDoclet configuration properties are updated and saved, and for the XDoclet processor to use the xdoclet-build.xml file during the code generation process. Warning: A project's xdoclet-build.xml file is over written by the new version whent the project's XDoclet configuration properties are revised. Only use this policy when you must manually manage the xdoclet-build.xml file.

   
   
9. Select  OK .  

During completion of XDoclet configuration process are saved to the local file named . xdoclet. Additionally if the "Use xdoclet-build.xml file" build policy is enabled then MyEclipse will generate a file named  xdoclet-build.xml from your new XDoclet settings and store this file in the root directory of your project.

This completes the basic XDoclet EJB configuration process. The next section demonstrates how to configure XDoclet EJB subtasks for your specific application server.

7.1.2 Configuring Application Server XDoclet (optional)

XDoclet is able to generate application server specific deployment descriptors. This section demonstrates configuring an XDoclet @ejbdoclet with a subdoclet for the JBoss application server. The list of application servers supported by XDoclet can be viewed in the pop-up menu shown in Figure 13. 

Note: later in this section we will demonstrate deployment of the firstejb to a local JBoss 3.2 server. Therefore we will use the JBoss subtask.

1. Right-click ejbdoclet and select Add from the context-menu .  
2. Select the jboss from the doclet subtask, followed by OK as shown in Figure 12.
   
   
   Figure 13.  Adding JBoss subtask to ejbdoclet
    

3. Set the following jboss properties as shown in Figure 14.

   Version = 3.2
   destDir = src/META-INF
   

   
   
   Figure 14.  Setting jboss subtask attributes
   
   
4. Select OK .

7.2 Running XDoclet Code Generation

Once you've configured your project's XDoclet settings you can run the XDoclet code generator at any time. Typically you should execute XDoclet after each change to the XDoclet EJB configuration or application server settings or when you modify the XDoclet annotations of any EJB bean implementation class.

Now is a good opportunity to execute XDoclet on the firstejb project and test the new XDoclet settings as Trader EJB has not yet been extended with new XDoclet-annotated business methods.

1. To run XDoclet on the firstejb right-click on the project and select MyEclipse > Run XDoclet  from the context-menu (see Figure 15).

 
Figure 15. Starting XDoclet code generation on EJB project

2. Monitor the Console view for anomalous output messages from the xdoclet-build script. Figure 16 depicts XDoclet progress messages as the TraderBean class is processed.

Figure 16.  Console output of Run XDoclet action

Upon XDoclet's completion the firstejb project should include new versions of the Trader and TraderHome interfaces and the ejb-jar.xml and jboss.xml deployment descriptors. Figure 17 depicts the initial generation of these new project resources.

Note: When we created the TraderBean.java class during Section 5, we specified its Java package name as com.genuitec.trader.ejb and emphasized that the package name end in ".ejb". This is because the Standard EJB XDoclet packageSubstitution subtask creates a corresponding Java package name ending in ".interfaces"  and adds generated EJB and Home interfaces to it.  In our example, the com.genuitec.trader.interfaces package was created and it contains the for the Trader EJB and TraderHome interfaces. If you did not follow this package naming convention and are using default XDoclet setting some of the files may not be generated.

   
Figure 17.  Contents of EJB project before and after XDoclet generation

8. Creating a Session EJB - Part-2

In Part-1, Creating a Session EJB, we demonstrated the process for creating the TraderBean class. In this section we will add business methods as well as XDoclet annotations to the TraderBean class and then use XDoclet to update the Trader and TraderHome interfaces created in Section 7.2.

When we created the initial TraderBean.java class, the EJB Creation Wizard added an example business method that you can use as a pattern for adding your own business methods. Notice that this method includes the javadoc tag @ejb.interface-method. This custom ejbdoclet tag identifies the method as an implementation of an EJB interface method. When XDoclet is run on the this class, the Trader.java EJB interface class will be revised to include all methods with the @ejb.interface-method annotation.

1. Begin by adding the following the following 2 methods to the TraderBean.java class and saving your changes.

2. Next rerun XDoclet on the firstejb project to resynchronize the Trader and TraderHome classes and the deployment descriptors (see Section 7.2 for details).

3. Open the Trader.java EJB interface in the Java editor and notice the addition of the buy() and sell() business methods.
   

As you enter XDoclet annotations in the Java editor, note that XDoclet code completion features are available. MyEclipse extends the Java editor with the addition of this feature as well as the ability to invoke code completion on EJB APIs.

3. From the Java editor open on the TraderBean.java go to the class javadoc and place the cursor in the "view-type" XDoclet annotation.

Enter ctrl+space to invoke code completion suggestions for this annotation.


Figure 18.  XDoclet property value code completion

1. Place your cursor on a new line after the jndi-name tag.
2. Enter Ctrl+Space to see XDoclet code completion suggestions for other available @ejb.bean tags not already specified.
   
   
   Figure 19. XDoclet property code completion

9. Deploying an EJB Project

The Enterprise Archive (EAR) is the only required deployment model specified by the J2EE specification.  Yet, the specification makes provision for application server specific deployment models.  Application servers such as JBoss and Weblogic support direct deployment of EJB Jar archives. A restriction of direct EJB Jar deployment is there is no provision for deployment of optional packages required by an EJB jar archive. See Section 8.2 of the J2EE 1.4 specification for optional package deployment details.

This section presents abbreviated instructions for deploying the firstejb project to a local JBoss 3.2 instance as a single EJB Jar archive.  Please view the Application Server Tutorial for a more thorough guide to the deployment process. 

1. Configure a JBoss 3.2 application server from the MyEclipse Application Server preference pages

   1. From the MyEclipse menubar open JBoss server configuration preferences; select
      Window > Preferences > MyEclipse > Application Servers > JBoss 3.
   2. Select the Enable radio button
   3. Select Browse... for the JBoss root installation directory
   4. Select the JBoss3 JDK preference page and select a full JDK, not just a JRE.  Note: You may have to add a new JDK if only a JRE is listed.

2. Deploy the firstejb project to the JBoss 3 server

   1. From the MyEclipse toolbar select the deploy icon,    or right-click firstejb project and select MyEclipse >Add and Remove Project Deployments... This will open the Deployment dialog.
   2. Select firstejb in Project field.  Select Add... and select the configured JBoss 3 server.
   3. Choose either Packaged or Exploded deployment; JBoss supports both deployment modes.

3. Launch JBoss Application Server

   1. From the MyEclipse toolbar select the application server management icon,  and expand the menu to  JBoss3 > Start action

4. Monitor the JBoss stdout and stderr messages presented in Console view. 

   1. Inspect the message log for an that EJB was successfully deployed as shown in Figure 18.
      

10. Testing an EJB

Standalone EJB testing requires a distributed test client. Creation of a test client for the Trader EJB is a non-trivial effort that is beyond the scope of this document. For efficiency purposes we have elected to defer this topic to the MyEclipse Enterprise Application Tutorial. That document describes the process for creating an Enterprise application composed of the Trader EJB and a simple web client that are packaged and deployed as a single unit. The web client serves as a test client.

11. Customizing EJB Project Preferences

MyEclipse provides a number of customizable preferences. You are encouraged to familiarize yourself with each of these. We have already seen several EJB Project wizards and dialogs with prepopulated fields. The value of many prepopulated dialog fields is frequently derived from the MyEclipse system preferences. Two MyEclipse preferences that you should be aware of are the J2EE Project Templates preferences and the EJB Project Deployment Policies.  See the Advanced Features  section for a description of the later.

To access the MyEclipse preferences do the following:

From the menubar select Window > Preferences > MyEclipse > J2EE Project > EJB Project (See Figure 21).

Figure 21. MyEclipse EJB Project Template preferences

Note: changing the EJB Project template folders will only affect new projects, not existing projects.

12. Advanced Features 

This section describes working with EJB applications that consists of an EJB Project and additional Java projects. Please note that if your EJB Project depends upon 3rd party Jars then you must use an Enterprise Project to incorporate the EJB Project and the 3rd party libraries into a single Enterprise Archive (EAR) deployment unit. To learn more about Enterprise Projects and EAR deployment visit the EAR Project Development Tutorial.

12.1 Dependent Java Project Setup and Deployment Policy Configuration

Frequently the codebase of an EJB application may be partitioned between a primary MyEclipse EJB Project and 1 or more Java projects upon which the EJB project depends. Typically the role of these dependent Java projects is to localize common or shared code that has other uses beyond that of the EJB project. MyEclipse can be configured to package and merge the output of dependent Java projects into the deployment of an EJB Project. In this section we introduce the procedure for establishing project dependency and configuring deployment policies for dependent projects.

12.1.1 Establishing a Java Project dependency,

A dependent Java project is defined through the EJB Project's Build Path properties . To access the Build Path properties dialog from the target EJB project's context-menu select Properties > Java Build Path > Projects. See Figure 22 for an example of establishing the Logging Java project as a dependent project of the firstejb project. Doing this enables  firstejb project source code to have access to the classes defined by an example Logging Java project. Code completion, validation, and other tools are able to reference Logging project resources.

Figure 22. Making the Logging Java project a dependent of the  firstejb EJB Project

12.1.2 Configuring the Deployment Policy of Dependent Java Projects

The MyEclipse EJB Project Deployment Service provides 2 policies that define how dependent Java projects are processed during EJB Project deployment. Table 2 describes each of these policies.

Table 2. Dependent Java Project Deployment Policy descriptions

Figure 23. MyEclipse default dependent Java project deployment preferences

Individual EJB Projects may override the system default behavior from the MyEclipse-EJB Project properties dialog (see Figure 24). 

Figure 24. MyEclipse EJB Project deployment properties

13. Summary

This concludes your introduction to creating a session EJB with MyEclipse. Additional Tutorial documents are available that introduce working with Web Projects, editing, application server configuration, enterprise application projects and database development. For more information visit the MyEclipse Tutorial library.

14. User Feedback

If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum.

15. Resources

• Download JBoss Application Server from RedHat.
  
• Download the MyEclipse.
  
• To learn more about XDoclet visit the  official XDoclet site.
  
• To learn more about @ejbdoclet and its subtasks click here,  link.
  
• Visit the MyEclipse Tutorial Library for more MyEclipse tutorials.