EJB 3.0: les interceptors

Celinio FERNANDES

Ce tutoriel a pour but de présenter une des nouvelles fonctionnalités apportées par la spécification EJB 3.0 :
les interceptors.

- Titre : EJB 3.0: les interceptors

- Auteur : Celinio FERNANDES

- Parution : 31 décembre 2007

- Mise à jour : 7 janvier 2013

- Licence : Copyright ® 2007 Celinio FERNANDES. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Définition

- II. Avantages

- III. Exemples d'utilisation

- IV. Le pattern Chain of Responsibility (CoR)

- V. L'interface InvocationContext

- VI. Exemple

- VII. Liens

- VIII. Remerciements

I - Définition

Un interceptor est une méthode qui intercepte l'appel d'une méthode métier.

Les interceptors fonctionnent à la manière des filtres avec les servlets.

Ils sont automatiquement appelés, juste avant que les méthodes métiers du bean soient appelées.

Ils peuvent être appliqués à des méthodes métiers dans des session beans (stateful et stateless) et dans des message-driven beans.

On peut définir une méthode interceptor dans une classe bean ou dans une classe dédiée.
La signature d'une méthode interceptor est la suivante:

1. @javax.ejb.AroundInvoke

2. public Object [nomMethode](javax.ejb.InvocationContext ctx) throws java.lang.Exception

Une classe interceptor ou une classe bean ne peut avoir qu'une seule méthode @AroundInvoke.

II - Avantages

- un contrôle plus fin dans le déroulement d'une méthode.

- on peut de façon élégante analyser et manipuler des paramètres et autoriser ou interdire l'exécution d'une méthode métier.

- on arrive ainsi à gérer des fonctionnalités techniques (logging, traçage, sécurité) de façon transparente dans les méthodes métiers.

III - Exemples d'utilisation

- contrôle des permissions sur des méthodes

- modification des paramètres avant qu'ils soient passés au bean ( InvocationContext.getParameters() )

- modifier la valeur retourner par un bean

- catcher et gérer les exceptions des méthodes

- totalement interrompre l'appel

- etc

IV - Le pattern Chain of Responsibility (CoR)

Les interceptors sont une forme du pattern Chain of Responsibility.

Ce pattern concerne une chaîne d'objets qui sont liés à travers des références indirectes pour permettre à un objet de traiter une requête ou la passer à un autre objet dans la chaîne.

C'est ce qui se passe avec les interceptors dans les EJB :

la méthode proceed() provoque l'appel de la prochaine méthode interceptor dans la chaîne.

Quand la dernière méthode interceptor AroundInvoke est appelée, la méthode proceed() appelle la méthode métier du bean.

La flèche ci-dessous illustre les enchaînements dans le cas de plusieurs intercepteurs appliqués à un bean:

1. @Interceptors({Interceptor1.class, Interceptor2.class, Interceptor3.class})

