The Two-Page Tutorial^tm Series

Creating an EJB In Eclipse Using the Lomboz J2EE Plugin

Carlos Valcarcel, Chief Architect

EinTech, Inc.

Company and product names mentioned in The Two-Page Tutorials^tm are trademarks or registered trademarks of their respective companies.

The Two Page Tutorial – Creating an EJB In Eclipse Using The Lomboz J2EE Plugin

This tutorial assumes that the Lomboz J2EE plugin is installed and properly configured and that the JBoss J2EE-compliant application server is also installed and available. When this tutorial is complete you will have a deployed stateless session EJB running in the JBoss EJB container and a test client to prove connectivity.

The Steps

Start Eclipse.
From the main menu select File->New->Lomboz J2EE Project.
The J2EE Project Creation Wizard will appear. In the Project Name field enter “EJBExample”. Press Next.
In the Source tab, if the Build output folder is not EJBExample/bin change it to EJBExample/bin. Press Next.
In the Create J2EE Container panel select the EJB Containers tab. Press Add.
Enter “ejb” as the EJB container name. Press OK. The name “ejb” should appear in the list of EJB Containers.
Select the Servers tab. Under Type select JBoss or select the JBoss tab.
Set the JBoss home directory to the absolute path where JBoss is installed (or use the “…” button to navigate to the JBoss home directory).
Change Servlet Container to “Tomcat-Catalina” and change Version to “3.0.x”. Press Finish.
Select the EJBExample project in the Package Explorer view.
From the main menu select File->New->Lomboz EJB Creation Wizard.

12. Set Package to “ejb.session” and Name to “MyEJB”. Press Finish.

Right click on MyEJBBean.java and select Lomboz J2EE…->Add EJB Method….
Enter into the Method Signature field:

public String sayHelloTo(String name).

15. Press Finish.

16. If MyEJBBean.java is not on display in the editor double-click on the file to make it appear.

In the editor go to sayHelloTo() change

return null;

return “Hello “ + name + “.”;

Save the MyEJBBean.java file (press control-s).
Right click on MyEJBBean.java and select Lomboz J2EE…->Add EJB to Container…. From the Please select a container dialog select EJB[ejb]. Press OK.
The Lomboz J2EE View should be visible at the bottom of the workbench. If it is not then select the view from the main menu by going to Window->Show View->Lomboz J2EE View. If the tab for Lomboz J2EE View is visible at the bottom of the workbench then select the tab.
Confirm the EJB has been added by looking in the Lomboz J2EE View and opening the EJBExample->ejb container. The class ejb.session.MyEJBBean should be below the entry for the JBoss server. If it is not visible press the Refresh button in the upper right-hand corner of the J2EE view (the Refresh button is the one with the two circular arrows).
Generate the various EJB classes and support files: in the Lomboz J2EE View right click on the “ejb” container and select Generate EJB Files.
In the J2EE view right click on the JBoss server and select Debug Server. Wait until output to the Console window completes.
Return to the J2EE view (select the Lomboz J2EE View tab), right click on the “ejb” container and select Deploy. A message will appear that reads something like:

[MainDeployer] Deployed package: file:/C:/jboss-3.0.3_tomcat-4.1.12/server/default/deploy/ejb.jar

From the main menu select File->New->Java Project. Enter the Project name as “EJBExampleClient”. Press Next.
Select the Projects tab. Select the checkbox next to EJBExample. Press Finish.
Select the EJBExampleClient in the Package Explorer. From the main menu select File->New->Lomboz EJB Test Client Wizard.
Enter the following information:

Package: ejb.client

Name: EJBClient

EjbHome: ejb.session.MyEJBHome

Ejb Interface: ejb.session.MyEJB.

TargetServer: JBoss

Version: 3.0.x

Press Finish.
Open the EJBExampleClient->src folder. Double-click on EJBClient.java to display the file in the editor.
Go to testBean(). Change

//System.out.println(myBean.callYourMethod());

System.out.println(myBean.sayHelloTo(“Kitty”));

Save the EJBClient.java file.

33. From the main menu select Run->Run As->1 Java Application. The Console window will display the message:

Hello, Kitty.

Creating an EJB In Eclipse Using The Lomboz Plugin

Carlos Valcarcel, Chief Architect

Level: Intermediate

Summary

