first ejb dev

In this section we will walk through a simple ejb development scenario in Lomboz.

Lomboz makes extensive use of XDoclet  http://xdoclet.sourceforge.net for EJB development.  Lomboz will help you in creating, developing, deploying and running xdoclet “enabled” EJBs by easy to use tools.

The following excerpt is taken directly from the xdoclet documentation:

“XDoclet is an extended Javadoc Doclet engine. It's a generic Java tool that lets you create custom Javadoc @tags and based on those @tags generate source code or other files (such as xml-ish deployment descriptors) using a template engine it provides. XDoclet supports a set of common standard tasks such as web.xml or ejb-jar.xml generation, users and contributors can create other templates and @tags and add support for other technologies also.

The broader goal is to let you apply "Continuous Integration" in component-oriented development. The point is that you program your component and specify its meta-data in a per component fashion, you set the deployment meta-data per component. You don't have to worry about outdating deployment meta-data whenever you touch the code. The deployment meta-data is continuously integrated. And the whole process is, in its nature, round-trip. We call it "Continuous Reconfiguration". XDoclet is meant to be used as part of the build process utilizing Apache-Ant.

The system is extensible. If desired, you can write a specific template for your specific task (supporting a new application server, defining the OR schema for a tool like TopLink for example, or even supporting Servlets as components!). Some pre-built @tags and templates are already supported by XDoclet, for example <ejbdoclet/> for EJB-related stuff, <webdoclet/> for web.xml deployment descriptor generation and so on.

XDoclet is based on these parts:

• The Apache Ant task: <ejbdoclet/> and <webdoclet/> are examples of such tasks. In your build.xml file, define it before the target that compiles the code.

• The nested elements to the task element: This is where you specify exactly which sub-tasks are performed over your source codes. Examples are <remoteinterface/> and <jsptaglib/>. Each sub-task is separately configurable.

• The template files: Sub-tasks generate output based on template files. Template may be any text file with some XML-ish <XDoclet.blabla/> elements in it. Templates are like JSP files, <XDoclet.XYZ/> are like JSP tags, the actual implementation is in sub-task classes and a base class where the common tags are defined.

• The special JavaDoc @tags: using some special JavaDoc @tags, settings are defined for each component. For example putting a @ejb.bean name="TestSession" jndi-name="jndi/TestSessionBean" type="Stateless" in TestSessionBean.java lets the <deploymentdescriptor/> sub-task know that TestSessionBean.java contains a stateless session bean definition, so it can generate the corresponding interfaces, home class, context, and ejb-jar.xml deployment descriptor based on the information provided by @ejb.bean tag.

• The merge system: To avoid lots of silly tags, XDoclet also lets you utilize a merge system. For example instead of putting @jboss.table-name account in your EJBean source code, you can define a jaws-db-settings-Account.xml file where the content is the actual XML that <jboss/> sub-task will merge into the generated jaws.xml file.

For concrete xdoclet examples, please refer to the sample codes and sample build.xml file.

XDoclet is the successor to EJBDoclet, a project that Rickard Öberg, one of the best programmers of the world and an Open Source pioneer, started. Then, during its development, EJBDoclet reached the stage that it was no longer only for EJBs. So a new project was created with a broader goal in mind.

You can download it from http://sourceforge.net/projects/xdoclet.”

Lets try this by following the example below.

1.	In the main workbench window, select the drop-down menu from the Open New Wizard button and select Project.
2.	On the left, select Java, and on the right, select Lomboz J2EE Project. Then click Next. In the Project name field, type "MyFirstEJBProject", then click Next. The Java Setting page will appear. Make sure that source tab indicates that ‘src’ folder is being used as the project source folder and the build output folder is ‘bin’. Click Next, and this will take you to the modules tab.
3.	Click on EJB-Modules tab

4.	Click on the ‘Add…’ button to add a new ejb module, type ‘mybeans’ for the name of the EJB module. You may want to choose a different root folder than the project folder for your module. To do this click on the Choose... button for the base folder. All related directories and files will created under the base folder.
5.	Click on Targeted Servers tab

6.

