Exposition des méthodes dans les services Web JAX-WS basés sur une interface SEI
Vous pouvez utiliser les annotations @WebService et @WebMethod sur une implémentation de noeud final de service pour définir les méthodes Java™ que vous voulez exposer comme API Java pour les services Web JAX-WS (XML-Based Web Services).
Avant de commencer
La technologie JAX-WS permet l'implémentation de services Web basés à la fois sur l'interface standard de noeud final de service et sur une interface fournisseur. Lors du développement d'un service Web JAX-WS à partir d'une classe Java existante, ce qui est un mode de développement connu sous le nom de développement ascendant, vous devez annoter la classe avec @WebService ou @WebServiceProvider pour la définir initialement comme un service web.
L'utilisation d'une interface fournisseur constitue le mode dynamique de définition des services JAX-WS. Pour utiliser l'interface fournisseur, la classe doit implémenter l'interface javax.xml.ws.Provider et contenir l'annotation @WebServiceProvider. L'interface fournisseur a une méthode, la méthode invoke, qui utilise des éléments génériques dans le langage de programmation Java pour contrôler les types d'entrée et de sortie lors d'une utilisation avec différents messages ou charges de message.
Par opposition, vous pouvez utiliser les annotations Java pour décrire les services web à l'aide de l'interface de noeud final de service (interface SEI).
Pourquoi et quand exécuter cette tâche
Pour définir initialement un service Web, annotez la classe Java avec l'annotation @WebService. Vous pouvez également annoter les méthodes individuelles de façon sélective avec l'annotation @WebMethod pour contrôler leur exposition en tant qu'opérations de service Web.
Pour éviter les ambiguïtés provoquées par la multiplicité des spécifications de service web définissant l'exposition des méthodes en tant qu'opérations, et garantir un comportement cohérent quelle que soit l'implémentation JAX-WS, suivez les recommandations ci-dessous.
- Pour définir un service Web de base, annotez la classe d'implémentation avec l'annotation @WebService.
- Pour définir des services Web en utilisant une interface SEI explicite, référencez de façon explicite une classe d'interface Java à l'aide de l'attribut endpointInterface de l'annotation @WebService.
- Entrez la référence à un fichier WSDL dans l'attribut wsdlLocation
de l'annotation @WebService. L'ajout d'un fichier WSDL prédéfini améliore les performances. En outre, les incohérences entre le fichier WSDL et les annotations vous sont
signalées par l'environnement d'exécution.
Eviter les incidents: Conformément à la spécification JAX-WS 2.2, si SOAP 1.2 est déclaré comme type de liaison et que l'attribut wsdlLocation correspond à une chaîne vide (valeur par défaut), le conteneur ne peut pas générer le fichier WSDL automatiquement. Par conséquent, si vous utilisez ?wsdl pour demander le fichier WSDL, le message d'exception suivant s'affiche :
Si vous souhaitez afficher le fichier WSDL, vous devez le générer manuellement, le placer dans l'application et définir l'attribut wsdlLocation avec l'emplacement correct.gotchaCWWKW0037E: The WSDL that is compliant with the JAX-WS 2.2 specification cannot be generated.
- Lorsque vous utilisez une interface SEI explicite, toutes les méthodes publiques de l'interface et des classe héritées sont toujours exposées. L'ajout d'annotations @WebMethod n'est nécessaire qu'en cas de personnalisation des méthodes déjà exposées.
- La saisie d'une référence dans l'annotation @WebService à une interface SEI explicite ou à un fichier WSDL existant permet l'élimination des ambiguïtés possibles lors de l'exposition des méthodes.
- Si vous n'utilisez pas d'interface SEI explicite, suivez les règles suivantes
pour garantir la cohérence de l'exposition des méthodes :
- Ajoutez une annotation @WebService à la classe d'implémentation et à toutes ses superclasses contenant les méthodes à exposer. L'ajout d'une annotation @WebService à une classe expose toutes les méthodes publiques de cette classe qui ne sont pas statiques ou finales.
- Pour obtenir un contrôle plus granulaire et n'exposer que certaines méthodes, utilisez l'annotation @WebMethod sur les méthodes sélectionnées. Pour garantir l'exposition d'une méthode, annotez-la avec @WebMethod. Pour garantir la non-exposition d'une méthode, annotez-la avec @WebMethod(exclude=true).

