Personnalisation de modèles d'URL dans le fichier web.xml pour des applications JAX-WS
Le fichier web.xml contient des informations sur la structure et les dépendances externes de composants Web dans le module ; il décrit aussi comment les composants sont utilisés lors de l'exécution. Pour les applications JAX-WS (Java™ API for XML-Based Web Services), vous pouvez personnaliser le modèle d'URL dans le fichier web.xml.
Avant de commencer
Pourquoi et quand exécuter cette tâche
- Un fichier WEB-INF/web.xml comportant les informations de configuration et de déploiement pour les composants Web d'une application Web
- Des classes annotées implémentant les services Web qui figurent dans le module d'application, dont la classe d'implémentation du noeud final de service
- Des classes JAXB
- (Facultatif) Des documents Web Services Description Language (WSDL) décrivant les services Web à l'intérieur du module d'application
- (Facultatif) Un fichier schéma XML
- (Facultatif) Des classes utilitaires
- (Facultatif) Des clients de services Web
Le modèle d'URL par défaut est défini par l'attribut @WebService.serviceName figurant dans votre classe d'implémentation de services Web. Lorsque le fichier WSDL associé à votre classe d'implémentation de service inclut une définition de port unique, vous pouvez choisir d'utiliser le modèle d'URL par défaut ou vous pouvez personnaliser le modèle d'URL dans le fichier web.xml. Lorsque le fichier WSDL associé à votre classe d'implémentation de service contient plusieurs définitions de port dans la même définition de service, des modèles d'URL personnalisés sont obligatoires. Si vous utilisez le modèle d'URL par défaut lorsque la classe d'implémentation de service contient plusieurs définitions de port, plusieurs classes d'implémentation de service sont mappées sur le même modèle d'URL, ce qui entraîne une erreur. Vous devez alors modifier le fichier web.xml et personnaliser les modèles d'URL pour chaque définition de service. Chaque port est mappé sur une classe d'implémentation de service Web et son modèle d'URL personnalisé. En personnalisant le modèle d'URL dans le fichier web.xml, vous corrigez les définitions de modèle d'URL supposant un conflit.
Si votre application JAX-WS est configurée dans un fichier JAR (Java Archive) d'EJB (Enterprise JavaBeans) à l'intérieur d'un fichier EAR (Enterprise Archive), vous pouvez personnaliser les modèles d'URL à l'aide de la commande endptEnabler.
Procédure
- Déterminez si des modèles d'URL personnalisés sont nécessaires ou souhaités. Des modèles d'URL personnalisés sont nécessaires uniquement si le fichier WSDL du service Web JAX-WS contient plusieurs définitions de port dans un service unique. Dans le cas contraire, la définition de modèles d'URL est facultative.
- Pour personnaliser le modèle d'URL pour une classe d'implémentation de service, modifiez le fichier web.xml et indiquez un <servlet> ainsi que l'entrée <servlet-mapping> correspondante pour chaque classe d'implémentation de service Web JAX-WS nécessitant un modèle d'URL personnalisé. Vous devez définir la valeur <url-pattern> dans l'entrée <servlet-mapping>.
Résultats
Définition de port WSDL unique dans une classe d'implémentation de service
L'exemple suivant illustre le modèle d'URL par défaut et comment le personnaliser lorsque le fichier WSDL associé à la classe d'implémentation de service possède une seule définition de port.
Il s'agit d'un extrait d'un exemple de classe d'implémentation de service Web.
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP11EchoServicePort")
public class EchoServiceSOAP11{
Il s'agit d'un extrait du fichier WSDL associé à la classe d'implémentation de service Web EchoServiceSOAP11 :
<wsdl:service name="EchoService">
<wsdl:port name="SOAP11EchoServicePort" tns:binding="..." >
...
</wsdl:port>
</wsdl:service>
Comme requis par JSR-109, le modèle d'URL par défaut dans
cet exemple est construit avec l'attribut @WebService.serviceName
et le modèle d'URL par défaut est /EchoService.Pour personnaliser éventuellement le modèle d'URL dans cet exemple, modifiez le fichier web.xml et indiquez l'entrée url-pattern. Dans cet exemple, le modèle d'URL personnalisé est /EchoServiceSOAP11.
L'extrait suivant provient d'un exemple de fichier web.xml illustrant la configuration d'un servlet :
<servlet id="...">
<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
<servlet-class>com.ibm.test.EchoServiceSOAP11</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
<url-pattern>/EchoServiceSOAP11</url-pattern> ----> Defining the URL pattern and
pointing it to the service implementation class.
</servlet-mapping>
L'exemple suivant illustre les personnalisations obligatoires du modèle d'URL lorsque le fichier WSDL associé à la classe d'implémentation de service possède plusieurs définitions de port.
L'extrait suivant provient d'un exemple de classe d'implémentation de service Web :
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP11EchoServicePort")
public class EchoServiceSOAP11{
...
}
package com.ibm.test;
@WebService(serviceName="EchoService", portName="SOAP12EchoServicePort")
public class EchoServiceSOAP12{
...
}
L'extrait suivant provient du fichier WSDL associé à la classe d'implémentation de service Web EchoServiceSOAP11. Chaque port dans le fichier WSDL est mappé sur un nom de port dans la classe d'implémentation de service Web.
<wsdl:service name="EchoService">
<wsdl:port name="SOAP11EchoServicePort" tns:binding="..." >
...
</wsdl:port>
<wsdl:port name="SOAP12EchoServicePort" tns:binding="..." >
...
</wsdl:port>
</wsdl:service>
Dans ce scénario, sachant que le fichier WSDL contient plusieurs définitions de port, vous devez personnaliser le modèle d'URL en modifiant le fichier web.xml. Indiquez des modèles d'URL personnalisés pour chaque service.
L'extrait suivant provient d'un exemple de fichier web.xml illustrant la configuration d'un servlet :
<servlet id="...">
<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
<servlet-class>com.ibm.test.EchoServiceSOAP11</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>com.ibm.test.EchoServiceSOAP11</servlet-name>
<url-pattern>/EchoServiceSOAP11</url-pattern>
</servlet-mapping>
<servlet id="...">
<servlet-name>com.ibm.test.EchoServiceSOAP12</servlet-name>
<servlet-class>com.ibm.test.EchoServiceSOAP12</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>com.ibm.test.EchoServiceSOAP12</servlet-name>
<url-pattern>/EchoServiceSOAP12</url-pattern>
</servlet-mapping>