Here you will find the list of server definitions, which you have configure earlier using the Lomboz preferences. Each module can be targeted for a number of servers. You can select the server definition that you would like to target this module and click add. You can add as many definitions as you like. However, you must identify one of these targets as the default one. If you enable the update classpth and deployment properties button, lomboz will update the relevant project properties accordingly for the default target. You can change the default target, or add/remove targets later using the Package Explorer "Change default server" popup menu for the module.

7.

Click Finish. Notice that the Java perspective opens with the new J2EE  project in the Packages view.

8.

In the Packages view, expand the ‘MyFirstEJBProject’ project and notice the ‘mybeans’ folder in the ‘MyFirstEJBProject’. There will be six xml files in the META-INF folder. You will notice that contents of ejb-jar.xml is empty. Other xml files are to be used by Lomboz. build.xml and ejbGenerate.xml are the ant scripts file used by Lomboz for all build and deployment tasks.  targets.xml contains launching parameters for the application server. beans.xml contains a list of beans to be included in this jar (initially empty). ejbs.xml is used by the ant scripts and contains the locations of the beans to be included in this jar (auto-generated later, and initially empty).

9.	Now we are ready to create our first EJB.  To do this select your project in the packages view by highlighting it then get th popup menu using the right mouse button.   Select New->Lomboz EJB Creation Wizard

10.	Enter the following in the EJB Wizard:  For the new package name, enter com.testing.session, for the class name TestSession, and for the EJB type select stateless session EJB.  Please note that whatever name you enter for the class, Lomboz will add “Bean” at the end.  The resulting class will be called TestSessionBean. Click finish when you are done.
11.	In the Packages view, expand the ‘com.testing.session’ package and notice the ‘TestSessionBean.java’ class.  Double click on the file to open it.

12.

A typical EJB created by Lomboz will look like the TestSessionBean.java: package com.testing.session; import javax.ejb.SessionBean; /**  * @ejb.bean name="TestSession"  *    jndi-name="TestSessionBean"  *    type="Stateless" **/ public abstract class TestSessionBean implements SessionBean { } We will add business method to our EJB soon. Please note the Javadoc comments including xdoclet tags. An XDoclet tag is comprised of the following parts: @namespace.tag-name parameter-name="parameter value" Tags are grouped by namespaces, and have names that are unique within that namespace. Tags can have zero or more parameters, which are grouped in name="value" pairs. Looking at the above example, we find the first tag is in the ejb namespace, and is called bean. The ejb:bean tag defines data relating to Enterprise Java Beans. Every EJB will require a name, and it is specified here. The namespace is a mechanism for making sure no name collision happens. Namespaces include ejb,  jboss, weblogic and so on. So it's simply a way to group related tags. For details on individual tags, consult the xdoclet documentation.

13.

Now select our newly created TestSessionBean class in the Packages view, and use the right mouse button popup menu to access the J2EE->Add Ejb Method menu. When the wizard is opened, enter the public String helloWorld() as the method signature in the wizard and identify the type  to be a Business method, also state that you would like this method to be a part of the remote interface (meaning this method can be invoked by distributed clients).   Click finish.

14.	In the Packages view, expand the ‘com.testing.session’ package and notice the ‘TestSessionBean.java’ class.  Double click on the file to open it. Browse the method and change it  as follows: /**  * @ejb.interface-method  *    tview-type="remote" **/ public String helloWorld(){  return "Hello from lomboz!"; }
15.	Now we have enough to run a simple test with this EJB.  However, we must prepare for deployment.  In order to deploy this EJB we still need the following: a)     Package it inside a Jar file. b)     Generate the necessary interface, home and utility classes. c)      Deploy it to an application server. d)     Write a test and run the test to see the results.
16.	To package the TestSessionBean into our mybeans EJB module (which we have created earlier), we will need to add it to mybeans.  We can do this by selecting the our EJB in the packages view, and after opening the right mouse button popup menu, select J2EE->Add Ejb to Modules item. In the list, select mybeans and click OK.

17.

