Si vous disposez d'applications Enterprise JavaBeans (EJB)
qui sont exposées à l'aide d'une vue sans interface, vous pouvez exposer une interface RESTful au bean enterprise à l'aide de l'API JAX-RS (Java™ API for RESTful Web Services).
En implémentant des beans enterprise annotés, vous conservez les fonctionnalités des EJB, y compris la prise en charge des transactions, l'injection de composants et de ressources Java EE, ainsi que d'autres fonctions de bean session EJB.
Avant de commencer
Avant EJB 3.1, les beans enterprise nécessitant une vue client locale EJB avaient aussi besoin d'une interface Java séparée, généralement située dans un fichier distinct, qui déclarait les méthodes de vue locale.
Le bean enterprise spécifiait qu'il implémentait l'interface de vue locale EJB à l'aide de descripteurs de déploiement ou d'annotations EJB.
Grâce à la spécification EJB 3.1, vous avez la possibilité d'exposer une vue locale d'un bean enterprise sans interface locale EJB explicite.
En effet, le bean enterprise dispose d'une vue client sans interface basée sur les méthodes publiques de votre classe de bean. Il peut être plus simple de développer des beans enterprise de vue sans interface qu'un bean enterprise de vue locale pour les raisons suivantes :
- Les beans enterprise de vue sans interface ne nécessitent pas de déclaration d'interface Java distincte.
- Les beans enterprise de vue sans interface ne nécessitent pas la spécification de métadonnées supplémentaires dans le descripteur de déploiement ou lors de l'utilisation d'annotations EJB.
Consultez la spécification EJB 3.1 pour de plus amples informations sur les vues sans interface d'un bean enterprise.
JAX-RS prend en charge l'utilisation de beans enterprise déclarant une interface métier locale et des beans enterprise de vue sans interface.
Pratiques recommandées: Même si vous pouvez déclarer des beans enterprise de différentes manières, il est conseillé d'implémenter directement l'interface métier locale EJB et de toujours déclarer l'annotation @javax.ejb.Local. Avec cette méthode, le bean EJB doit implémenter l'interface métier locale, ce qui évite les erreurs de saisie de noms de méthode et de modifications de type d'argument.
En utilisant toujours l'annotation @javax.ejb.Local, dans le cas de plusieurs interfaces métier, il suffit d'ajouter l'interface métier à la valeur d'annotation. Vous pouvez également utiliser cette approche pour modifier le bean enterprise à l'aide d'un descripteur de déploiement.
bprac
Cette tâche décrit l'implémentation de vues RESTful
d'un bean enterprise de vue sans interface.
Pourquoi et quand exécuter cette tâche
Vous pouvez créer un bean enterprise simple avec des annotations JAX-RS.
Même si cette tâche explique spécifiquement comment implémenter des vues RESTful
d'un bean enterprise de vue sans interface, il est important de prendre en compte la totalité de la portée de votre architecture d'application et le mode d'exposition souhaité lors du choix du modèle de ressource et de l'identification des vues RESTful convenant à l'application des beans enterprise. Ces considérations n'entrent pas dans le périmètre de cette tâche.
JAX-RS prend en charge les beans session sans état et de type singleton.
Vous pouvez ajouter des annotations JAX-RS à l'interface locale d'un bean session. De plus, avec EJB 3.1, vous pouvez ajouter des annotations JAX-RS directement dans une classe EJB si un bean enterprise expose une vue sans interface.
Avec les règles de mise en forme EJB 3.1, vous pouvez ajouter des beans enterprise JAX-RS dans le fichier WAR (fichier d'archive d'application Web) directement dans le répertoire WEB-INF/classes
ou à l'aide d'un fichier JAR (fichier d'archive Java) dans le répertoire WEB-INF/lib. Vous pouvez déclarer un bean enterprise à l'aide d'annotation ou d'un descripteur de déploiement EJB, ou en utilisant à la fois des annotations et un descripteur de déploiement.
Les beans enterprise annotés JAX-RS dans un fichier autonome ou un fichier JAR d'EJB distinct non inclus dans un fichier EAR ne sont pas pris en charge.
Procédure
- Créez un bean enterprise. L'exemple suivant comprend une classe EJB simple appelée Organization.
Cette classe tire parti des avantages de la fonction de classe de vue sans interface introduite dans la spécification EJB 3.1.
public class Organization {
public String getInformation() {
// return information via a String
}
}
- Pour exposer un bean enterprise en tant que ressource JAX-RS, effectuez l'une des étapes suivantes :
- Dans le fichier descripteur de déploiement WEB-INF/ ejb-jar.xml pour votre bean enterprise, modifiez vos classes Java simples en beans enterprise JAX-RS. Par exemple, vous pouvez ajouter le fragment de code suivant au descripteur de déploiement
WEB-INF/ejb-jar.xml :
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" version="3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd">
<!--
This file must exist in the WEB-INF/ directory of your WAR file.
See EJB 3.1 spec 20.4 for more details.
-->
<enterprise-beans>
<session>
<ejb-name>Organization</ejb-name>
<ejb-class>com.example.jaxrs.Organization</ejb-class>
<session-type>Stateless</session-type>
</session>
</enterprise-beans>
</ejb-jar>
Si vous souhaitez que le bean enterprise soit un bean enterprise de type singleton utilisant le descripteur de déploiement, indiquez <session-type>Singleton</
session-type> au lieu de <session-type>Stateless</session-type>.
- Ajoutez une annotation @javax.ejb.Stateless à la classe Java de votre bean enterprise. L'exemple suivant illustre un bean enterprise annoté JAX-RS simple :
package com.example.jaxrs;
@javax.ejb.Stateless
@javax.ws.rs.Path("/organization/")
public class Organization {
@javax.ws.rs.GET
@javax.ws.rs.Produces("text/plain")
public String getInformation() {
// return information via a String
}
}
Si vous souhaitez que le bean enterprise soit un bean enterprise de type singleton utilisant des annotations, indiquez l'annotation EJB 3.1 @javax.ejb.Singleton au lieu de l'annotation @javax.ejb.Stateless.
- Ajoutez des annotations JAX-RS aux méthodes que vous souhaitez exposer comme interface RESTful pour le bean enterprise. L'exemple suivant illustre l'ajout d'annotations JAX-RS au bean enterprise @javax.ejb.Stateless.
package com.example.jaxrs;
@javax.ejb.Stateless
@javax.ws.rs.Path("/organization/")
public class Organization {
@javax.ws.rs.GET
@javax.ws.rs.Produces("text/plain")
public String getInformation() {
// return information via a String
}
}
- (Facultatif) Ajoutez des zones et des propriétés de ressource Java EE annotées @javax.annotation.Resource à vos classes EJB JAX-RS pour accéder facilement aux ressources de votre application. Les injections Java EE ne fonctionnent pas dans des classes
Java simples avec des annotations
JAX-RS. L'injection de zones et de propriétés de ressource Java EE annotées @javax.annotation.Resource dans vos classes EJB JAX-RS fonctionne uniquement si vos classes annotées JAX-RS sont de type bean enterprise ou bean géré JDCI (Context
and Dependency Injection) Java (JSR-299). Par exemple :
@javax.ejb.Stateless
@javax.ws.rs.Path("/organization/")
public class Organization {
@javax.annotation.Resource(name="jdcb/TestDataSource")
private javax.sql.DataSource datasource;
@javax.ws.rs.GET
@javax.ws.rs.Produces("text/plain")
public String getInformation() {
// read from the datasource
// return information via a String
}
}
Dans cet exemple, si une source de données est correctement configurée avec le nom JNDI approprié, un objet DataSource est injecté dans la classe de ressources.
- (Facultatif) Utilisez l'injection @javax.ws.rs.core.Context JAX-RS pour accéder aux informations sur la demande. Vous pouvez ajouter une zone
@javax.ws.rs.core.Context UriInfo à votre classe EJB JAX-RS pour accéder aux informations sur l'URI de la demande. Par exemple :
@javax.ejb.Stateless
@javax.ws.rs.Path("/organization/")
public class Organization {
@javax.ws.rs.core.Context
private UriInfo uriInfo;
@javax.ws.rs.GET
@javax.ws.rs.Produces("text/plain")
public String getInformation() {
// return information via a String
}
}
Pour lire les paramètres de la demande, comme
@javax.ws.rs.HeaderParam, @javax.ws.rs.QueryParam et @javax.ws.rs.PathParam,
ajoutez un paramètre à votre méthode de ressource. Par exemple :
@javax.ejb.Stateless
@javax.ws.rs.Path("/organization/")
public class Organization {
@javax.ws.rs.GET
@javax.ws.rs.Produces("text/plain")
public String getInformation(@javax.ws.rs.QueryParam("page") String page) {
/* The QueryParam in the method parameter list will be set correctly. */
// Return information using a String
}
/* The following field will not be set. */
@javax.ws.rs.QueryParam("q")
private String willNotWork;
@javax.ws.rs.QueryParam("q")
public void setMyQueryParam(String q) {
/* This property will not be set. */
}
}
Configurations prises en charge: L'injection de paramètre de propriété et de zone JAX-RS, tel que @javax.ws.rs.QueryParam, n'est pas pris en charge.
sptcfg
- Ajoutez la classe EJB au répertoire WEB-INF/classes de votre fichier WAR ou dans un fichier JAR situé dans votre répertoire WEB-INF/lib. Lorsqu'un client effectue une demande sur un bean enterprise annoté JAX-RS, l'environnement d'exécution JAX-RS recherche et utilise une instance EJB de la classe pour appeler la méthode de ressource.
Résultats
Vous avez activé un bean enterprise existant avec une vue sans interface pour exposer les ressources JAX-RS pour consommation.