The Lomboz plugin from ObjectLearn adds J2EE development support to Eclipse. Java Server Pages, servlets and Enterprise JavaBeans are supported directly through the creation of either a web container or an EJB container. The plugin also takes care of creating either a war (web archive) file or a jar file containing all of the EJB classes and deployment files needed to deploy into a J2EE app server. In this tutorial we will look at how to use the plugin to create an EJB that will be deployed on the open-source JBoss application server.

The JBoss J2EE Application Server

If you do not already have the JBoss app server I recommend downloading JBoss from http://www.jboss.org (download the version that includes Tomcat-Catalina). JBoss is free, full-featured, industrial-strength and trivial to install: once you have unzipped JBoss into a directory it will be ready to go (just make sure you have JAVA_HOME declared in your environment as the Tomcat component uses tools.jar).

Installing the Lomboz J2EE Plugin

The Lomboz J2EE Eclipse plugin is not a standard part of the Eclipse package. As such we will go over the details of installing and configuring the plugin prior to explaining the tutorial steps.

If you do not have the Lomboz plugin go to http://www.objectlearn.com, follow the links to the download area, fill in the questionnaire and download the latest version. This tutorial was written using Lomboz version .97.

Install the plugin by exiting Eclipse, if you have it running, and unzipping lomboz.097.b202.zip into your Eclipse installation directory. Do not unzip the file into the eclipse/plugins directory as the zip file already includes the plugins directory as part of the paths it will create.

Once you’ve installed the plugin you need to make it available from within Eclipse. Start Eclipse and from the main menu select Window->Customize Perspective. Open up File > New and check the seven (7) items that starts with Lomboz. We will not be using them all, but later you can always unselect items you decide not to use. Under Window >Show View check Lomboz J2EE View and under Other check Lomboz Actions.

From the main menu select Window->Show View and select Lomboz J2EE View. The J2EE View should appear as a new tab in the console output area at the bottom of the Eclipse workbench.

The only external dependency I found was that $JAVA_HOME/bin must be in the PATH environment variable available to Eclipse. For Win users this means add %JAVA_HOME%/bin to the User Variable PATH in the System Properties. Unix developers can either add $JAVA_HOME/bin to their shell profiles or to any shell script that starts Eclipse. The Lomboz plugin includes XDoclet software which uses the javadoc executable when it generates EJBs so the path must be set prior to starting Eclipse.

There are a few internal dependencies that must be checked within Eclipse prior to using the Lomboz plugin. First, the plugin expects the .class files to be located under the bin directory instead of the classes directory. This can be corrected one of three ways:

1. Using the main Preferences dialog, set Java->New Project->Output Location Name to bin

2. Setting the Build Output Folder field to {project name}/bin from within the New Project dialog. The Build Output Folder field is located in the second configuration panel (after pressing Next on the panel that requires the project name).

3. Once you have created the project, right-click on the Project name and select Properties. From the Project Properties dialog select Java Build Path and set the Build Output Folder field to {project name}/bin.

Remember to use only one of the three methods listed above. The requirement to use the bin directory is real and as such must be set for Lomboz to function properly. I personally prefer to set the Build Output Folder specific to a project. Saving .class files under the bin directory is not idiomatic to Java so setting it in the global Preferences would be convenient, but not typical Java..

The next two internal configurations are specific to Lomboz. The first has to do with the path to the compiler used by the servlet container of the underlying app server. Under the main Preferences dialog select Lomboz and enter the absolute path to the tools.jar file. The servlet container will use this path to find the compiler needed to compile JSPs. True, we will not be using JSPs in this tutorial, but I would prefer to make sure that the app server and the plugin are both configured properly.

The second Lomboz-specific configuration is the choice of app server. Still using the main Preferences dialog select Lomboz->Application Servers and select the JBoss tab. Enter the absolute path to the JBoss installation directory in the Server HomeDirectory field. Do not include any JBoss sub-directories; the name of the home directory is all that is required. Select the Servlet Container as Tomcat-Catalina and the version as 3.0.x. As of Lomboz version .97 I have found that the plugin Properties module does not seem to remember any servlet container selection except Jetty (which is the default). In any case, select Tomcat-Catalina and press OK.

The Lomboz J2EE plugin

Now that you have installed and configured the plugin we will create a stateless session EJB. As usual, the Two-Page Tutorial^tm (TPT) should be enough to take you from beginning to end, creating both the EJB and a test client that calls the EJB, but the following explanation will put many of the steps into an Eclipse perspective.