Now lets verify the results of this action.  Open the J2EE View and refresh the projects.  If you open the mybeans EJB module, you will see TestSessionBean listed as a session bean. Also, if you open the file mybeans/meta-inf/beans.xml you will find out that it has the following beans: <?xml version="1.0" encoding="UTF-8"?> <beangroup>   <bean>     <beanClass>com.testing.session.TestSessionBean</beanClass>     <type>Session</type></bean></beangroup>

18.

It is time to generate all the necessary EJB classes and deployment XML files for mybeans container.  To generate the necessary EJB classes and xmls, select the container named mybeans in the J2EE view, and run the “Generate EJB files” command from the right mouse button menu. WARNING:  THIS STAGE DEPENDS ON THE CORRECT EXECUTION OF THE XDOCLET TASKS.  MAKE SURE THAT YOU HAVE FOLLOWED THE XDOCLET INSTALLATION INSTRUCTIONS FOR LOMBOZ. Alternatively, you can accomplish the same result by using the right mouse button popup menu of the Packgases view.  Select the folder named myBeans in the packages view and run the command “Generate EJB files”.

19.	To separate the Java classes generated by xdoclet  from the rest of your Java classes, these will be located in a special java source folder named ‘ejbsrc.  As the EJB  files are processed in their natural course,you will use xdoclet to generate the corresponding Java classes and deposit them under this directory. In the Packages view, expand the ‘ejbsrc’ folder and notice the all the ‘TestSession’ related classes.
20.	Now we are ready to test our application.  First we will launch the server. Open the J2EE View if it is not already open.  Click on the ‘MyFirstEJBProject’ to expand it. Click on the ‘mybeans’ module to expand it.  You will see our server listed as ‘A server…’. Highlight the ‘A server…’ to select it. Use the pop-up context menu and select ‘Debug Server’.
21.	Now its time to deploy the EJB  to the server that we have just launched.  To do this switch to the Java perspective and open the J2EE View if it is not already open.  Expand the ‘MyFirstEJBProject’.  Select ‘myBeans from the list.  Using the pop-up menu, select ‘deploy’ menu item.  You will observe the progress in Eclipse.  Also notice the activity in the console window If everything goes smoothly, you may see messages similar to the following: <Jul 17, 2002 1:35:37 PM EEST> <Info> <EJB> <EJB Deployed EJB with JNDI name jndi/TestSessionBean.> <Jul 17, 2002 1:35:37 PM EEST> <Info> <J2EE> <Deployed : myBeans>
22.	Now let’s create a new project for our Test Clients.  It is a good idea to create a new project for your test client classes due to different classpath requirements of client applications.  If you use your server-side project for the Test client, it is likely that you will run into problems (especially if the client is a Java Application not a servlet). Let’s create an all new Java Project from scratch.  Name this project ‘MyEjbClientProject’. Open the new project wizard and enter the project name and click Finish. You will end up with a project as follows:
23.	Now we will add the Server Project to the classpath of the client project.  This will make sure that EJB classes are available to us for testing immediately. To do this highlight the client project in the Packages view and using the right mouse button menu, select the ‘Properties’ command.:
24.	In the properties window, select the Java Build Path and make sure that ‘MyFirstEjbProject’ is checked.

25.

Now we are ready to create our test client.  Make sure that the ‘MyEJBClientProject’ is highlighted and using the New items menu select the Lomboz EJB Test Client Wizard. For the new package name, enter com.testing.client, for the class name TestClient, and for the EJB interfaces enter the TestSessionHome and TestSession types. You must also select the target server type and version.  This will allow the wizard to add necessary client jar files to the project classpath. Click finish when you are done.

26.

In the Packages view, expand the ‘com.testing.client’ package and notice the ‘TestClient.java’ class.  Double click on the file to open it.

27.

Go the testBean method and modify the code like the following:       public void testBean() {             try {                   com.testing.session.TestSession                         myBean = getHome().create();                   //--------------------------------------                   //This is the place you make your calls.                   System.out.println(myBean.helloWorld());             } catch (RemoteException e) {                   e.printStackTrace();             } catch (CreateException e) {                   e.printStackTrace();             } catch (NamingException e) {                   e.printStackTrace();             }       }

28.	Run the test:  Select the class TestClient from the packages view and run its as a “Java Application”.
29.	And if all goes well you will see the following console: