EasyBeans Developer's guide

EasyBeans code is using maven tool. In order to download Maven2 dependencies in Eclipse, the M2 Eclipse plugin can be used. This plugin is available at http://m2eclipse.sonatype.org/

The eclipse-checkstyle plugin is used to check the javadoc of Easybeans project. A warning will print if the EasyBeans coding convention is not used. This plugin is available at http://eclipse-cs.sourceforge.net.

As part of the EasyBeans coding convention, the use of tabulation characters is disallowed. Files should contain only spaces. The AnyEdit plugin allows tabs to be converted to spaces when saving the file. Also, trailing spaces can be removed automatically.

This plugin is available at http://andrei.gmxhome.de/anyedit/.

EasyBeans uses bytecode enhancement. This is done using the OW2 ASM project. ASM provides a plugin that allows the ASM code of a given class to be obtained. The plugin is available at http://asm.objectweb.org/eclipse/index.html.

The EasyBeans test suite uses TestNG. A plugin is available for Eclipse: http://testng.org/doc/eclipse.html.

EasyBeans can be launched within Jetty web container. The assemblies for Jetty are available in the assemblies/distrib/jetty/target folder.

EasyBeans can be launched within JOnAS 4 J2EE application server. The assemblies for JOnAS are available in the assemblies/distrib/jonas/target folder.

	Note
	EasyBeans is already included by default in JOnAS 5.0

EasyBeans can be launched within Apache Tomcat web container. The assemblies for Jetty are available in the assemblies/distrib/tomcat/target folder.

EasyBeans can be launched without any container. This is done by using the uberjar file. EasyBeans is launched by using java -jar easybeans-uberjar-xxx.jar command.

The war module is then used for Apache Tomcat or Jetty web container.

This module is used for JOnAS 4 J2EE Application server.

This example is a stateless session bean. It contains a helloWorld() method that displays text on the server side. Additionally, it demonstrates the use of EJB3 annotation, such as @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, must follow this signature:

	Note
	As a new feature of EJB3, the bean's interface does not need to extend the Remote interface.

If the server is not available, it must be run by following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The stateless session bean must be deployed. If the bean has been installed in the easybeans-deploy folder, this is done automatically.

On the server side, the following output should display:

     [java] 5/16/07 10:59:32 AM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/stateless.jar]
     [java] 5/16/07 10:59:32 AM (I) JContainer3.start : Container started in : 408 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once the container has been started, the client can be launched.

Run the client 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 the PortableRemoteObject.narrow() call is no longer required.

This is an example of a stateful session bean using the SessionSynchronization interface.

It uses the @Stateful annotation and uses the default transaction model, which is REQUIRED.

If the server is not available, it must be run by following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The stateful session bean must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should be seen:

     [java] 5/16/07 10:59:37 AM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/stateful.jar]
     [java] 5/16/07 10:59:37 AM (I) JContainer3.start : Container started in : 94 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once the container has been started, the client can be launched.

Run the client 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.

This is an example of an entity bean. It describes how to use the new Java Persistence Model of an EJB3 persistence provider. To access EJB3 entities that 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 is managed by the persistence provider.

Currently, the persistence provider is supplied by the Hibernate product, but the ObjectWeb Speedo product should be available soon. Users will have the choice between providers.

This example uses the @Stateful annotation and uses the default transaction model, which is REQUIRED.

The example shows an entity bean using EJB3 Hibernate-prototype persistence provider.

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The entity bean must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should be seen:

     [java] 5/16/07 10:59:36 AM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/entitybean.jar]
     [java] 5/16/07 10:59:36 AM (I) JPersistenceUnitInfoHelper.getPersistenceUnitInfo : No persistence provider was set, set to value org.hibernate.ejb.HibernatePersistence.
     [java] 5/16/07 10:59:36 AM (I) JPersistenceUnitInfoHelper.getPersistenceUnitInfo : Found a default configuration for the persistence provider org.hibernate.ejb.HibernatePersistence
     [java] 5/16/07 10:59:36 AM (I) JPersistenceUnitInfoHelper.getPersistenceUnitInfo : Setting the property hibernate.transaction.manager_lookup_class with value org.hibernate.transaction.JOTMTransactionManagerLookup
     [java] 5/16/07 10:59:36 AM (I) JPersistenceUnitInfoHelper.getPersistenceUnitInfo : Setting the property hibernate.cache.provider_class with value org.hibernate.cache.HashtableCacheProvider
     [java] 5/16/07 10:59:36 AM (I) Ejb3Configuration.configure : Processing PersistenceUnitInfo [
     [java] name: entity
     [java] ...]
     [java] 5/16/07 10:59:36 AM (I) Ejb3Configuration.scanForClasses : found EJB3 Entity bean: org.objectweb.easybeans.examples.entitybean.Employee
     [java] 5/16/07 10:59:36 AM (I) Ejb3Configuration.scanForClasses : found EJB3 Entity bean: org.objectweb.easybeans.examples.entitybean.Employee
  ...
     [java] 5/16/07 10:59:36 AM (I) JContainer3.start : Container started in : 412 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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] Employee with id 1 = Florent
     [java] Employee with id 2 = Whale