Standard Caveat: Eclipse gives developers a number of ways to do certain tasks. For the sake of simplicity I am always going to choose the most explicit way of performing a task, but recognize that there may be shorter ways to accomplish the same goal.

Also, all input will be shown in double-quotes, but do not enter the double-quotes into the input fields.

Creating and deploying the EJB

After starting Eclipse select File->New->Lomboz J2EE Project from the main menu. The J2EE Project Creation Wizard dialog will appear requesting the name of the project. In the Project Name field enter “EJBExample” and press Next[1].

In the Java Settings panel of the wizard select the Source tab if it is not already displayed. Change the Build output folder to “EJBExample/bin”. This is purely a Lomboz-ism. If the class files are not found in the bin directory by the plugin the deployment step will fail. Press Next.

The Create J2EE Container panel is where we tell the plugin where our EJB files are going to live. Select the EJB Containers tab and press Add. An input dialog will appear requesting the name of the container. The name you give the container does not matter, but adhere to standard directory conventions. Enter the name “ejb” and press OK. The new container name should appear in the container list.

The last information to be entered is under the Servers tab directly to the right of the EJB Containers tab. Under Type select JBoss or select the JBoss tab (both actions are equivalent). There are three things do here:

1. Set the JBoss home directory to the absolute path where JBoss is installed (or use the … button to navigate to the JBoss home directory).

2. Set Servlet Container to “Tomcat-Catalina”

3. Set Version to “3.0.x”.

Press Finish. The plugin will create the project and a src directory as well as add a number of support packages.

If the EJBExample project is not already selected in the Package Explorer view then select it. From the main menu select File->New->Lomboz EJB Creation Wizard (Fig. 1).

Figure 1. The EJB Creation Wizard

We only care about the top two sections of this dialog. In the Package field enter a package name of “ejb.session”. In the Name field enter a name of “MyEJB”. Press Finish. The Package Explorer will display the ejb.session package under the src directory and MyEJBBean.java will be under the package. The Java editor will automatically open displaying the MyEJBBean.java file.

A couple of things to notice: MyEJBBean is bereft of internals and the class is declared abstract. The plugin will take care of creating a proper concrete class later when we generate the files required for deployment, but we will add our business logic to MyEJBBean. Methods to support the business logic are the only things that should ever go into MyEJBBean.

Speaking of which, return to the Package Explorer view. Right-click on MyEJBBean.java and, from the bottom of the pop-up menu, select Lomboz J2EE…-> Add EJB Method…. DO NOT USE pop-up menu item New->Lomboz EJB Method Wizard. Creating methods using the pop-up menu item New->Lomboz EJB Method Wizard does not appear to work in version .97 of the plugin (if you want to try it, go ahead. Nothing will happen after you enter the method signature and press Finish).

Another point to remember: use the Lomboz EJB Method Wizard to add methods to your EJB as it takes care of adding the Javadoc comment block to the methods to be declared accessible to your EJB clients. Once you have used the tool for some length of time you can add the methods manually (i.e. bypass the wizard), but make sure you understand what the plugin’s expectations are for the source code or the generated stub code will not be complete.

When the Create a New EJB Method dialog appears enter into the Method Signature field:

public String sayHelloTo(String name)

As sayHelloTo() is not going into the home interface (which normally has just creation and finder methods) we leave the Method Type set to Business Method. Also we will only be accessing MyEJBBean remotely so leave the Interface Type set to Remote Interface. Press Finish.

If MyEJBBean is not on display in the editor then double-click on the filename in the Package Explorer. Go to sayHelloTo() and change the line that reads

return null;

return “Hello, “ + name + “.”;

Save the file. It is now time to add the EJB to its container, generate the support files, run the app server and deploy the EJB.

Right click on MyEJBBean.java and from the bottom of the popup menu select Lomboz J2EE…->Add EJB to Container…. When the Please select a container dialog appears select EJB[ejb] and press OK. If you press OK without selecting EJB[ejb] nothing will happen. In order to guarantee that the EJB was added to the container it is time to use the Lomboz J2EE View.

