Tutorial EJB 3.0 de Session avec JBoss 4.

Ce tutorial prsente la cration dun EJB 3.0 trs simple avec JBoss 4.2. Il sagit dune introduction rapide aux concepts des EJB 3.0 de type Session. Il existe galement sur ce Blog, un tutorial sur les EJB 3.0 Entits : il commence l : Prsentation du tutorial sur le mapping par annotations des EJB Entits 3.0.

Une rapide prsentation des EJB 3.0

Les EJB 3.0 permettent de dcoupler le code client de linterface (susceptible de changer rapidement) du code mtier (gnralement plus stable). Le code mtier doit tre excut dans un objet diffrent de celui qui gre laffichage. Les EJB permettent galement dappeler un service excut sur une machine distante depuis un poste client. Dans ce cas, on utilise galement un mcanisme de communication comme JNDI. Dans tous les cas, les EJB ncessite la prsence dun serveur dapplication capable dtre conteneur dEJB. Les deux serveurs dEJB Open Source les plus connus sont JBoss et Resin. Dans notre tutorial nous allons utiliser JBoss dans sa version 4.2. Les EJB 3.0 reposent sur le mcanisme dannotation qui simplifie grandement la mise en uvre : autrefois, il tait ncessaire de multiplier les fichiers quils sagissent de classes Java ou de fichier de configuration XML. Aujourdhui cela devient trs simple. Il y a deux grandes sortes dEJB : Les EJB sessions : il sagit dobjets qui rendent un service et qui permettent dassurer une transaction. Les EJB Entity : il sagit dobjet qui correspondent des enregistrements dune base de donnes et qui grent l'accs la base de donnes.

Ce tutorial ne concerne que les EJB de types session.

Organisation du tutorial
Ce tutorial a pour objectif de prsenter une mise en uvre basique dun EJB 3.0 avec JBoss 4.2. Je me suis inspir du tutorial fournis par JBoss lurl suivante http://docs.jboss.org/ejb3/appserver/tutorial/stateless/stateless.html. Jai essay dtre un peu plus prcis et complet en prsentant toutes les classes ncessaires. Jai galement simplifi le nombre de classes dinterface. Comme la quasi-totalit des tutoriaux de ce blog, il repose sur lutilisation dEclipse 3.2. Jai install sur mon Eclipse les plug-in Web Standard Tool (WST) et J2EE Standard Tool (JST) dont vous pouvez trouver une prsentation sur ce poste de mon blog : Plug-In Web pour Eclipse. A priori ces plug-in ne sont pas utiles pour ce tutorial, vous devriez pouvoir vous en passer. Le tutorial comprendra les tapes suivantes : La configuration de JBoss 4.2 La ralisation de lEJB 3.0 dans Eclipse La construction du client de cet EJB ralis dans un autre projet Eclipse.

Configuration
Le tutorial a t ralis sur un poste Windows XP SP2.

Le runtime et le jdk Java sont la version 1.5.0_11. Lenvironnement de dveloppement est Eclipse 3.2. Il est quip des plug-in JST (J2EE Standard Tool) et WST (Web Standard Tool) comme indiqu prcdemment. Pour JBoss, jai utilis la version 4.2 GA du 5 mai 2007. La page de tlchargement peut tre trouv lurl suivante :http://sourceforge.net/project/showfiles.php? group_id=22866&package_id=16942&release_id=507793 Jai utilis la distribution au format zip : jboss-4.2.0.GA.zip. La version 4.2 de JBoss ncessite un JDK 1.5. Elle contient en standard les EJB 3.0 et il nest plus ncessaire de lancer un installateur supplmentaire.

Prparation de JBoss
Vous devez dans un premier temps tlcharger le fichier JBoss indiqu prcdemment. Suite son tlchargement, il faut le dezipper dans un rpertoire. Comme il est recommand dutiliser un chemin ne contenant pas despace, jai choisi c:\ jboss-4.2.0.GA. Cette installation nest pas intrusive sur votre poste : la seule modification ralise sur votre poste et la cration de ce rpertoire avec son contenu. Lorganisation du rpertoire JBoss est la suivante : Bin : cest le rpertoire qui contient la commande qui permet de dmarrer JBoss: run.bat Client : ce rpertoire contient des librairies java sous forme de jar permettant un client java de travailler avec un serveur dapplication JBoss. Cela comprend notamment lappel dEJB. Docs : ce rpertoire contient des exemples Lib : ce rpertoire contient les jar de bases du serveur. Il ne doit pas tre modifi Server : cest le rpertoire qui contient les diffrentes configurations de fonctionnement de JBoss.

JBoss a une particularit par rapport Tomcat : il est possible de dfinir plusieurs configurations de fonctionnement : une configuration comprend la fois les services JBoss activs mais galement les applications que vous avez installes. Quand vous dmarrez le serveur JBoss il est possible de lui indiquer la configuration que vous souhaitez utiliser. Il est donc possible de basculer rapidement dune configuration lautre. Par dfaut, la configuration utilise est celle qui sappelle default. Linstallation de base de JBoss dfinit 3 configurations : all, minimal et default. Nous utiliserons default. Personnellement afin de pouvoir toujours revenir rapidement la configuration default dorigine, je commence toujours par faire une copie de ce rpertoire avec lexplorateur Windows. Pour tester linstallation de JBoss on le dmarre en double cliquant sur c:\ jboss-4.2.0.GA\run.bat. Cela dmarre le serveur JBoss avec sa configuration par dfaut. Une fentre DOS souvre pour afficher une trace. Cette trace doit sachever par une ligne : INFO [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA date=200705111440] Started in XXs:XXms O il faut remplacer XX par le temps de dmarrage constat. Ouvrez maintenant un browser et tapez lurl suivante : http://localhost:8080/jmx-console/ Une page daccueil JBoss souvre.

Attention JBoss utilise par dfaut le port 8080 de votre machine. Si vous avez sur votre poste un autre serveur dapplication comme Tomcat qui utilise le port 8080, vous devez vous assurer que ce dernier est arrt. Attention galement bien utiliser localhost et non pas votre nom de machine. Seul localhost fonctionne par dfaut pour des raisons de scurit : la console jmx est une application dadministration, il nest pas souhaitable quelle soit accessible depuis un autre poste par dfaut. Pour arrter JBoss, il suffit de faire Ctrl C dans la console DOS. Quand le message terminer le programme de commandes (O/N) ? apparat appuyer sur O puis Return.

Cration dun projet Eclipse pour lEJB

Dans Eclipse, on cre un projet Java simple que lon nommera MaCalculetteEJB. Menu File, Sous menu New, puis Project Dans la dialogue New Project, choisir le dossier Java puis le nud Java Project. Appuyez sur le bouton Next. Pour Project name, tapez : MaCalculetteEJB et laissez les autres options par dfaut. Appuyez sur Finish. Acceptez le choix de la perspective Java si la dialogue Open Associated Perspective saffiche. Il faut importer des jar JBoss : cliquez droit sur le projet dans lexplorateur et choisissez Properties. Dans la dialogue qui souvre choisir Java Build Path . Appuyer sur Add External Jars.. , et utiliser lexplorateur pour aller dans le rpertoire C:\jboss4.2.0.GA\server\default\lib et slectionnez les jar suivant : Ejb3-persistence.jar Jboss-ejb3x.jar

Validez en appuyant sur Ok. Notre projet est maintenant correctement configur pour construire un EJB de type Session.

Cration de linterface
Nous commenons par crer linterface du service. Linterface dfinit les mthodes qui seront disponibles dans lEJB. Linterface est galement utilise par le code client. A partir de la barre de menu : File -> New -> Interface Dans la dialogue New Java Interface: Pour Package, tapez : fr.j2ltho.calculette.ejb Pour Name tapez : MaCalculette