These properties are defined in the META-INF/persistence.xml file.

      <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect" />
      <property name="toplink.target-database" value="HSQL"/>
      <property name="openjpa.jdbc.DBDictionary" value="hsql"/>

      <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      <property name="toplink.ddl-generation" value="drop-and-create-tables"/>
      <property name="toplink.ddl-generation.output-mode" value="database"/>
      <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>

This is an example of a message driven bean. It describes how to use a JMS message driven bean.

The class is a class annotated with @MessageDriven. Then, it is mapped to a JMS queue through the properties of this annotation.

@MessageDriven(activationConfig = {
        @ActivationConfigProperty(propertyName = "destination", propertyValue = "SampleQueue"),
        @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue")
        }
)

The Message Driven Bean will receive message from the SampleQueue queue.

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The entity bean must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should be seen:

5/16/07 2:42:24 PM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/mdb.jar]
5/16/07 2:42:24 PM (I) JContainer3.start : Container started in : 267 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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:

run.client:
     [java] May 16, 2007 3:39:08 PM org.objectweb.carol.util.configuration.ConfigurationRepository init
     [java] INFO: No protocols were defined for property 'carol.protocols', trying with default protocol = 'jrmp'.
     [java] May 16, 2007 3:39:08 PM org.objectweb.util.monolog.wrapper.javaLog.Logger log
     [java] INFO: Debug.initialize() - a3debug.cfg
     [java] May 16, 2007 3:39:09 PM org.objectweb.util.monolog.wrapper.javaLog.Logger log
     [java] INFO: ReliableTcpConnection.windowSize=100
     [java] Message [ID:0.0.1026c2m1, text:Message_0] sent
     [java] Message [ID:0.0.1026c2m2, text:Message_1] sent
     [java] Message [ID:0.0.1026c2m3, text:Message_2] sent
     [java] Message [ID:0.0.1026c2m4, text:Message_3] sent
     [java] Message [ID:0.0.1026c2m5, text:Message_4] sent

And on the server side, the messages have been received:

Receiving a message named '((org.objectweb.joram.client.jms.TextMessage@4391f0,messageID=ID:0.0.1026c2m1,destination=queue#0.0.1027,correlationId=null,deliveryMode=2,expiration=0,priority=4,redelivered=false,replyTo=null,timestamp=1179322749177,type=null),text=Message_0,RObody=true)'. with the content 'Message_0
Receiving a message named '((org.objectweb.joram.client.jms.TextMessage@13e9934,messageID=ID:0.0.1026c2m4,destination=queue#0.0.1027,correlationId=null,deliveryMode=2,expiration=0,priority=4,redelivered=false,replyTo=null,timestamp=1179322749216,type=null),text=Message_3,RObody=true)'. with the content 'Message_3
Receiving a message named '((org.objectweb.joram.client.jms.TextMessage@1e064c,messageID=ID:0.0.1026c2m5,destination=queue#0.0.1027,correlationId=null,deliveryMode=2,expiration=0,priority=4,redelivered=false,replyTo=null,timestamp=1179322749261,type=null),text=Message_4,RObody=true)'. with the content 'Message_4
Receiving a message named '((org.objectweb.joram.client.jms.TextMessage@95ef17,messageID=ID:0.0.1026c2m2,destination=queue#0.0.1027,correlationId=null,deliveryMode=2,expiration=0,priority=4,redelivered=false,replyTo=null,timestamp=1179322749209,type=null),text=Message_1,RObody=true)'. with the content 'Message_1
Receiving a message named '((org.objectweb.joram.client.jms.TextMessage@17c4779,messageID=ID:0.0.1026c2m3,destination=queue#0.0.1027,correlationId=null,deliveryMode=2,expiration=0,priority=4,redelivered=false,replyTo=null,timestamp=1179322749212,type=null),text=Message_2,RObody=true)'. with the content 'Message_2

This example shows the use of the @Timeout annotation on a method. The client invokes the TimerBean that will launch a timer. This timer will send a message to an MDB and then calls another bean which implements javax.ejb.TimedObject interface.

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The timer bean example must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should display:

     [java] 9/29/07 3:52:50 PM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/timer.jar]
     [java] 9/29/07 3:52:50 PM (I) JContainer3.start : Container started in : 104 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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 on the client side:

