La première étape de la préparation d'Eclipse consiste à prendre en charge le serveur Glassfish au travers de son plugin. Pour cela, on déclare Glassfish en tant que runtime environment.

La liste des runtime environment est accessible via les préférences d'Eclipse.

Figure 2. Ouverture des préférences d'Eclipse

Cette fenêtre présente de nombreuses options, qu'il est possible de filtrer. L'option que l'on cherche est Server > Runtime environment.

Figure 3. Sélection de l'option runtime environment

Il faut cliquer sur le bouton Add... pour ajouter un runtime environment, ce qui nous mène au panneau suivant.

Figure 4. Sélection de Glassfish

On peut alors sélectionner la bonne version de Glassfish, et accéder à la suite des panneaux de configuration.

Figure 5. Configuration du serveur - 1

On sélectionne le bon JDK dans un premier temps.

Figure 6. Configuration du serveur - 2

Puis on sélectionne son répertoire d'installation. Attention, le répertoire que demande Eclipse correspond au répertoire $GLASSFISH_HOME/glassfish.

Figure 7. Configuration du serveur - 3

Valider l'installation fait apparaître Glassfish dans la liste des environnements d'exécution disponibles.

Figure 8. Glassfish correctement installé

Glassfish permet de gérer de nombreuses choses, dont une qui va nous être immédiatement utile : une connexion à une base de données. La gestion peut se faire au travers d'Eclipse, ce qui est très pratique. Il faut pour cela ouvrir Glassfish dans Eclipse.

Pour cela, on utilise la vue Servers de la perspective JEE d'Eclipse.

Figure 9. Gestion de Glassfish dans Eclipse

La création de ce nouveau serveur au niveau d'Eclipse nous mène au même panneau que précédemment. Cette fois Glassfish est associé à une installation, qui est sélectionnée par défaut dans le panneau.

Figure 10. Choix de Glassfish

Le panneau suivant nous demande deux informations, qu'Eclipse ne peut pas deviner : le domaine que nous allons utiliser, et le mot de passe de l'administrateur de ce domaine. Comme nous avons pris la précaution de créer un domaine au préalable, nous allons pouvoir le donner à Eclipse.

Figure 11. Configuration du domaine - 1

Une fois le domaine correctement configuré, Eclipse ne nous donne plus de message d'erreur.

Figure 12. Configuration du domaine - 2

La dernière étape consiste à ajouter des projets JEE à ce domaine. Nous n'en avons pas pour le moment, la fenêtre est donc vide, et on peut la passer.

Figure 13. Configuration du domaine - 3

Une fois cette configuration terminée, Glassfish apparaît dans la vue Servers, aux côtés de Tomcat.

Figure 14. Glassfish configuré

Cette partie suppose que l'on a configuré une base de données Derby en mode serveur, et que cette base de données est lancée. Pour ce faire, on peut se reporter au tutorial Premiers pas avec Derby dans Eclipse.

Glassfish est administré via une application web, qui se lance en même temps que le serveur. On se propose à présent de créer une première source de données à partir de ce panneau.

La première chose à faire est de lancer Glassfish, en cliquant sur le bouton Start.

Figure 15. Démarrer Glassfish

Eclipse active la vue Console, dans laquelle apparaît la journalisation de Glassfish. Après quelques secondes, Glassfish est démarré, et l'on peut accéder à la console d'administration en chargeant l'URL :4848/. Le panneau de connexion s'affiche en quelques secondes.

J'ai constaté un bug curieux dans le couple Eclipse / Glassfish, du moins avec les versions que j'utilise, sous Windows. Lors du lancement d'Eclipse, si le PATH comprend des chemins avec des espaces, alors Glassfish ne se lance pas. La solution consiste pour moi à créer un fichier le lancement (un bon vieux .bat des familles) avec un PATH minimal, qui ne comporte pas ce défaut.

Figure 16. Connexion au panneau d'administration

Le nom de connexion est admin, et le mot de passe est celui qui a été entré au moment de la création du domaine.

Une fois authentifié, le panneau d'administration complet s'affiche. L'objet de ce tutorial n'est pas de détailler chacune de ses fonctionnalités. Nous allons juste l'utiliser pour créer une source de données.

Figure 17. Panneau d'administration de Glassfish

Une source de données se crée en deux temps :

La création du pool se fait au travers de l'interface d'administration de Glassfish. Le nom de ce pool ne peut pas contenir d'espaces, il faut donc prendre garde à ce point. Le type choisi peut être javax.sql.DataSource, et dans le cas de Derby, la classe d'implémentation sera org.apache.derby.jdbc.ClientDataSource. Les propriétés du pool sont les propriétés JDBC classiques : identifiant de connexion et mot de passe, nom de la base, qui doivent bien sûr correspondre aux paramètres de la base Derby.

Si la base Derby est bien lancée, il est possible de vérifier que ce pool s'y connecte bien, en cliquant sur le bouton Ping.

La création de la source de données se fait ensuite. Il faut renseigner deux paramètres pour cette création.

On peut, en suivant la même procédure, ouvrir des sources de données sur autant de bases que l'on veut, et de n'importe quel type.

Supposons que l'on ait déjà un projet JPA sous la main, avec une unique classe, Marin. Pour créer un tel projet, on pourra se reporter au tutorial Premier pas avec Eclipse et JPA.

Le projet JPA que l'on ajoute a la structure suivante, rien ne le différencie de celui que l'on a construit sur notre tutorial.

Figure 18. Structure du projet JPA

La structure de notre projet JPA n'est pas différente de celui que l'on a vu dans le tutorial précédent. En revanche, le contexte d'utilisation est différent : il s'agit d'un projet JEE, alors que le précédent était un projet JSE. Plutôt que de se connecter directement à une base de données, notre unité de persistence doit utiliser la source de données que l'on a défini précédemment. Pour cela, on doit modifier le fichier persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0"
	xmlns="http://java.sun.com/xml/ns/persistence" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
	                    http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
	
	<persistence-unit name="jpa-project" transaction-type="JTA">
		
		<!-- Eclipse link JPA implementation -->
		<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
		
		<!-- Data source definition -->
		<jta-data-source>jdbc/MelodieDS</jta-data-source> 
	
		<class>org.paumard.model.Marin</class>
		
		<properties>
			<property name="eclipselink.ddl-generation"  
			          value="drop-and-create-tables"/>
		</properties>
		
	</persistence-unit>
	
</persistence>

On remarquera les différences suivantes.

Le code de notre classe Marin ne contient pas de points trop exotiques.

@Entity(name="marin")
@Table(name="marin")
public class Marin implements Serializable {

	@Id @GeneratedValue(strategy=GenerationType.AUTO)
	private long id;
	private String nom;
	private String prenom;
	private int salaire;

	public Marin() {
	}
	   
	public Marin(String nom, String prenom, int salaire) {
		this.nom = nom ;
		this.prenom = prenom ;
		this.salaire = salaire ;
	}
	
	// suivent les getters et les setters
	
}

Le deuxième projet que nous allons créer va nous permettre de stocker les interfaces de nos EJB. Ce projet est un projet Java classique, qui a juste besoin de connaître les classes du projet JPA, puisque c'est là que se trouve notre modèle objet.

Pour l'instant on crée une unique classe dans ce projet : MarinService, qui n'expose qu'une unique méthode.

Figure 19. Structure de notre projet ejb-interface

La dépendance vers le projet JPA est définie dans les propriétés de ce projet, de façon classique.

Figure 20. Dépendances du projet ejb-interface

Le code de notre interface est le suivant. Il s'agit d'une interface basique, sans aucune particularité.

public interface MarinService {

   public long createMarin(String nom, String prenom, int salaire) ;
}

Le projet ejb-project est un projet différent, non pas dans sa structure, mais dans ses dépendances.

Il va contenir l'implémentation de notre interface, et manipuler des objets en base. Les classes de ce projet vont donc dépendre du modèle, mais aussi des classes JEE : annotations notamment. Eclipse nous propose une manière propre de créer ce genre de projet.

Lors de la création de ce projet, on choisit le type EJB.

Figure 21. Création d'un projet de type EJB

Le panneau qui suit nous permet de choisir le type de serveur qui va être utilisé pour exécuter ce projet. Il s'agit naturellement du serveur Glassfish que l'on vient de créer. L'un des intérêt est que toutes les librairies JEE sont mises automatiquement en dépendance du projet créé.

On précise de plus la version de nos EJB : ici version 3.0. Il existe aussi une version 3.1, qui est celle proposée par défaut.

Figure 22. Choix d'un serveur

Il ne reste plus qu'à ajouter les deux projets ejb-interface et jpa-project en dépendance de notre projet ejb-project.

Figure 23. Dépendances du projet ejb-project

On crée enfin une implémentation de l'interface MarinService, dans ce projet. Le code de la classe est le suivant.

@Stateless(mappedName="MarinService")
@Remote
public class MarinServiceImpl implements MarinService {

	@PersistenceContext
	private EntityManager em ;
	
	@Override
	public long createMarin(String nom, String prenom, int salaire) {
		
		Marin marin = new Marin(nom, prenom, salaire) ;
		em.persist(marin) ;
		
		return marin.getId() ;
	}

}

La structure du projet ejb-project est donc la suivante.

Figure 24. Structure du projet ejb-project

Un projet EAR est un projet qui agrège différents modules, de toute sorte. Un projet EAR peut contenir des EJB, des applications Web, des services Web, des services REST, des services de messagerie, et bien d'autres choses encore. Nous allons nous borner ici à une application très simple et très classique : un module JPA auquel on accède par un EJB façade. Cet EAR va donc être un assemblage de nos trois projets déjà créés.

Un projet EAR est un projet Eclipse d'un type particulier, comme montré sur la figure suivante.

Figure 25. Création d'un projet EAR - 1

Encore une fois, il faut fixer le type de serveur d'application dans lequel se projet va être déployé.

Figure 26. Création d'un projet EAR - 2

On sélectionne alors les projets qui vont être agrégés par cet EAR.

Figure 27. Création d'un projet EAR - 3

À l'issue de ces opérations, la structure de notre projet EAR est donc la suivante.

Figure 28. Structure du projet EAR

On remarquera que le projet EJB se trouve bien à la racine de cet EAR, et que tous les projets dont il dépend se trouvent dans le répertoire lib, ce qui est bien conforme à la spécification.

Notre projet projet-ear est appelé a être déployé dans Glassfish. C'est Glassfish qui va se charger de lui, et de le rendre disponible aux requêtes des projets clients.

Il existe plusieurs façons de déployer un projet EAR dans un serveur d'application sous Eclipse, la plus simple est probablement de glisser / déposer le projet dans la vue Servers, sur l'élément correspondant au serveur Glassfish, comme sur la figure suivante.

Figure 29. Déploiement par glisser / déposer

Si le serveur est déjà en marche, le projet va être déployé et disponible en quelques secondes. S'il n'est pas en marche, et qu'il ne démarre pas automatiquement (ce démarrage automatique est le comportement par défaut), alors il faut le lancer à la main.

Une fois déployé, notre serveur Glassfish a la structure suivante.

Figure 30. Structure d'un projet déployé sous Glassfish

Notre projet EAR, correctement déployé, est prêt à traiter les requêtes extérieures. Pour montrer ce point, nous n'avons plus qu'à écrire un client simple.

Un projet client est un projet Java normal, sans type spécial. Pour se connecter à Glassfish, il a juste besoin d'une dépendance vers un JAR de la distribution de Glassfish : gf-client.jar, qui se trouve dans $GLASSFISH_HOME/glassfish/lib. Attention toutefois, ce JAR ne contient quasiment rien, mais il référence de très nombreux JAR du répertoire $GLASSFISH_HOME/glassfish/modules. Si l'on copie juste ce fichier en le sortant de l'installation de Glassfish, les choses ne se passeront pas bien.

Notre projet client doit de plus référencer les projets contenant les interfaces de nos EJB, et le modèle objet. Il n'a pas besoin de référencer le projet contenant les implémentations de nos EJB.

Voici ses dépendances vers les autres projets.

Figure 31. Dépendances du projet client - 1

Et voici ces dépendances vers les JARs de Glassfish.

Figure 32. Dépendances du projet client - 2

Il ne nous reste plus qu'à écrire une classe Main afin d'accéder à nos EJB.

public class Main {

   public static void main(String[] args) {
		
		
   try {
			
      // création du "contexte initial" = de la connexion à l'annuaire du serveur
      InitialContext context = new InitialContext();

      // requête sur le nom de la ressource que l'on veut, ici notre EJB
      MarinService marinService = (MarinService)context.lookup("MarinService") ;

      // invocation d'une méthode
      long id = marinService.createMarin("Surcouf", "Robert", 5000) ;

      System.out.println("Id = " + id) ;
			
      } catch (NamingException e) {
         e.printStackTrace();
      }
   }
}

L'exécution de ce code nous affiche sur la console la clé primaire du marin créé, ce qui est le signe que l'écriture en base s'est bien effectuée.