Laissez les autres options par dfaut et appuyez sur Finish.

On modifie le code pour dfinir les deux mthodes add et substract du service. On ajoute lannotation @Remote pour spcifier au conteneur dEJB quil devra cr un lien de type Remote avec cette interface pour lEJB. On obtient le code suivant :

package fr.j2ltho.calculette.ejb; import javax.ejb.Remote; @Remote public interface MaCalculette { public int add(int x, int y); public int subtract(int x, int y); }

Cration du Bean
Nous commenons par crer la classe qui implmente le service. A partir de la barre de menu : File -> New -> Class Dans la dialogue New Java Class : Pour Package, tapez : fr.j2ltho.calculette.ejb Pour Name tapez : MaCalculetteBean

Appuyez, sur le bouton Add.. afin de dfinir linterface. Dans la dialogue Implemented Interfaces Selection tapez MaCalculette puis slectionnez linterface "MaCalculette fr.j2ltho.calculette.ejb" de votre projet. Validez en appuyant sur Ok. La dialogue se referme et linterface apparat dans la liste Interfaces de la dialogue New java Class . Laissez les autres options par dfaut et appuyez sur Finish. Le code de la classe apparat avec les deux mthodes cres, il faut maintenant complter le code. Il faut galement ajouter : lannotation @Stateless en dbut de classe. Cette annotation prcise que cet EJB sera sans tat : il ne conserve pas une mmoire de ce quil a fait prcdemment. On obtient le code suivant :

package fr.j2ltho.calculette.ejb; import javax.ejb.Stateless; @Stateless public class MaCalculetteBean implements MaCalculette { public int add(int x, int y) { return x + y ; } public int subtract(int x, int y) { return x - y; } }

Il tait possible dajouter lannotation @Remote en spcifiant le nom de la classe dinterface aprs lannotation Stateless. Cela remplace lannotation Remote quon a ajout au niveau de la classe dinterface. Dans ce cas, on aurait eu les deux annotations suivantes :

@Stateless @Remote ({MaCalculette.class})

Gnration du jar
Assurez vous davoir bien sauvegarder la classe et son interface. Cliquez droit dans lexplorateur de ressource dEclipse sur votre projet MaCalculetteEJB, slectionnez Export, dans la dialogue Export qui saffiche choisissez, dans Java, JAR file. Puis Next. Slectionner lemplacement et le nom du JAR File. Pour ma part je lai cr directement dans le rpertoire C:\jboss-4.2.0.GA\server\default\deploy qui est le rpertoire de dploiement pour la configuration par default. Le nom du fichier est MaCalulette.jar. Appuyez, ensuite sur Finish. Vous devriez trouver un fichier MaCalulette.jar dans le rpertoire C:\jboss-4.2.0.GA\server\default\deploy. Si on lance JBoss, on devrait voir safficher quelques lignes avant la dernire ligne les lignes suivantes :

11:38:11,999 INFO [JmxKernelAbstraction] installing MBean: jboss.j2ee:jar=MaCalculette.jar,name=MaCalculetteBean,service= EJB3 with dependencies: 11:38:12,139 INFO [EJBContainer] STARTED EJB: fr.j2ltho.calculette.ejb.MaCalculetteBean ejbName: MaCalculetteBean 11:38:12,155 INFO [EJB3Deployer] Deployed: file:/C:/jboss4.2.0.GA/server/default/deploy/MaCalculette.jar

Cration dun projet Eclipse pour le client

Dans Eclipse, on cre un second projet Java simple que lon nommera MonClientEJB. Menu File, Sous menu New, puis Project Dans la dialogue New Project, choisir le dossier Java puis le nud Java Project. Appuyez sur le bouton Next. Pour Project name, tapez : MonClientEJB et laissez les autres options par dfaut. Appuyez sur Finish. Acceptez le choix de la perspective Java si la dialogue Open Associated Perspective saffiche. Il faut importer des jar JBoss ncessaire lappel dun EJB : cliquez droit sur le projet dans lexplorateur et choisissez Properties. Dans la dialogue qui souvre choisir Java Build Path .