run.client:
     [java] Sep 29, 2007 4:16:45 PM org.objectweb.carol.util.configuration.ConfigurationRepository init
     [java] INFO: No protocols were defined for property 'carol.protocols', trying with default protocol = 'jrmp'.
     [java] Calling init method that will fire a new timer...

The following output is displayed on the server side:

     [java]  SLSB -> Timer method called by the Timer Service.
     [java]  SLSB -> Timer received = 'org.ow2.easybeans.component.quartz.EasyBeansTimer@6e7d3050'.
     [java]  SLSB -> Info object inside the timer object is 'Simple Serializable object'.
     [java]  SLSB -> Sending a message to a MDB which will start a timer.
     [java]  SLSB -> Message sent
     [java]  SLSB -> Call a local bean in order to start a new timer.
     [java]   MDB -> Timer method called by the Timer Service.
     [java]   MDB -> Timer received = 'org.ow2.easybeans.component.quartz.EasyBeansTimer@59d794d'.
     [java]   MDB -> Info object inside the timer object is 'Timer started by the onMessage() method'.
     [java]  TimedBean -> Got a timer with value 'org.ow2.easybeans.component.quartz.EasyBeansTimer@2dd5b883'.

This example illustrates the use of different Java EE 5 annotations which are linked to the security part.

The annotations used by the example are:

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The security bean example must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should display:

     [java] 5/16/07 10:59:37 AM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/security.jar]
     [java] 5/16/07 10:59:37 AM (I) JContainer3.start : Container started in : 115 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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 on the client side:

     run.client:
     [java] Oct 16, 2006 5:27:03 PM org.objectweb.carol.util.configuration.ConfigurationRepository init
     [java] INFO: No protocols were defined for property 'carol.protocols', trying with default protocol = 'jrmp'.
     [java] Calling methods that everybody can call...
     [java] Call a bean with run-as in order to have 'admin' role...
     [java] Access denied as expected (method is denied)

The following output is displayed on the server side:

     [java] someRolesAllowed() called
     [java] -> Caller is 'Principal[EasyBeans/Anonymous]'.
     [java] for run-as bean, caller is Caller is 'Principal[EasyBeans/Anonymous]
     [java] onlyAdminAllowed() called
     [java] -> Caller is 'Principal[admin]'.
     [java] someRolesAllowed() called
     [java] -> Caller is 'Principal[admin]'.

This example illustrates the definition of some values to limit the size of a pool. In the example, the pool size can be configured through the specific XML deployment descriptor or with annotations.

The example contains two kind of beans, Stateless beans and Message Driven beans.

The annotation used in the example is:

By using annotation to configure the pool, the @Pool annotation needs to be put on the class of the bean. For example : @Pool(max = MyInterface.MAX_INSTANCE)

By using XML configuration, the settings are located in the META-INF/easybeans.xml entry of the EJB-JAR file.

   ...
      <!-- Configure pool element with pool namespace -->
      <pool:pool>
        <!-- Sets the max value to 2 -->
        <pool:max>2</pool:max>
      </pool:pool>
  ...  

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The pool bean example must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should display:

3/7/08 5:26:26 PM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/pool.jar]
3/7/08 5:26:28 PM (I) JContainer3.start : Container 'easybeans-deploy/pool.jar' [2 SLSB, 0 SFSB, 2 MDB] started in 1,388 ms

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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 on the client side:

run.client:
     [java] Mar 7, 2008 5:31:35 PM org.objectweb.carol.util.configuration.ConfigurationRepository init
     [java] Calling bean's methods...
     [java] Waiting some time before checking the number of instances...
     [java] Number of instances Annotation Bean = 5
     [java]   --> This value is OK, pool is limited to 5
     [java] Number of instances XML Bean = 2
     [java]   --> This value is OK, pool is limited to 2
     [java] 3/7/08 5:31:41 PM (I) Logger.log : Debug.initialize() - a3debug.cfg
     [java] 3/7/08 5:31:42 PM (I) Logger.log : ReliableTcpConnection.windowSize=100
     [java] Sending messages with multiple threads...
     [java] Waiting some time to ensure that all messages have been sent...
     [java] Look at the server side console to check pool values of MDB ...

The following output is displayed on the server side:

     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.
     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.
     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.
     [java] MDBXMLBean:Number of instances = '2', max = '2'.
     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.
     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.
     [java] MDBXMLBean:Number of instances = '2', max = '2'.
     [java] MDBAnnotationBean: Number of instances = '5', max = '5'.

...

The instances are not exceeding the limits fixed in the example then everything is working fine.

