Annotations JAX-WS
JAX-WS (Java™ API for XML-Based Web Services) s'appuie sur l'utilisation des annotations pour spécifier les métadonnées associées aux implémentations de services Web et pour simplifier le développement de services Web. Les annotations décrivent la façon dont une implémentation de service côté serveur est accessible sous la forme d'un service Web ou comment une classe Java côté client accède aux services Web.
La norme de programmation JAX-WS introduit le support d'annotation de classes Java à l'aide des métadonnées permettant de définir une application de noeud final de service sous la forme d'un service Web, ainsi que le mode d'accès au service Web par un client. JAX-WS prend en charge l'utilisation des annotations basées sur Metadata Facility pour la spécification Java Programming Language (Java Specification Request (JSR) 175), Web Services Metadata pour la spécification Java Platform (JSR 181) et les annotations définies par la spécification JAX-WS version 2.0 ou ultérieure (JSR 224) qui inclut des annotations JAXB. En utilisant des annotations de la norme JSR 181, vous pouvez simplement annoter la classe d'implémentation de service ou l'interface de service pour que l'application soit activée sous la forme d'un service Web. L'utilisation d'annotations dans la source Java simplifie le développement et le déploiement de services Web via la définition de quelques-unes des informations supplémentaires qui sont généralement extraites des fichiers descripteurs de déploiement, des fichiers WSDL ou du mappage de métadonnées des fichiers XML et WSDL vers les artefacts source.
Utilisez les annotations pour configurer des liaisons, des chaînes de gestionnaires, des noms définis de type de port (portType), de service et d'autres paramètres WSDL. Les annotations sont utilisées dans le cadre du mappage de Java vers WSDL et les schémas, ainsi qu'au moment de l'exécution pour contrôler la façon dont le module d'exécution JAX-WS traite les appels de service Web et répond à ces derniers.
Pour les services Web JAX-WS, l'utilisation du descripteur de déploiement webservices.xml est facultatif car vous pouvez utiliser des annotations pour spécifier toutes les informations contenues dans le fichier de descripteur de déploiement. Vous pouvez utiliser ce fichier pour augmenter ou remplacer des annotations JAX-WS existantes. Toutes les informations que vous définissez dans le descripteur de déploiement webservices.xml remplacent les informations correspondantes spécifiées par les annotations.
A partir de WebSphere Application Server versions 7.0 et ultérieures, les modules d'application Java EE 5 (modules d'application Web version 2.5 ou ultérieure, ou modules EJB modules version 3.0 ou ultérieure) font l'objet d'une recherche d'annotations pour identifier les clients et les services JAX-WS. En revanche, les modules d'application antérieurs à Java EE 5 (modules d'application Web versions 2.4 ou antérieures, ou modules EJB versions 2.1 ou antérieures) ne font pas l'objet de cette recherche d'annotations JAX-WS par défaut, pour des raisons liées aux performances.
- Vous pouvez définir la valeur true pour la propriété UseWSFEP61ScanPolicy dans l'élément META-INF/MANIFEST.MF d'un fichier WAR ou d'un module EJB. Par
exemple :
Lorsque la valeur de cette propriété est true dans le fichier META-INF/MANIFEST.MF du module, les annotations JAX-WS sont recherchées dans ce dernier quelle que soit la version Java EE du module. La valeur par défaut est false et si elle est effective, les annotations JAX-WS ne sont prises en charge que dans des modules dont la version est Java EE 5 ou ultérieure.Manifest-Version: 1.0 UseWSFEP61ScanPolicy: true
- Vous pouvez définir la propriété personnalisée com.ibm.websphere.webservices.UseWSFEP61ScanPolicy de la machine virtuelle Java (JVM) à l'aide de la console d'administration. Reportez-vous à la documentation relative aux propriétés personnalisées de la JVM pour connaître le chemin de navigation correct à utiliser. Pour demander la recherche d'annotations dans tous les modules quels que soient leur version Java EE, attribuez la valeur true à la propriété personnalisée com.ibm.websphere.webservices.UseWSFEP61ScanPolicy. Vous devez modifier la définition sur chaque serveur requérant une modification du comportement par défaut.
![[z/OS]](../images/ngzos.gif)


- types, comme une classe Java, énumération ou interface
- méthodes
- zones représentant des variables d'instance locales dans une classe Java
- paramètres dans une méthode Java
Classe d'annotation | Annotation | Propriétés |
---|---|---|
javax.jws. WebService | L'annotation @WebService marque une classe Java comme implémentant un service Web ou marque une interface SEI (Service Endpoint Interface) comme implémentant une interface de service Web. Important :
|
|
javax.jws. WebMethod | L'annotation @WebMethod indique une méthode correspondant à une opération de service Web. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.jws. Oneway | L'annotation @Oneway dénote une méthode sous la forme d'une opération unidirectionnelle de service Web qui ne comporte qu'un message d'entrée et aucun message de sortie. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.jws. WebParam | L'annotation @WebParam personnalise le mappage d'un paramètre individuel vers un élément XML ou une partie de message de service Web. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.jws. WebResult | L'annotation @WebResult personnalise le mappage d'une valeur de retour vers une partie WSDL ou un élément XML. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.jws. HandlerChain | L'annotation @HandlerChain associe le service Web à une chaîne de gestionnaires définie en externe. Vous ne pouvez configurer le gestionnaire côté serveur qu'à l'aide de l'annotation @HandlerChain sur l'interface SEI (Service Endpoint Interface) ou la classe d'implémentation de noeud final de serveur. Utilisez une des nombreuses méthodes permettant de configurer un gestionnaire côté client. Vous pouvez configurer le gestionnaire côté client à l'aide de l'annotation @HandlerChain sur la classe de service générée ou l'interface SEI. En outre, vous pouvez à l'aide d'un programme enregistrer votre propre implémentation de l'interface HandlerResolver sur le service ou définir la chaîne de gestionnaires sur l'objet Binding. |
|
javax.jws. SOAPBinding | L'annotation @SOAPBinding indique le mappage du service Web vers le protocole de message SOAP. Appliquez cette annotation à un type ou aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. L'annotation de niveau méthode est limitée quant à l'élément qu'elle peut spécifier et n'est utilisée que si la propriété style est DOCUMENT. Si l'annotation de niveau méthode n'est pas spécifiée, le comportement @SOAPBinding du type est utilisé. |
|
Classe d'annotation | Annotation | Propriétés |
---|---|---|
javax.xml.ws. Action | L'annotation @Action spécifie l'action WS-Addressing qui est associée à une opération de service Web. Lorsque vous utilisez cette annotation avec une méthode particulière, et générez le document WSDL correspondant, l'attribut de l'extension WS-Addressing Action est ajouté aux éléments d'entrée et de sortie de l'opération WSDL qui correspond à cette méthode. Pour ajouter cet attribut à l'opération WSDL, vous devez également spécifier l'annotation @Addressing sur la classe d'implémentation de noeud final de serveur. Si vous ne voulez pas utiliser l'annotation @Addressing, vous pouvez fournir votre propre document WSDL avec l'attribut Action déjà défini. |
|
javax.xml.ws. BindingType | L'annotation @BindingType indique la liaison à utiliser lors de la publication d'un point de contact de ce type. Appliquez cette annotation à une classe d'implémentation de noeud final de serveur. Important : Vous pouvez utiliser l'annotation @BindingType sur la classe d'implémentation de point de contact JavaBeans pour activer MTOM, en spécifiant la valeur javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING ou javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING pour l'annotation.
|
|
javax.xml.ws. FaultAction | L'annotation @FaultAction spécifie l'action WS-Addressing qui est ajoutée à une réponse d'erreur. Cette annotation doit être placée dans une annotation @Action. Si vous utilisez cette annotation avec une méthode particulière, l'attribut de l'extension WS-Addressing FaultAction est ajouté à l'élément fault de l'opération WSDL qui correspond à cette méthode. Pour ajouter cet attribut à l'opération WSDL, vous devez également spécifier l'annotation @Addressing sur la classe d'implémentation de noeud final de serveur. Si vous ne voulez pas utiliser l'annotation @Addressing, vous pouvez fournir votre propre document WSDL avec l'attribut Action déjà défini. |
|
javax.xml.ws. RequestWrapper | L'annotation @RequestWrapper fournit le bean d'encapsulation de demande généré JAXB, le nom d'élément et l'espace de nom pour la sérialisation et la désérialisation, à l'aide du bean d'encapsulation de demande utilisé au moment de l'exécution. Lors du démarrage à l'aide d'un objet Java, cet élément sert à résoudre les conflits de surcharge en mode document/literal. Seul l'attribut className est requis dans ce cas. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.xml.ws. ResponseWrapper | L'annotation @ResponseWrapper fournit le bean d'encapsulation de réponse généré JAXB, le nom d'élément et l'espace de nom pour la sérialisation et la désérialisation, à l'aide du bean d'encapsulation de réponse utilisé au moment de l'exécution. Lors du démarrage à l'aide d'un objet Java, cet élément sert à résoudre les conflits de surcharge en mode document/literal. Seul l'attribut className est requis dans ce cas. Appliquez cette annotation aux méthodes d'une interface SEI (Service Endpoint Interface) client ou serveur ou d'une classe d'implémentation de noeud final de serveur. |
|
javax.xml.ws. RespectBinding | L'annotation @RespectBinding indique si l'implémentation JAX-WS doit utiliser le contenu de l'élément wsdl:binding pour un noeud final. Si cette annotation est spécifiée, un contrôle est effectué pour s'assurer que tous les éléments d'extensibilité WSDL requis avec l'attribut activé avec la valeur true sont pris en charge. Appliquez cette annotation aux méthodes sur une classe d'implémentation de noeud final de serveur. |
|
javax.xml.ws. ServiceMode | L'annotation @ServiceMode indique si un fournisseur de service doit avoir accès à la totalité d'un message de protocole ou uniquement à la charge utile du message. Important : L'annotation @ServiceMode n'est prise en charge que sur les classes annotées à l'aide de @WebServiceProvider.
|
|
javax.xml.ws. soap.Addressing | L'annotation @Addressing indique que ce service veut activer la prise en charge WS-Addressing. Appliquez cette annotation aux méthodes sur une classe d'implémentation de noeud final de serveur. |
|
javax.xml.ws. soap.MTOM | L'annotation @MTOM indique si un contenu binaire dans le corps d'un message SOAP est envoyé à l'aide de MTOM. Appliquez cette annotation à une classe d'implémentation de noeud final de service. |
|
javax.xml.ws. WebFault | L'annotation @WebFault mappe les erreurs WSDL vers les exceptions Java. Elle sert à enregistrer le nom de l'erreur pendant la sérialisation du type JAXB qui est généré à partir d'un élément global référencé par un message d'erreur WSDL. Elle permet également de personnaliser le mappage des exceptions spécifiques à un service vers des incidents WSDL. Cette annotation ne peut être appliquée qu'à une classe d'implémentation d'erreur sur le client ou le serveur. |
|
javax.xml.ws. WebServiceProvider | L'annotation @WebServiceProvider indique qu'une classe satisfait les exigences d'une classe d'implémentation de fournisseur
JAX-WS. Important :
|
|
javax.xml.ws. WebServiceRef | L'annotation @WebServiceRef définit une référence à un service
Web appelé par le client. Remarque :
|
|
javax.xml.ws. WebServiceRefs | L'annotation @WebServiceRefs associe plusieurs annotations @WebServiceRef avec une classe spécifique. Remarque : L'annotation @WebServiceRef est prise en charge uniquement dans certains types de classe, des classes d'implémentation de noeud final JAX-WS, des classes de gestionnaire JAX-WS, des classe Enterprise JavaBeans et des classes de servlet, par exemple. Cette annotation est prise en charge dans les mêmes types de classe que l'annotation @Resource. Pour la liste complète des types de classe pris en charge, voir la spécification Java EE (Java Platform, Enterprise Edition) 5.
|
|
Classe d'annotation | Annotation | Propriétés |
---|---|---|
javax.annotation. Resource | L'annotation @Resource marque une ressource WebServiceContext requise par l'application. Remarque :
L'application de cette annotation sur une zone de type WebServiceContext sur la classe d'implémentation de noeud final de serveur pour un noeud final JavaBeans ou un noeud final de fournisseur entraîne le conteneur à injecter une instance de WebServiceContext dans la zone spécifiée. Lorsque cette annotation est utilisée à la place de l'annotation @WebServiceRef, les règles décrites pour l'annotation @WebServiceRef s'appliquent. |
|
javax.annotation. Resources | L'annotation @Resources associe plusieurs annotations @Resource à une classe spécifique et sert de conteneur pour de nombreuses déclarations de ressources. |
|
javax.annotation. PostConstruct | L'annotation @PostConstruct marque une méthode qui doit s'exécuter une fois l'injection de dépendance effectuée sur la classe. Appliquez cette annotation sur un gestionnaire d'applications JAX-WS ou une classe d'implémentation de noeud final de serveur. |
|
javax.annotation. PreDestroy | L'annotation @PreDestroy marque une méthode qui doit s'exécuter lorsque l'instance est en cours de suppression par le conteneur. Appliquez cette annotation sur un gestionnaire d'applications JAX-WS ou une classe d'implémentation de noeud final de serveur. |
|
Classe d'annotation | Annotation | Propriétés |
---|---|---|
com.ibm.websphere. wsaddressing. jaxws21. SubmissionAddressing | L'annotation @SubmissionAddressing indique que ce service souhaite activer la prise en charge de WS-Addressing pour la spécification WS-Addressing 2004/08. Cette annotation fait partie de l'implémentation IBM de la spécification JAX-WS 2.1. Appliquez cette annotation aux méthodes sur une classe d'implémentation de noeud final de serveur. |
|