Copyright © 2006 ObjectWeb Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
$Id: developerguide.xml 216 2006-03-16 19:01:07Z benoitf $
Abstract
The EasyBeans developer guide is intended for developers wanting to work with the source distribution of EasyBeans. People wanted to contribute to EasyBeans should read this documentation.
Table of Contents
Table of Contents
A JDK 5.0 is required to build EasyBeans. So check that the JDK used to build EasyBeans is compliant with new 5.0 features
To build EasyBeans, the ant tool is used with
build.xml
files. This tool is available at http://ant.apache.org
The test suite of EasyBeans uses TestNG tool. This tool is available at http://www.testng.org
The test suite of EasyBeans uses Clover that is a code coverage analysis tool. Cenqua has granted licenses to open source projects. More about Clover at http://www.cenqua.com/
EasyBeans project provides .project and .classpath for Eclipse 3.1 or greater. You can import the sources in Eclipse tool and the project will be ready to go. Eclipse tool is available at http://www.eclipse.org
The eclipse-checkstyle plugin is used to check the javadoc of Easybeans project. It prints warning if the EasyBeans coding convention is not used. This plugin is available at http://eclipse-cs.sourceforge.net
As part of the EasyBeans coding convetion, the use of tabulations characters is disallowed. Files should contain only spaces. The AnyEdit plugin allows to convert tabs into spaces when saving the file. Also, trailing spaces could be removed automatically.
This plugin is available at http://andrei.gmxhome.de/anyedit/
EasyBeans uses bytecode enhancement. This is done by using the ObjectWeb ASM project.ASM provides a plugin allowing to get the ASM code of a given class. The plugin is available at http://asm.objectweb.org/eclipse/index.html
The test suite of EasyBeans is using TestNG. There is a plugin available for Eclipse : http://testng.org/doc/eclipse.html
In the root of the project (named easybeans by default), the command ant compile needs to be launched.
![]() | Note |
---|---|
The command ant -p could be used to list the targets that are available. |
Once the command has been run successfully, an output
folder is created with a subfolder
classes
. This last folder contains
the generated classes.
ant clean is used to clean the generated classes.
Javadoc of EasyBeans can be generated by using ant javadoc
The resulting documentation will be available in the output/dist/javadoc
folder.
By using ant jar, binaries jar files are built.
The generated jar files are located in the output/dist
folder.
By using ant rar, rar files will be generated (one for JOnAS application server).
The rar file is located in the output/dist
folder.
Anyone can checkout source code from the SVN server. To do this, the following command should be used (For GUI SVN client use, configure it appropriately):
svn checkout svn://svn.forge.objectweb.org/svnroot/easybeans easybeans
Table of Contents
The build.xml
file at which is at the root of
the project will be used. This file is found in the source
distribution.
The following command needs to be used : ant run.server
Then, EasyBeans server will be launched and the following output will be printed :
Buildfile: /home/benoitf/workspace/easybeans/build.xml init: [mkdir] Created dir: /home/benoitf/workspace/easybeans/output [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/manifest [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/dist [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/classes [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/dist/javadoc compile: [javac] Compiling 246 source files to /home/benoitf/workspace/easybeans/output/classes [copy] Copying 9 files to /home/benoitf/workspace/easybeans/output/classes run.server: [java] Mar 14, 2006 4:53:47 PM org.objectweb.easybeans.log.CommonsLoggerImpl warn [java] WARNING: No directory was configured, take the default value of /home/benoitf/workspace/easybeans/ejb3s. [java] Mar 14, 2006 4:53:47 PM org.objectweb.easybeans.log.CommonsLoggerImpl warn [java] WARNING: Directory /home/benoitf/workspace/easybeans/ejb3s created. [java] Mar 14, 2006 4:53:47 PM org.objectweb.carol.util.configuration.TraceCarol infoCarol [java] INFO: Name service for jrmp is started on port 1099 [java] Mar 14, 2006 4:53:47 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: List of all MBeans descriptors [java] Mar 14, 2006 4:53:47 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: Found managedBean EJB3Deployer. [java] Mar 14, 2006 4:53:47 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: End of list of all MBeans descriptors [java] Mar 14, 2006 4:53:48 PM org.objectweb.jotm.Current <init> [java] INFO: JOTM 2.0.11 [java] Mar 14, 2006 4:53:48 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: Startup was done in '684' ms. [java] Mar 14, 2006 4:53:48 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: '0' containers have been created. [java] Mar 14, 2006 4:53:48 PM org.objectweb.easybeans.log.CommonsLoggerImpl info [java] INFO: Waiting requests...
Now, EasyBeans is launched and it is ready to handle EJBs.
Table of Contents
Before trying to run the examples, the requirements in order to compile and run EasyBeans have to be followed.
The ant tool is used to build the
examples. This time, the build.xml
file that is
used is located in the examples
directory.
The command ant
install_all_examples
needs to be launched in the
examples
directory :
Buildfile: /home/benoitf/workspace/easybeans/examples/build.xml install_all_examples: init: [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/dist/clients [mkdir] Created dir: /home/benoitf/workspace/easybeans/output/dist/ejbjars [mkdir] Created dir: /home/benoitf/workspace/easybeans/clients compile: [javac] Compiling 5 source files to /home/benoitf/workspace/easybeans/output/classes install.persistence: install: [copy] Copying 4 files to /home/benoitf/workspace/easybeans/ejb3s/stateless.jar [jar] Building jar: /home/benoitf/workspace/easybeans/clients/client-stateless.jar init: compile: [javac] Compiling 3 source files to /home/benoitf/workspace/easybeans/output/classes install.persistence: install: [copy] Copying 2 files to /home/benoitf/workspace/easybeans/ejb3s/stateful.jar [jar] Building jar: /home/benoitf/workspace/easybeans/clients/client-stateful.jar init: compile: [javac] Compiling 4 source files to /home/benoitf/workspace/easybeans/output/classes install.persistence: [mkdir] Created dir: /home/benoitf/workspace/easybeans/ejb3s/entitybean.jar/META-INF [copy] Copying 1 file to /home/benoitf/workspace/easybeans/ejb3s/entitybean.jar/META-INF install: [copy] Copying 4 files to /home/benoitf/workspace/easybeans/ejb3s/entitybean.jar [jar] Building jar: /home/benoitf/workspace/easybeans/clients/client-entitybean.jar BUILD SUCCESSFUL Total time: 4 secondsThe examples are copied under the
ejb3s/
folder of the project and are
available for the deployment.
![]() | Note |
---|---|
If EasyBeans server is running, it will detect these new applications and deploy them automatically. |
Each example has its own build.xml
file in
order to be independent from each other.
The build.xml
file to use is in examples/statelessbean
folder.
This example is a stateless session bean. It contains an
helloWorld()
method which displays a text on
the server side. Also, it demonstrates the use of EJB3 annotation like
@Stateless.
The trace()
method is annotated with
@AroundInvoke EJB3 annotation. This method
will be called at each call on a business method. The business methods
are defined in the interface implemented by the SessionBean
class.
The signature of the method annotated by @AroundInvoke when it is defined in the bean class, needs to follow this signature :
(private|protected|public) Object methodName(InvocationContext invocationContext)
throws Exception;
![]() | Note |
---|---|
As a new feature of the EJB3, the bean's interface doesn't need to extend anymore the Remote interface. |
If the server is not available, it needs to be run by following the steps described in this guide.
The stateless session bean needs to be deployed. It is done
automatically if the bean has been installed in ejb3s
folder.
On the server side, the following output should be seen :
[java] INFO: Creating container for archive /home/benoitf/workspace/easybeans/ejb3s/stateless.jar. [java] INFO: Analyze elapsed during : 95 ms [java] INFO: Binding bean XXX with interface XXX into registry with jndi name XXX [java] INFO: Enhancement elapsed during : 105 ms [java] INFO: Container started in : 274 ms
If these informations are on the screen, it means that the container is ready to receive client calls.
As the container has been started, the client can be launched.
The client is run with the following ant command : ant run.client
If the client runs successfully, the following output is displayed :
[java] Calling helloWorld method... [java] Add 1 + 2... [java] Sum = '3'.
![]() | Note |
---|---|
In the client's code, the use of PortableRemoteObject.narrow() call is not required anymore. |
The build.xml
file to use is in examples/statefulbean
folder.
This example is a stateful session bean using the
SessionSynchronization
interface.
It uses the @Stateful annotation and use the default transaction model which is REQUIRED.
If the server is not available, it needs to be run by following the steps described in this guide.
The stateful session bean needs to be deployed. It is done
automatically if the bean has been installed in ejb3s
folder.
On the server side, the following output should be seen :
[java] INFO: Creating container for archive /home/benoitf/workspace/easybeans/ejb3s/stateful.jar. [java] INFO: Analyze elapsed during : 89 ms [java] INFO: Enhancement elapsed during : 76 ms [java] INFO: Binding bean XXX with interface XXX into registry with jndi name XXX [java] INFO: Container started in : 251 ms
If these informations are on the screen, it means that the container is ready to receive client calls.
As the container has been started, the client can be launched.
The client is run with the following ant command : ant run.client
If the client runs successfully, the following output is displayed :
[java] Start a first transaction [java] First request on the new bean [java] Second request on the bean [java] Commit the transaction [java] Start a second transaction [java] Buy 50 amount. [java] Rollback the transaction [java] after rollback, value = 30 [java] Request outside any transaction [java] Check that value = 30 [java] ClientStateful OK. Exiting.
The build.xml
file to use is in examples/entitybean
folder.
This example is an entity bean.
It describes how to use the new Java Persistence Model of an EJB3 persistence provider. To access EJB3 entities which are POJO, a stateless session bean is used. It is a facade bean.
The Entity class is a POJO class annotated with @Entity. The entities class are managed by the persistence provider.
Currently the persistence provider is provided by the Hibernate product, but ObjectWeb Speedo product should be used sooner. Users will have the choice between providers.
It It uses the @Stateful annotation and use the default transaction model which is REQUIRED.
This example shows the use of an entity bean and using EJB3 persistence provider which is in this prototype Hibernate. In a next version, the ObjectWeb Speedo product will provide an EJB3 persistence provider, so users will have the choice between these providers.
If the server is not available, it needs to be run by following the steps described in this guide.
The entity bean needs to be deployed. It is done automatically
if the bean has been installed in ejb3s
folder.
On the server side, the following output should be seen :
[java] INFO: Creating container for archive /home/benoitf/workspace/easybeans/ejb3s/entitybean.jar. [java] INFO: Analyze elapsed during : 95 ms [java] INFO: Enhancement elapsed during : 102 ms [java] INFO: No persistence provider was set, set to value org.hibernate.ejb.HibernatePersistence. [java] INFO: Hibernate 3.1.1 [java] INFO: Using provided datasource [java] INFO: RDBMS: HSQL Database Engine, version: 1.8.0 [...] [java] INFO: Binding bean XXX with interface XXX into registry with jndi name XXX [java] INFO: Container started in : 2010 ms
If these informations are on the screen, it means that the container is ready to receive client calls.
Table of Contents
The contributions should follow the EasyBeans code convention. An good document to get started is Java code convention. Besides, there is others conventions that are listed in this document.
In addition, the EasyBeans uses tools to check the compliance: the checkstyle plugin and the eclipse checkstyle plugin. The configuration settings are available on EasyBeans SVN.
All files should have the header which contains the LGPL and the date.
If a file is modified, the modification year should be appended in the existing year. For example, if there was '1999' or '2004' put '1999-2006' or '2004-2006', respectively.
Also, the tag $Id: code_convention.xml 314 2006-04-04 09:39:43Z pinheirg $ should be added. There is a header example above:
/** * EasyBeans * Copyright (C) 2006 Bull S.A.S. * Contact: easybeans@objectweb.org * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA * * -------------------------------------------------------------------------- * $Id: code_convention.xml 314 2006-04-04 09:39:43Z pinheirg $ * -------------------------------------------------------------------------- */
The imports should reference a correct class name, instead of the wildcard imports. The wildcard imports is not authorized.
For example, if the classes List and ArrayList are used, the imports should not be like this:
import java.util.*;
But the imports should have each class as follow:
import java.util.List; import java.util.ArrayList;
The classes should not have a unused import.
![]() | Note |
---|---|
The Eclipse IDE provides facilities to do this job. There is the option Organize Imports (Shift+Ctrl+O) in the menu Source that inserts correctly the imports and removes the unused imports. However, this option does not work well with import static. |
The class and interface name should begin with an uppercase. Also, each class and interface has a @author tag in the comment. For example:
/** * This is an example that shows how is a class/interface declaration. * @author Gisele Pinheiro Souza * @author Eduardo Studzinski Estima de Castro */ public class ClassExample implements InterfaceExample{ }
The space is used instead of the tab character. The number of spaces for an indent is 4 spaces.
The wrapping lines follow the Java code convention in this part.
The trailing spaces should be removed. There is an eclipse plug in that removes the trailing spaces and converts the tab into spaces. The plug in is AnyEdit.
Use whitespaces in for() loop, while(), when concatenating strings. One space should be added before the operator and other after the operator. For example, the correct is:
for (int i = 0; i < arTest.length; i++) { String strResult = "The element " + i + " has the value " + arTest[i]; }
The follow code does not follow the convention:
for (int i = 0; i< arTest.length; i++) { String strResult = "The element "+ i+" has the value "+arTest[i]; }
All methods and attributes (including protected and private) must have a comment. In a method comment the parameters, the exceptions thrown and the method return should have a comment. For example:
/** * This is an example that is used in the EasyBeans Code Convention. */ private int intValue; /** * This is an example method to show how is a class comment. * @param a an example of parameter. * @param b other example of parameter. * @return the method result. * @throws Exception the exception thrown by the method. */ public int add(final int a, final int b) throws Exception { return a + b; }
The braces must be used in the if/else blocks, even if there is a single statement. To illustrate:
if (true) { doThis(); }
This is not allowed:
if (true) doThis();
The braces position should be the same as in the example before. The following format is incorrect:
if (true) { test1(); test2(); }
All exception required a statement, no silent catching like :
try { doThis(); } catch (Exception e) { // should not occur }
You can use a logger :
try { doThis(); } catch (Exception e) { logger.logDebug("Exception while doing .....", e); }
The inline conditionals are not allowed. The following code is incorrect:
b = isOk() ? true : false;
The correct way to write is:
if (isOk()) { b = true; } else { b = false; }
The declarations is static final and is not final static, this is a JLS recommendation.
The constants should be static and final, and should follow the pattern:
'^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
The constants must to be used avoiding magic numbers in the code. For example, it is not allowed:
private int myAttribute = 5;
The correct format is:
/** * Default value */ private static final int DEFAULT_VALUE = 5; /** * This attribute is initialized with the default value */ private int myAttribute = DEFAULT_VALUE;
Table of Contents
First, developers wanting to contribute on EasyBeans could share their thoughts on the easybeans mailing list.
In order to subscribe to the list, steps are described at the following url :http://www.objectweb.org/wws/info/easybeans
There are several ways to contribute to easybeans and then there a lot of ideas.
Here is a list of things than can be done :
Documentation : improving the existing documentation, creating new chapters, translating, etc.
Code : Some glue could be added so that EasyBeans could be integrated in other server.
Tests : New tests can be added to the current test suite.