This example illustrates the use of annotations that provide Home and Remote interface for clients written for the EJB 2.1 specification.

The annotations used by the example are:

An EJB that is using these annotations can be used by an EJB3 client and a EJB 2.1 client. These annotations can be used to do a migration of your beans on the server side while the clients are the same.

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The migration bean example must be deployed. It is done automatically if the bean has been installed in the easybeans-deploy folder.

On the server side, the following output should display:

5/16/07 2:42:24 PM (I) AbsDeployer.deployEJB : Deploying EJB3DeployableImpl[archive=easybeans-deploy/migration21.jar]
5/16/07 2:42:25 PM (I) JContainer3.start : Container started in : 166 ms 

Once this information is displayed on the screen, the container is ready to receive client calls.

Once 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 on the client side:

run.client:
     [java] May 16, 2007 2:43:18 PM org.objectweb.carol.util.configuration.ConfigurationRepository init
     [java] INFO: No protocols were defined for property 'carol.protocols', trying with default protocol = 'jrmp'.
     [java] Calling hello() method on EJB 3.0 view of the Bean...
     [java] Calling hello() method on Remote EJB 2.1 view of the Bean...

The following output is displayed on the server side:

Hello world EJB 3.0 !
Hello world EJB 2.1 Remote View !
Link to itself remote = org.objectweb.easybeans.examples.migrationejb21.EJB2And3Bean_org.objectweb.easybeans.examples.migrationejb21.EJB2RemoteHome/8414877
Link to itself local view = org.objectweb.easybeans.examples.migrationejb21.EJB2And3Bean_org.objectweb.easybeans.examples.migrationejb21.EJB2LocalHome/8414877
Calling itself on the local view...
Hello world EJB 2.1 Local View !

This example will deploy the EJB3 included in the EAR file in EasyBeans EJB3 container while the .war file will be deployed in the web container This EAR example includes an EJB3 and a WAR file. This allows to use local interface between the WEB layer and the EJB layer. The EAR file has no entry named META-INF/application.xml, EasyBeans will detect the type of the given archives and use default values for the name of the web context. Due to the use of local interface, the Entities don't need to implement the Serializable interface. The interface is not annotated with @Local annotation as it is the default value. Each entity class provides a @NamedQuery query that allows to get all the objects There is a relationship between Author and Book entities. It is very simple: One Author can write several books, but a Book is written only by one Author. @OneToMany and @ManyToOne annotations are used to define the relationship

If the server is not available, it must be run following the steps described in Chapter 3, "Running the EasyBeans Server" of the developer's guide.

The EAR application example must be deployed. It is done automatically if the EAR has been installed in the easybeans-deploy folder.

When the EAR is detected by EasyBeans, the following traces will be displayed :

JOnASDeployer.deployEAR : Deploying EARDeployableImpl[archive=/tmp/EasyBeans-Deployer-benoitf/EAR/ear3.ear]
ENCManager.getInterceptorClass : Detecting JOnAS: using JOnAS ENC for the naming.
JPersistenceUnitInfoHelper.loadDefaultValues : Default persistence provider set to value org.hibernate.ejb.HibernatePersistence.
...
Version.<clinit> : Hibernate Annotations 3.3.0.GA
Environment.<clinit> : Hibernate 3.2.4
...
JContainer3.start : Container started in : 5619 ms
AbsJWebContainerServiceImpl.registerWar : War /tmp/EasyBeans-Deployer-benoitf/EAR/ear3.ear/ear-web.war available at the context /ear-web.
JOnASDeployer.deployEAR : 'EARDeployableImpl[archive=/tmp/EasyBeans-Deployer-benoitf/EAR/ear3.ear]' EAR Deployable is now deployed

Once this information is displayed on the screen, the application can be used by using an HTTP browser.

Once the container has been started, the client can be accessed.

The URL used to connect to the client is the following: http://localhost:9000/ear-web for JOnAS.

The following text should be displayed on the browser:

Initialize authors and their books...

Get authors

List of books with author 'Honore de Balzac' :

    * Title 'Le Pere Goriot'.
    * Title 'Les Chouans'.

List of books with author 'Victor Hugo' :

    * Title 'Les Miserables'.
    * Title 'Notre-Dame de Paris'.

There is no output on the server side.

Declarations are static final, not final static. This is a JLS recommendation.

Constants should be static and final, and should adhere to the following:

'^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'

Constants must be used in the code and magic number must be avoided. For example, the following 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;

The attribute name should not have an underscore ( _ ). The _ is valid for constants that are in uppercase.

Use pValue and mValue instead of p_Value and m_Value.

The pattern for attribute name is:

'^[a-z][a-zA-Z0-9]*$'