Select the Lomboz J2EE View from the selection of tabs located at the bottom of the workbench. In the Containers list there should be a folder labeled EJBExample. Open the folder. Inside of the folder should be a node labeled ejb. Opening the ejb node should reveal two entries: A JBOSS server… and our EJB, ejb.session.MyEJBBean (Fig. 2). If MyEJBBean does not appear in the view press the refresh button (the button with the two circular arrows). Depending on your screen resolution you may have to scroll down to see the project, the container, the server and the EJB all at once.

Figure 2. The Lomboz J2EE View located at the bottom of the workbench.

Generate the various EJB classes and support files by right clicking on the ejb container in the Lomboz J2EE View and select Generate EJB Files. It is in this step that the concrete (i.e., non-abstract) implementation of MyEJB is created. The concrete class, generated under the ejbsrc directory, is called MyEJBSession. If you like you can open MyEJBSession and take a look at the collection of empty methods that make up the sub-class of MyEJBBean.

Before deploying MyEJB we need to start the app server. From the Lomboz J2EE View right click on the JBoss server (A JBOSS server…) and select Run Server or Debug Server (either will do for this tutorial). If JBoss successfully starts the Console window will come forward displaying the JBoss output as the app server initializes. JBoss has finished initializing when a message like this appears:

[Server] JBoss (MX MicroKernel) [3.0.3 Date:200209301503] Started in 0m:25s:787ms

One more step and we will be done with the server-side tasks of the tutorial. Return to the Lomboz J2EE View, right click on the ejb container and select Deploy. A Progress dialog appears with the message “Deploying container…”. When the dialog disappears the Console output window once again comes to the front printing additional JBoss status information. The EJB is successfully deployed with the appearance of the message (Fig. 3):

[MainDeployer] Deployed package: file:/C:/jboss-3.0.3_tomcat-4.1.12/server/default/deploy/ejb.jar

Figure 3. JBoss startup output after MyEJB has been deployed.

Our EJB is deployed and waiting to talk to a client.

Creating and running an EJB Test Client

Let’s create a plain vanilla Java project and add a test client to the project using the Lomboz J2EE Test Client Wizard.

From the main menu select File->New->Java Project. When the New dialog appears enter the Project name as EJBExampleClient and press Next. As we are going to be making reference to the EJB interface MyEJB we have to make sure our J2EE project, EJBExample, is visible to our client project. Go to the Projects tab and select the checkbox next to EJBExample. Press Finish.

Make sure EJBExampleClient is still selected in the Package Explorer (if it is not, then select it). From the main menu select File->New->Lomboz EJB Test Client Wizard (Fig. 4). When the dialog appears enter the following information:

Package: ejb.client

Name: EJBClient

EjbHome: ejb.session.MyEJBHome

Ejb Interface: ejb.session.MyEJB.

Target Server: JBOSS

Version: 3.0.x

Press Finish.

Figure 4. The EJB Test Client Wizard.

Open the EJBExampleClient->src folder and double-click on EJBClient.java to display the file in the editor. Go to testBean() and change the following line from

//System.out.println(myBean.callYourMethod());

System.out.println(myBean.sayHelloTo(“Kitty”));

Save the EJBClient.java file. Eclipse performs incremental compilation every time a file is saved so our client is now ready to go.

From the main menu select Run->Run As->1 Java Application. The Console window in Figure 5 should display the message “Hello, Kitty.”.

Figure 5. The final output of the tutorial.

Conclusion

Every step we took in this tutorial was mechanical. There was very little room for creativity as the creation of an EJB is not where you want to spend your time, but rather in its implementation logic. The Lomboz plugin (with the help of XDoclet) does an excellent job in automating the steps needed to get an EJB up and running quickly.

Resources

Download the Lomboz plugin as well as documentation:

http://www.objectlearn.com

The code-generation engine used in Lomboz is XDoclet. Read more about this technology at:

http://xdoclet.sourceforge.net

About the Author

Carlos Valcarcel is the Chief Architect at EinTech, Inc. and has been involved in Java and distributed systems since 1996. He has done numerous presentations at domestic and international conventions. In addition to his work as an architect, developer and mentor, he has also presented Java courses for various companies including Sun and IBM. He can be reached at carlos@eintech.com.

Company and product names mentioned in The One-Page Tutorials and The One-Page Tutorials are trademarks or registered trademarks of their respective companies.

[1] If you happen to press FINISH delete the project from the Package Explorer and start again. There are a number of ways to add the missing information, but for the purposes of this tutorial just delete the project and start again.