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 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 :
    CWWKW0037E: The WSDL that is compliant with the JAX-WS 2.2 specification cannot be generated.
    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.gotcha
  • 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).
Configurations prises en charge Configurations prises en charge: sptcfg
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.
Le message d'erreur contient les informations similaires au texte suivant :
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
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.
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

  1. Identifiez les méthodes à exposer en tant qu'opérations de service Web.
  2. Reportez-vous aux règles d'exposition des méthodes en tant qu'opérations dans les classes annotées par @WebService.
  3. 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.

Eviter les incidents Eviter les incidents:

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 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.
gotcha

Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxws_exposewebmethod
Nom du fichier : twbs_devjaxws_exposewebmethod.html