2. public class MonBean {

3. &#8230;

4. public void methode() {

5. &#8230;}

6. }

V - L'interface InvocationContext

L'interface InvocationContext permet de propager un état à travers une chaîne d'interceptors.

view plainprint?

1. package javax.interceptor;

3. public interface InvocationContext {

4. public Object getBean();

5. public java.lang.reflect.Method getMethod();

6. public Object[] getParameters();

7. public void setParameters(Object[] params);

8. public java.util.Map getContextData();

9. public Object proceed() throws Exception;

10. }

Il faut toujours appeler la méthode proceed() dans l'appel de l'objet invocationContext. Sinon, l'invocation de la méthode ne continue pas.

VI - Exemple

Voici un exemple d'un mini projet qui définit une classe interceptor, ainsi qu'une méthode interceptor à l'intérieur du bean.

Les deux sont appelées mais selon un ordre:

les interceptors sont appelés dans l'ordre dans lequel ils sont spécifiés mais les interceptors définis dans des classes externes sont éxécutées AVANT un interceptor définit dans une classe bean.

Dans cet exemple, elles affichent des traces dans les fichiers logs du serveur d'application, ainsi que dans le fichier de trace log4J.

Si on choisit le serveur d'application JBoss, il faut aller voir dans : {jboss-install-path}\server\default\log\server.log

La business interface BonjourRemote.java :

1. package org.developpez.tutorial.stateless.bean;

3. import javax.ejb.Remote;

5. @Remote

6. public interface BonjourRemote {

7. public void bonjour();

8. public String aurevoir();

9. }

Avec l'annotation @Interceptors, on indique quelles classes externes vont être utilisées en tant qu'interceptors.

Toutes les méthodes du bean sont interceptées.

L'annotation @AroundInvoke est utilisée pour définir une méthode en tant qu'interceptor.

La classe bean BonjourBean.java :

1. package org.developpez.tutorial.stateless.bean;

3. import javax.ejb.Stateless;

4. import javax.interceptor.AroundInvoke;

5. import javax.interceptor.Interceptors;

6. import javax.interceptor.InvocationContext;

8. import org.apache.log4j.Logger;

10. @Stateless

11. @Interceptors(org.developpez.tutorial.stateless.bean.TraceInterceptor.class)

12. public class BonjourBean implements BonjourRemote{

14. private static org.apache.log4j.Logger log = Logger.getLogger(BonjourBean.class);

16. public void  bonjour()

17. {

18. log.info("Bonjour toi");

19. }

21. public String aurevoir()

22. {

23. return "au revoir";

24. }

26. @AroundInvoke

27. public Object myBeanInterceptor(InvocationContext ctx) throws Exception

28. {

29. if (ctx.getMethod().getName().equals("bonjour"))

30. {

31. log.info("*** bonjour!");

32. }

34. if (ctx.getMethod().getName().equals("aurevoir"))

35. {

36. log.info("*** Au revoir!");

37. }

39. return ctx.proceed();

40. }

41. }

La classe interceptor TraceInterceptor.java :

1. package org.developpez.tutorial.stateless.bean;

3. import javax.interceptor.AroundInvoke;

4. import javax.interceptor.InvocationContext;

6. import org.apache.log4j.Logger;

8. public class TraceInterceptor {

10. private static org.apache.log4j.Logger log = Logger.getLogger(TraceInterceptor.class);

12. @AroundInvoke

13. public Object log(InvocationContext ctx) throws Exception

14. {

15. log.info("*** Interception par TraceInterceptor");

16. long start = System.currentTimeMillis();

17. try

18. {

19. return ctx.proceed();

20. }

21. catch(Exception e)

22. {

23. throw e;

24. }

25. finally

26. {

27. long time = System.currentTimeMillis() - start;

28. String method = ctx.getClass().getName() + "." + ctx.getMethod().getName() + "()";

29. log.info("*** TracingInterceptor : l'invocation de " + method + " a pris " + time + "ms");

30. }

31. }

32. }

La classe Client.java :

1. package org.developpez.tutorial.client;

3. import javax.naming.InitialContext;

5. import org.apache.log4j.Logger;

6. import org.developpez.tutorial.stateless.bean.BonjourRemote;

8. public class Client

9. {

10. private static org.apache.log4j.Logger log = Logger.getLogger(Client.class);

12. public static void main(String[] args) throws Exception

13. {

14. InitialContext ctx = new InitialContext();

15. BonjourRemote bonjourRemote = (BonjourRemote)ctx.lookup("BonjourBean/remote");

16. bonjourRemote.bonjour();

17. log.info(bonjourRemote.aurevoir());

18. System.out.println("Et voila !");

19. }

20. }

Le fichier jndi.properties :

1. java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory

2. java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces

3. java.naming.provider.url=localhost:1099

Le fichier log4j.properties :

1. log4j.appender.R=org.apache.log4j.RollingFileAppender

2. log4j.appender.R.File=sortie.log

3. log4j.appender.R.layout=org.apache.log4j.PatternLayout

4. log4j.appender.R.layout.ConversionPattern=%p  %d{hh:mm:ss} %t %c{1} -%m%n

5. log4j.appender.R.MaxBackupIndex=1

6. log4j.appender.R.MaxFileSize=100KB

7. log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

8. log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) -%m%n

