EJB - Stateless Session Beans

EJB | Stateless Session Beans

Introduction
Définir un stateless bean
Annotations @Local, @Remote, @LocalBean
Annotations @PostConstruct, @PreDestroy
Exemple: Utilisation d'un stateless bean
Exemple: Accéder un stateless bean en utilisant DI (Dependency Injection)
Exemple: Accéder un stateless bean en utilisant JNDI

Introduction
Un stateless bean ("stateless session bean") est une classe Java que le container EJB instancie et rend accessible ses méthodes publiques.
Le stateless bean est accessible en utilisant l'injection automatique ou JNDI.

Le container peut créer plusieurs instances du stateless bean pour répondre aux multiples invocations des méthodes publiques de la classe.
Par conséquent, les variables d'instance de la classe ne doivent pas être utilisées pour conserver l'état du stateless bean entre différents appels du stateless bean.

Mais, il est possible d'utiliser les variables d'instance (qui peuvent être initialisées à l'instanciation du stateless bean ou lors de l'appel d'une méthode du stateless bean).
Typiquement, le but est pour une instance donnée le traitement sera fait une seule fois (par exemple, lire un fichier de configuration à l'instanciation du stateless bean et initialiser un tableau avec les données du fichier).
Définir un stateless bean
Pour définir une classe comme étant un stateless bean il faut, typiquement, annoter la classe avec l'annotation @Stateless.

Code source (JBoss) de l'annotation @Stateless:
package javax.ejb; /** * A stateless session bean must be annotated with the Stateless annotation or denoted in the deployment descriptor as a stateless session bean. * If other annotations are applied to the bean class or its members, the Stateless annotation must be used. * The bean class does not implement the javax.ejb.SessionBean interface. */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface Stateless { /** * The ejb-name of this bean. */ String name() default ""; /** * A product specific name (in JBoss the global JNDI name) that this session bean should be mapped to. * Application servers are not required to support any particular form or type of mapped name, nor the ability to use mapped names. * The mapped name is product-dependent and often installation-dependent. * No use of a mapped name is portable. */ String mappedName() default ""; String description() default ""; }
L'annotation @Stateless accepte 3 paramètres :
- String name()
  Le nom EJB du stateless bean.
  Ce nom sera utilisé pour référencer le stateless bean (avec DI ou JNDI).
  Par défaut, si aucune valeur n'est spécifiée pour ce paramètre, il sera initialisé par le nom de la classe du stateless bean (sans le nom du package).
  Typiquement, on s'en sert pour donner un nom plus explicite au stateless bean ou pour distinguer le stateless bean d'une autre Stateless qui a le même nom de la classe.
- String mappedName()
  Ce paramètre permet de mapper le stateless bean à un nom global définit dans le container EJB (assez souvent un nom JNDI).
- String description()
  Nom descriptif du stateless bean.
Exemple :
package com.mtitek.session.beans.stateless; import javax.ejb.Stateless; @Stateless public class MyFirstStatelessBean { public String foo() { return "foo() method ..."; } public String bar() { return "bar() method ..."; } }
Annotations @Local, @Remote, @LocalBean
@Local // (javax.ejb.Local) @Remote // (javax.ejb.Remote) @LocalBean // (javax.ejb.LocalBean)
Un stateless bean peut implémenter des interfaces métiers locales (@Local) ou distantes (@Remote).

Les méthodes d'une interface métier locale (@Local) sont accessibles à l'intérieur de la même JVM.
L'invocation de ces méthodes n'implique pas des appels RPC distants et ainsi les paramètres et les valeurs de retour des méthodes sont passés par référence.

Les méthodes d'une interface métier distante (@Remote) sont typiquement invoquées par un code s'exécutant par une autre JVM.
L'invocation de ces méthodes implique des appels RPC distants et ainsi les paramètres et les valeurs de retour des méthodes sont passés par valeur (sérialisation/désérialisation des paramètres et des valeurs de retour).

Le stateless bean qui définit l'annotation @LocalBean expose toutes ses méthodes publiques au code s'exécutant par la même JVM.

Notes : Un stateless bean qui ne définit pas les annotations @Local, @Remote, et @LocalBean et n'implémente pas des interfaces métiers (annotées par @Local ou @Remote) expose toutes ses méthodes publiques au code s'exécutant par la même JVM.
1. Annotation @Local
  L'annotation @Local permet d'indiquer l'interface locale qui implémente les méthodes métiers du stateless bean.
  Ces méthodes peuvent être invoquées localement (même JVM) par d'autres objets (le passage des paramètres et des valeurs de retour des méthodes est fait par référence).
  
  Code source (JBoss) de l'annotation @Local:
  package javax.ejb; /** * Bean class annotation that specifies local interfaces of the Session bean. */ @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface Local { Class[] value() default {}; }
  L'annotation @Local accepte 1 paramètre :
  - Class[] value()
    Indique les interfaces locales du stateless bean.
  L'annotation peut être utilisée avec des interfaces mais aussi avec des classes :
  - Si l'annotation @Local est utilisée avec une interface, alors l'interface est marquée comme une interface métier locale (aucun paramètre n'est requis dans ce cas pour l'annotation).
    @Local public interface MyInterfaceL11 { void foo(); }
    @Local public interface MyInterfaceL12 { void bar(); }
    @Stateless public class MyClassL1 implements MyInterfaceL11, MyInterfaceL12 { public void foo() {} public void bar() {} }
    Le stateless bean "MyClassL1" implémente deux interfaces métiers locales "MyInterfaceL11" et "MyInterfaceL12".
  - Si l'annotation @Local est utilisée directement avec le stateless bean, alors les interfaces spécifiées comme paramètres de l'annotation constituent les interfaces métiers locales.
    public interface MyInterfaceL21 { void foo(); }
    public interface MyInterfaceL22 { void bar(); }
    @Stateless @Local({ MyInterfaceL21.class, MyInterfaceL22.class }) public class MyClassL2 implements MyInterfaceL21, MyInterfaceL22 { public void foo() {} public void bar() {} }
    Le stateless bean "MyClassL2" définit les interfaces "MyInterfaceL21" et "MyInterfaceL22" comme étant des interfaces métiers locales (en utilisant l'annotation @Local).
2. Annotation @Remote
  L'annotation @Remote permet d'indiquer l'interface distante qui implémente les méthodes métiers du stateless bean.
  Ces méthodes peuvent être invoquées par des objets distants n'appartenant pas à la même JVM du stateless bean (le passage des paramètres et des valeurs de retour des méthodes est fait par valeur).
  
  Code source (JBoss) de l'annotation @Remote:
  package javax.ejb; /** * Bean class annotation that specifies remote interfaces of the Session bean. */ @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface Remote { Class[] value() default {}; }
  L'annotation @Remote accepte 1 paramètre :
  - Class[] value()
    Indique les interfaces distantes du stateless bean.
  L'annotation peut être utilisée avec des interfaces mais aussi avec des classes.
  - Si l'annotation @Remote est utilisée avec une interface, alors l'interface est marquée comme une interface métier distante (aucun paramètre n'est requis dans ce cas pour l'annotation).
    @Remote public interface MyInterfaceR11 { void foo(); }
    @Remote public interface MyInterfaceR12 { void bar(); }
    @Stateless public class MyClassR1 implements MyInterfaceR11, MyInterfaceR12 { public void foo() {} public void bar() {} }
    Le stateless bean "MyClassR1" implémente deux interfaces métiers distantes "MyInterfaceR11" et "MyInterfaceR12".
  - Si l'annotation @Remote est utilisée directement avec le stateless bean, alors les interfaces spécifiées comme paramètres de l'annotation constituent les interfaces métiers distantes.
    public interface MyInterfaceR21 { void foo(); }
    public interface MyInterfaceR22 { void bar(); }
    @Stateless @Remote({ MyInterfaceR21.class, MyInterfaceR22.class }) public class MyClassR2 implements MyInterfaceR21, MyInterfaceR22 { public void foo() {} public void bar() {} }
    Le stateless bean "MyClassR2" définit les interfaces "MyInterfaceR21" et "MyInterfaceR22" comme étant des interfaces métiers distantes (en utilisant l'annotation @Remote).
3. Annotation @LocalBean
  Le stateless bean qui utilise l'annotation @LocalBean expose toutes ses méthodes publiques au code s'exécutant par la même JVM y compris les méthodes des interfaces métiers distantes (annotées par l'annotation @Remote).
  
  Code source (JBoss) de l'annotation @LocalBean:
  package javax.ejb; /** * Designates that a session bean exposes a no-interface view. */ @Target({ ElementType.TYPE }) @Retention(RetentionPolicy.RUNTIME) public @interface LocalBean { }
  L'annotation n'accepte aucun paramètre.
  
  Exemple (1) :
  @Stateless @LocalBean public class MyClassLB1 { public void foo() {} public void bar() {} }
  Le stateless bean "MyClassLB1" expose les deux méthodes "foo" et "bar" au code s'exécutant par la même JVM.
  
  Exemple (2) :
  @Remote public interface MyInterfaceR31 { void foo(); }
  @Stateless @LocalBean public class MyClassLB2 implements MyInterfaceR31 { public void foo() {} public void bar() {} }
  - Le stateless bean "MyClassLB2" expose les deux méthodes "foo" et "bar" au code s'exécutant par la même JVM.
  - Le stateless bean "MyClassLB2" expose aussi la méthode "foo" au code s'exécutant sur une autre JVM (clients distants).
Annotations @PostConstruct, @PreDestroy
Annotations qui gèrent le cycle de vie du stateless bean :
@PostConstruct // (javax.annotation.PostConstruct) @PreDestroy // (javax.annotation.PreDestroy)
1. Annotation @PostConstruct
  Code source (JBoss) de l'annotation @PostConstruct:
  package javax.annotation; /** * The PostConstruct annotation is used on a method that needs to be executed after dependency injection is done to perform any initialization. * This method must be invoked before the class is put into service. * This annotation must be supported on all classes that support dependency injection. * The method annotated with PostConstruct must be invoked even if the class does not request any resources to be injected. * Only one method can be annotated with this annotation. * * The method on which the PostConstruct annotation is applied must fulfill all of the following criteria: * - The method must not have any parameters except in the case of EJB interceptors in which case it takes an InvocationContext object as defined by the EJB specification. * - The return type of the method must be void. * - The method on which PostConstruct is applied may be public, protected, package private or private. * - The method must not be static except for the application client. * - The method may be final. * - The method must not throw a checked exception. * - If the method throws an unchecked exception the class must not be put into service except in the case of EJBs where the EJB can handle exceptions and even recover from them. */ @Documented @Retention(RUNTIME) @Target(METHOD) public @interface PostConstruct { }
  Cette annotation permet de marquer une méthode du stateless bean qui va être exécutée (par le container EJB) directement après :
  - l'instanciation de la classe du stateless bean ; incluant l'exécution du code des blocs d'initialisation et du constructeur sans-arguments (constructeur par défaut).
  - et la résolution des dépendances du stateless bean.
  La méthode annotée par l'annotation @PostConstruct est garantie d'être exécutée avant les autres méthodes métiers du stateless bean.
2. Annotation @PreDestroy
  Code source (JBoss) de l'annotation @PreDestroy:
  package javax.annotation; /** * The PreDestroy annotation is used on methods as a callback notification to signal that the instance is in the process of being removed by the container. * The method annotated with PreDestroy is typically used to release resources that it has been holding. * This annotation must be supported by all container managed objects that support PostConstruct except the application client container in Java EE 5. * * The method on which the PreDestroy annotation is applied must fulfill all of the following criteria: * - The method must not have any parameters except in the case of EJB interceptors in which case it takes an InvocationContext object as defined by the EJB specification. * - The return type of the method must be void. * - The method on which PreDestroy is applied may be public, protected, package private or private. * - The method must not be static. * - The method may be final. * - The method must not throw a checked exception. * - If the method throws an unchecked exception it is ignored except in the case of EJBs where the EJB can handle exceptions. */ @Documented @Retention(RUNTIME) @Target(METHOD) public @interface PreDestroy { }
  Cette annotation permet de marquer une méthode du stateless bean qui va être exécutée (par le container EJB) juste avant la destruction du stateless bean.
3. Exemple: Utilisation des annotations @PostConstruct/@PreDestroy
  package com.mtitek.session.beans.stateless; import javax.annotation.PostConstruct; import javax.annotation.PreDestroy; import javax.ejb.Stateless; @Stateless public class StatelessCallbackMethods { // bloc d'initialisation { System.out.println("StatelessCallbackMethods (" + this.toString() + ") - INIT_BLOC"); } // Constructeur public StatelessCallbackMethods() { System.out.println("StatelessCallbackMethods (" + this.toString() + ") - DEFAULT_CONSTRUCTOR"); } @PostConstruct public void postConstructMethod() { System.out.println("StatelessCallbackMethods (" + this.toString() + ") - postConstructMethod"); } @PreDestroy public void preDestroyMethod() { System.out.println("StatelessCallbackMethods (" + this.toString() + ") - preDestroyMethod"); } public void testMethod() { System.out.println("StatelessCallbackMethods (" + this.toString() + ") - testMethod"); } }
  Voici la sortie dans la console JBoss quand le stateless bean est instancie :
  00:13:50,014 INFO [stdout] (EJB default - 1) StatelessCallbackMethods (com.mtitek.session.beans.stateless.StatelessCallbackMethods@3cff58ec) - INIT_BLOC 00:13:50,021 INFO [stdout] (EJB default - 1) StatelessCallbackMethods (com.mtitek.session.beans.stateless.StatelessCallbackMethods@3cff58ec) - DEFAULT_CONSTRUCTOR 00:13:50,030 INFO [stdout] (EJB default - 1) StatelessCallbackMethods (com.mtitek.session.beans.stateless.StatelessCallbackMethods@3cff58ec) - postConstructMethod
Exemple: Utilisation d'un stateless bean
- Déclarer une classe utilitaire qui va servir comme exemple pour expliquer les différences de passage de paramètres entre les méthodes des interfaces métiers locales et distantes :
  package com.mtitek.utils; import java.io.Serializable; public class ValueHolder<T> implements Serializable { private static final long serialVersionUID = 4701850614777963704L; private T value; public ValueHolder() { } public ValueHolder(T value) { this.value = value; } public T getValue() { return value; } public void setValue(T value) { this.value = value; } }
- Déclarer une interface générique que les interfaces métiers locales et distantes vont hériter :
  package com.mtitek.session.beans.stateless.interfaces; import com.mtitek.utils.ValueHolder; public interface ValueHolderManager { String setValueHolderInteger(ValueHolder<Integer> valueHolder); }
- Déclarer une interface et l'annoter avec l'annotation @Local :
  package com.mtitek.session.beans.stateless.interfaces; import javax.ejb.Local; @Local public interface ValueHolderManagerLocal extends ValueHolderManager { }
- Déclarer une interface et l'annoter avec l'annotation @Remote :
  package com.mtitek.session.beans.stateless.interfaces; import javax.ejb.Remote; @Remote public interface ValueHolderManagerRemote extends ValueHolderManager { }
- Déclarer une classe et l'annoter avec l'annotation @Stateless :
  package com.mtitek.session.beans.stateless; import javax.ejb.Stateless; import com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerLocal; import com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerRemote; import com.mtitek.utils.ValueHolder; @Stateless public class ValueHolderManagerBean implements ValueHolderManagerLocal, ValueHolderManagerRemote { @Override public String setValueHolderInteger(ValueHolder<Integer> valueHolder) { valueHolder.setValue(10); return "ValueHolder (" + valueHolder.toString() + ") = " + valueHolder.getValue(); } }
Exemple: Accéder un stateless bean en utilisant DI (Dependency Injection))
Déclarer une classe et l'annoter avec l'annotation @Stateless :
package com.mtitek.session.beans.stateless.test; import javax.ejb.EJB; import javax.ejb.Stateless; import com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerLocal; import com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerRemote; import com.mtitek.utils.ValueHolder; @Stateless public class ValueHolderManagerTestDI { // L'annotation @EJB indique au container EJB d'injecter une instance du stateless bean ValueHolderManagerBean // (l'instance sera affecter à la variable valueHolderManagerLocal) @EJB ValueHolderManagerLocal valueHolderManagerLocal; @EJB ValueHolderManagerRemote valueHolderManagerRemote; public String testMyManagerLocal() { ValueHolder<Integer> valueHolder = new ValueHolder<Integer>(50); return "ValueHolder (" + valueHolder.toString() + ") = " + valueHolder.getValue() + "\n" + valueHolderManagerLocal.setValueHolderInteger(valueHolder) + "\n" + valueHolder.getValue(); } public String testMyManagerRemote() { ValueHolder<Integer> valueHolder = new ValueHolder<Integer>(50); return "ValueHolder (" + valueHolder.toString() + ") = " + valueHolder.getValue() + "\n" + valueHolderManagerRemote.setValueHolderInteger(valueHolder) + "\n" + valueHolder.getValue(); } }
L'invocation de la méthode "testMyManagerLocal" donnera le résultat suivant :
ValueHolder (com.mtitek.utils.ValueHolder@196a35c) = 50 ValueHolder (com.mtitek.utils.ValueHolder@196a35c) = 10 10
L'invocation de la méthode "testMyManagerRemote" donnera le résultat suivant :
ValueHolder (com.mtitek.utils.ValueHolder@48beedd4) = 50 ValueHolder (com.mtitek.utils.ValueHolder@32ba5d72) = 10 50
Notes :
- Dans le cas de l'utilisation de l‘interface métier locale, l'instance de la classe "ValueHolder" est passée en référence.
- Dans le cas de l'utilisation de l‘interface métier distante, l'instance de la classe "ValueHolder" est passée en valeur et cela même si le code est exécuté par la même JVM.
Exemple: Accéder un stateless bean en utilisant JNDI
Notes :
- Voir les détails sur JNDI dans la page : JNDI.
- Voir l'exemple comment utiliser JNDI (client distant) dans la page : JNDI (JBOSS AS).
package com.mtitek.session.beans.client; import javax.naming.InitialContext; import javax.naming.NamingException; import com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerRemote; import com.mtitek.utils.ValueHolder; public class ValueHolderManagerTestJndi { public static void main(String[] args) { InitialContext ctx; ValueHolderManagerRemote valueHolderManagerRemote; try { ctx = new InitialContext(); valueHolderManagerRemote = (ValueHolderManagerRemote) ctx.lookup("ejb:/myejb/ValueHolderManagerBean!com.mtitek.session.beans.stateless.interfaces.ValueHolderManagerRemote"); ValueHolder<Integer> valueHolder = new ValueHolder<Integer>(50); System.out.println("ValueHolder (" + valueHolder.toString() + ") = " + valueHolder.getValue()); System.out.println(valueHolderManagerRemote.setValueHolderInteger(valueHolder)); System.out.println(valueHolder.getValue()); } catch (NamingException e) { e.printStackTrace(); } } }
L'invocation de la méthode "testMyManagerRemote" donnera le résultat suivant :
ValueHolder (com.mtitek.utils.ValueHolder@36d251a3) = 50 ValueHolder (com.mtitek.utils.ValueHolder@404e6e81) = 10 50
Notes : Vu que l‘interface métier distante est utilisée, alors l'instance de la classe "ValueHolder" est passée en valeur.