- Changement de comportement des méthodes d'exposition non annotées :
Le comportement JAX-WS relatif aux méthodes d'exposition en tant qu'opérations de services Web a changé. Il respecte désormais les clarifications récentes des spécifications JAX-WS.
Les applications sans SEI ou WSDL explicite qui sont migrées depuis des versions précédentes peuvent exposer des opérations supplémentaires, comme illustré ci-dessous. Vous pouvez définir une propriété de sorte que l'environnement d'exécution JAX-WS utilise le comportement existant. Cela peut être utile lors de la migration d'applications dans WSDL ou SEI afin que les méthodes supplémentaires ne soient pas exposées.
@WebService public class Foo { @WebMethod public void a() {} // exposed now, exposed before public void b() {} // exposed now, not exposed before }
Dans la nouvelle interprétation, des méthodes publiques d'une classe d'implémentation et ses superclasses ne sont exposées qu'aux conditions suivantes :- La classe parent contient une annotation @WebService.
- La méthode n'a pas d'annotation @WebMethod(exclude=true).
Dans l'interprétation existante, une méthode d'une classe d'implémentation et ses superclasses ne sont exposées qu'aux conditions suivantes :- La classe parent contient une annotation @WebService.
- L'annotation @WebMethod n'est pas appliquée à la méthode ET aucune autre méthode ne contient d'annotations @WebMethod.
- L'annotation @WebMethod ou @WebMethod(exclude=false) est appliquée à la méthode.
Pour indiquer que l'environnement d'exécution JAX-WS doit utiliser le comportement existant pour @WebMethod, configurez la propriété jaxws.runtime.legacyWebMethod=true. Cette propriété peut être configurée en tant que propriété système JVM (Java Virtual Machine) ou que propriété du fichier META-INF/MANIFEST.MF d'un fichier WAR. Par défaut, cette propriété est définie sur false et le serveur d'applications utilise le nouveau comportement.
Vous pouvez rencontrer un message d'erreur WSWS7054E si toutes les conditions suivantes sont vraies :- Votre application de service Web est composée de méthodes non annotées.
- Les méthodes ne sont pas destinées à être associée à une opération de service Web.
- Votre application ne référence pas de SEI et ne package pas de fichier WSDL.
Les outils JAX-WS sont conformes aux spécifications JAX-WS selon les principes de mappage @WebMethod. Cette modification peut affecter les applications ayant été dépendantes sur le comportement par défaut non conforme précédemment. Si vos applications packagent et référencent WSDL ou un SEI et ont TOUTES les méthodes annotées correctement avec l'indicateur d'exclusion @WebMethod dans l'implémentation SEI, puis cette modification ne vous affecte pas. Toutefois, si vous êtes affecté et que vous ajoutez des annotations explicites à vos méthodes pour vous assurer qu'elles sont exclues de la génération WSDL. Par exemple : @WebMethod(exclude=true) En outre, vous pouvez packager un WSDL avec votre application pour éliminer le besoin de génération d'un WDSL par l'exécution à votre place.javax.xml.ws.WebServiceException: WSWS7054E: The Web Services Description Language (WSDL) file could not be generated for the XXXX Web service implementation class because of the following error: javax.xml.ws.WebServiceException: Unable to create JAXBContext
- Changement de comportement des méthodes d'exposition statiques et finales :
Les méthodes statiques ou finales d'un service sans SEI explicite ne sont plus exposées comme opérations de service Web. Pour les exposer, conditionnez le WSDL avec l'application et définissez jaxws.runtime.legacyWebMethod=true.
Procédure
- Identifiez les méthodes à exposer en tant qu'opérations de service Web.
- Reportez-vous aux règles d'exposition des méthodes en tant qu'opérations dans les classes annotées par @WebService.
- Suivez les meilleures pratiques pour appliquer les annotations @WebMethod et @WebService dans les applications sans interface SEI pour exposer correctement les méthodes comme opérations dans les services Web.
Résultats
Vous avez utilisé l'annotation @WebMethod pour définir les méthodes à exposer en tant qu'opérations de service Web.

Si l'environnement de votre serveur d'applications a été mis à niveau et que vous rencontrez des problèmes, consultez les informations de traitement des incidents ci-après.
- Des erreurs client indiquent une incohérence entre le fichier WSDL et la propriété portType dans l'environnement des outils JAX-WS version 2.1.6 ou ultérieure
- Vous recevez un message d'erreur semblable à celui-ci en provenance du client :
javax.xml.ws.WebServiceException: The Endpoint validation failed to validate due to the following errors: :: Invalid Endpoint Interface :: :: The number of operations in the WSDL portType does not match the number of methods in the SEI or web service implementation class. wsdl operations = [...] dispatch operations = [....]
Pour corriger ce problème, régénérez les artefacts client pour qu'ils correspondent au fichier WSDL.
Pratiques recommandées: Pensez à régénérer les artefacts client à chaque modification du fichier WSDL. bprac
- Les clients ayant réalisé une opération ?WSDL sur les services Web reçoivent des opérations qui ne peuvent pas être réparties
- Après avoir exécuté une opération ?WSDL, vous recevez un fichier WSDL contenant plus d'opérations que l'environnement d'exécution JAX-WS ne peut en répartir. Si le client tente d'appeler l'une de ces opérations, il reçoit un message d'erreur de ce type :
The endpoint reference (EPR) for the Operation not found is http://localhost:9086/example/BeanImpl2Service and the WSA Action = <WSA_action_from_server>. If this EPR was previously reachable, contact the server administrator.
Les clients ne doivent accéder qu'aux opérations que le service Web a l'intention d'exposer. Choisissez l'une des solutions ci-dessous pour corriger ce problème :- Modifiez les annotations @WebMethod dans l'application de services Web, de sorte que le fichier WSDL résultant expose l'ensemble d'opérations approprié.
- Affectez à la propriété jaxws.runtime.legacyWebMethod la valeur false afin que toutes les opérations du WSDL soient distribuées.