Appuyer sur Add External Jars.. , et utiliser lexplorateur pour aller dans le rpertoire C:\jboss4.2.0.GA\client et slectionnez les jar : Jnp-client.jar Jbossall-client.jar

Il faut galement utiliser le Jar gnr prcdemment : Appuyer sur Add External Jars.. , et utiliser lexplorateur pour aller dans le rpertoire C:\jboss-4.2.0.GA\ server\default\deploy et slectionnez le jar : MaCalculette.jar. Validez en appuyant sur Ok.

Ajout dun fichier jndi

Lappel dun EJB par un client repose sur les APIs JNDI. Pour que cela fonctionne, il faut dfinir un fichier jndi.properties qui indique au client, o est le serveur dEJB. Dans Eclipse, Menu File, Sous menu New, puis File Dans la dialogue New File, tapez comme nom jndi.properties puis validez. Un fichier est cr, modifiez le afin que son contenu soit :

java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces java.naming.provider.url=localhost

Sauvez et fermez. Attention ! Le provider.url est obligatoirement localhost. Notre poste est maintenant correctement configur pour construire un EJB de type Session.

Cration de la classe cliente

Dans Eclipse. Nous allons crer une classe de type Main afin dappeler ce service web. Menu File, Sous menu New, puis Class Dans la dialogue New Java Class : Pour Package, tapez : fr.j2ltho.client.test.ejb Pour Name tapez : TestMaCalculetteMain Cochez la checkbox public static void main(String[] args)

et laissez les autres options par dfaut. Appuyez sur Finish. Le code ajouter est trs simple : On rcupre dabord grce JNDI un contexte dappel du serveur dEJB. Ce contexte nous permet ensuite dinstancier notre Service MaCalculette (remarquer quon utilise linterface et non le bean).

Pour finir, on appelle les deux services.

package fr.j2ltho.client.test.ejb; import javax.naming.InitialContext; import javax.naming.NamingException; import fr.j2ltho.calculette.ejb.MaCalculette; public class TestMaCalculetteMain { public static void main(String[] args) throws NamingException { InitialContext ctx = new InitialContext(); MaCalculette calculator = (MaCalculette) ctx.lookup("MaCalculetteBean/remote"); System.out.println("4 + 3= " + calculator.add(4, 3)); System.out.println("5 - 1 = " + calculator.subtract(5, 1)); } }

Pour tester, on sauve, puis on clique droit sur la classe TestMaCalculetteMain dans le Package Explorer dEclipse. Choisissez le menu Run As, puis le sous menu Java Application. La console affiche en bas est rafrachie et affiche deux lignes :

4 + 3 = 7 5 - 1 = 4

Conclusion
Nous avons vu rapidement comment crer un EJB de session 3.0. Vous allez pouvoir transformer dans le tutorial suivant cet EJB en service web de type JAX-WS. JAX-WS est une nouvelle norme Java permettant de creer trs simplement un service web en utilisant les annotations. La premire tapes tant de crer un EJB Session, vous pouvez maintenant continuer avec l'tape suivante : Tutorial service web avec JBoss 4.2. Mise jour : Pour les personnes qui souhaitent avoir une introduction/prsentation sur les EJB 3.0, vous pouvez lire mon billet Faut-il utiliser les EJB 3.0 et la Java Persistence API ? Aprs cette rapide introduction sur les EJB 3.0 Entit, vous pouvez parcourir mon tutorial sur le sujet qui commence l : Prsentation du tutorial sur le mapping par annotations des EJB Entits 3.0. Merci l'anonyme qui par son commentaire, m'a rappel le lien logique entre les deux tutoriaux.