9. log4j.appender.stdout=org.apache.log4j.ConsoleAppender

10. log4j.rootLogger=stdout,R

11. log4j.appender.R.Append=true

En sortie, le fichier sortie.log (spécifique log4J) :

1. DEBUG  09:22:02 main SecurityAssociation -Using ThreadLocal: false

2. DEBUG  09:22:02 main Client -invoke called, but our invoker is disconnected, discarding and fetching another fresh invoker for: InvokerLocator [socket://192.168.1.111:3873/]

3. DEBUG  09:22:02 main SocketClientInvoker -connect called for: org.jboss.remoting.transport.socket.SocketClientInvoker@158f9d3

4. INFO  09:22:02 main Client -au revoir

En sortie, le fichier server.log (spécifique JBoss) :

1. 2007-12-20 21:22:02,953 DEBUG [org.jboss.remoting.transport.socket.ServerThread] beginning dorun

2. 2007-12-20 21:22:02,953 INFO  [org.developpez.tutorial.stateless.bean.TraceInterceptor] *** Interception par TraceInterceptor

3. 2007-12-20 21:22:02,953 INFO  [org.developpez.tutorial.stateless.bean.BonjourBean] *** bonjour!

4. 2007-12-20 21:22:02,953 INFO  [org.developpez.tutorial.stateless.bean.BonjourBean] Bonjour toi

5. 2007-12-20 21:22:02,953 INFO  [org.developpez.tutorial.stateless.bean.TraceInterceptor] *** TracingInterceptor : l'invocation de org.jboss.ejb3.interceptor.InvocationContextImpl.bonjour() a pris 0ms

6. 2007-12-20 21:22:02,968 INFO  [org.developpez.tutorial.stateless.bean.TraceInterceptor] *** Interception par TraceInterceptor

7. 2007-12-20 21:22:02,968 INFO  [org.developpez.tutorial.stateless.bean.BonjourBean] *** Au revoir!

8. 2007-12-20 21:22:02,968 INFO  [org.developpez.tutorial.stateless.bean.TraceInterceptor] *** TracingInterceptor : l'invocation de org.jboss.ejb3.interceptor.InvocationContextImpl.aurevoir() a pris 0ms

On voit bien ici que la méthode log(InvocationContext ctx) définit dans la classe interceptor est exécutée avant celle définit dans la classe bean, myBeanInterceptor(InvocationContext ctx).

Cette technique d'interception se rapproche de la programmation par aspect (AOP): le code métier est séparé du code d'interception.

Une méthode interceptor est appelée un advice, et la classe contenant un advice est appelée un aspect.

On peut également appliquer une méthode interceptor à une seule méthode d'un bean, en annotant cette dernière :

1. @Interceptors(MaClass.class)

2. public void uneMethodeDuBean(int param){

3. ...

4. }

On peut également définir les interceptors de façon déclarative dans le fichier de déploiement ejb-jar.xml :

1. <session>

2. <ejb-name>Bjour</ejb-name>

3. <remote>org.developpez.tutorial.stateless.bean.BonjourRemote</remote>

4. <ejb-class>org.developpez.tutorial.stateless.bean.BonjourBean </ejb-class>

5. ...

6. <interceptor>

7. <class> TraceInterceptor </class>

8. <method-name> log </method-name>

9. </interceptor>

10. <interceptor>

11. <method-name> myBeanInterceptor</method-name>

12. </interceptor>

13. </session>

VII - Liens

- Le package javax.interceptor

- Docs EJB

- EJB 3.O specification (JSR-220)

VIII - Remerciements

Je tiens à remercier Ricky81, OButterlin pour les conseils, remarques et relectures, ainsi que RideKick pour la correction orthographique.

Je remercie aussi www.developpez.com me permettant de publier cet article et Nono40 pour ses outils.