Exposición de métodos en servicios web JAX-WS basados en SEI

Puede utilizar las anotaciones @WebService y @WebMethod en una implementación de punto final de servicio para especificar los métodos Java™ que desee exponer como servicios web JAX-WS (API de Java para servicios web basados en XML).

Antes de empezar

La tecnología JAX-WS permite la implementación de servicios web basados en la interfaz estándar de punto final de servicio y en una interfaz de proveedor. Cuando desarrolle un servicio web JAX-WS a partir de clases Java existentes, lo que se conoce como el método ascendente, debe anotar la clase con la anotación @WebService o @WebServiceProvider para definir inicialmente la clase como un servicio web.

El uso de la interfaz de proveedor es el enfoque dinámico para la definición de los servicios JAX-WS. Para utilizar la interfaz de proveedor, la clase debe implementar la interfaz javax.xml.ws.Provider y contener la anotación @WebServiceProvider. La interfaz de proveedor tiene un método, el método invoke, que utiliza genéricos en el lenguaje de programación Java para controlar los tipos de entrada y salida cuando trabajo con varios mensajes o varios datos de carga de mensaje.

En cambio, puede utilizar anotaciones Java para describir los servicios web mediante la interfaz de punto final de servicio (método SEI).

Acerca de esta tarea

Para definir inicialmente un servicio web, anote la clase Java con la anotación @WebService. También se pueden anotar selectivamente métodos individuales con la anotación @WebMethod para controlar su exposición como operaciones de servicios web.

Debido a las ambigüedades entre varias especificaciones de servicios web sobre cómo se exponen los métodos como operaciones, utilice las directrices siguientes para que le ayuden a garantizar un comportamiento coherente independientemente de la implementación de JAX-WS que utilice.

  • Para definir un servicio web básico, anote la clase de implementación con la anotación @WebService.
  • Para definir los servicios web mediante una SEI explícita, haga referencia explícitamente a una clase de interfaz Java utilizando el atributo endpointInterface de la anotación @WebService.
  • Proporcione una referencia a un archivo WSDL en el atributo wsdlLocation de la anotación @WebService. Si se especifica un archivo WSDL predefinido, se mejora el rendimiento. Asimismo, el entorno de ejecución informa de las discrepancias entre el archivo WSDL y las anotaciones.
    Avoid trouble Avoid trouble: De acuerdo con la especificación JAX-WS 2.2, si SOAP 1.2 está declarado como tipo de enlace y el atributo wsdlLocation es una cadena vacía, que es el valor predeterminado, el contenedor no puede generar el WSDL automáticamente. Por lo tanto, si utiliza ?wsdl para solicitar el archivo WSDL, se muestra el mensaje de excepción siguiente:
    CWWKW0037E: El WSDL que es compatible con la especificación
    JAX-WS 2.2 no se puede generar.
    Si desea visualizar el archivo WSDL, debe generar manualmente el archivo WSDL, colocarlo en la aplicación y especificar el atributo wsdlLocation con la ubicación correcta.gotcha
  • Cuando se utiliza una SEI explícita, todos los métodos públicos de la SEI y las clases heredadas siempre se exponen. Sólo es necesario añadir anotaciones @WebMethod si desea personalizar más los métodos que ya están expuestos.
  • Proporcionar una referencia en la anotación @WebService a una SEI explícita o a un archivo WSDL existente ayuda a eliminar posibles ambigüedades cuando se exponen métodos.
  • Si no utiliza una SEI explícita, siga estas reglas para asegurarse de que los métodos se exponen coherentemente:
    • Añada una anotación @WebService a la clase de implementación y todas sus superclases que contengan métodos que desee exponer. Al añadir una anotación @WebService a una clase se exponen todos los métodos públicos de dicha clase que no son estáticos o finales.
    • Si desea un control más granular para exponer sólo determinados métodos, utilice la anotación @WebMethod en los métodos seleccionados. Para garantizar que dicho método se exponga, anótelo con la anotación @WebMethod. Si desea asegurarse de que un método no se exponga, anótelo con la anotación @WebMethod(exclude=true).
Supported configurations Supported configurations: sptcfg
Cambio en el comportamiento de la exposición de métodos que no están anotados:

El comportamiento de JAX-WS ha cambiado en la exposición de métodos como operaciones de servicios web. Esto cumple las recientes aclaraciones de las especificaciones JAX-WS.

Las aplicaciones sin una SEI explícita o WSDL que se migran de versiones anteriores podrían tener operaciones adicionales expuestas como se muestra a continuación. Puede establecer una propiedad de forma que el entorno de ejecución de JAX-WS utilice el comportamiento anterior. Esto será necesario cuando migre aplicaciones sin un WSDL o una SEI, para que los métodos adicionales no se expongan.

@WebService
public class Foo {
	@WebMethod
	public void a() {}	// expuesto ahora, expuesto antes
	public void b() {}	// expuesto ahora, no expuesto antes
}
Utilizando la nueva interpretación, los métodos públicos de una clase de implementación y sus superclases sólo se exponen en las condiciones siguientes:
  • La clase que contiene tiene una anotación @WebService.
  • El método no tiene una anotación @WebMethod(exclude=true).
Utilizando la interpretación heredada, un método de una clase de implementación y sus superclases sólo se exponen en las condiciones siguientes:
  • La clase que contiene tiene una anotación @WebService.
  • El método no tiene ninguna anotación @WebMethod Y ningún otro método tiene anotaciones @WebMethod.
  • El método tiene una anotación @WebMethod o @WebMethod(exclude=false).

Para especificar que el entorno de ejecución de JAX-WS debe utilizar el comportamiento heredado de @WebMethod, configure la propiedad jaxws.runtime.legacyWebMethod=true. Puede configurar esta propiedad como una propiedad del sistema de máquina virtual Java (JVM) o como una propiedad en el archivo META-INF/MANIFEST.MF de un archivo WAR (archivador de aplicación web). De forma predeterminada, esta propiedad se establece en false y el servidor de aplicaciones utiliza el nuevo comportamiento.

Puede producirse un mensaje de error WSWS7054E si se cumplen todas las condiciones siguientes:
  • La aplicación de servicio web consta de métodos no anotados.
  • Los métodos no están diseñados para ser correlacionados con una operación de servicio web.
  • La aplicación no hace referencia a una SEI ni empaqueta un archivo WSDL.
El mensaje de error contiene información que es similar al texto siguiente:
javax.xml.ws.WebServiceException: WSWS7054E:
 El archivo SDL (Web Services Description Language) no se ha podido generar para la clase de imlementación de servicio web XXXX  debido al error siguiente: javax.xml.ws.WebServiceException: No se ha podido crear JAXBContext
Las herramientas JAX-WS cumplen la especificación JAX-WS con respecto a los principios de correlación @WebMethod. Este cambio puede afectar a las aplicaciones que han sido dependientes del comportamiento predeterminado anteriormente no compatible. Si las aplicaciones están empaquetadas y hacen referencia a WSDL o a una SEI y tienen TODOS los métodos anotados correctamente con el distintivo exclude de @WebMethod en la implementación SEI, este cambio no le afectará. Sin embargo, si le afecta, añada anotaciones explícitas a los métodos para asegurarse de que están excluidos en la generación de WSDL. Por ejemplo: @WebMethod(exclude=true) Además, puede empaquetar un WSDL con la aplicación para eliminar la necesidad de que el tiempo de ejecución genere un WSDL en su nombre.
Cambio en el comportamiento de la exposición de métodos estáticos y finales:

Los métodos estáticos o finales de un servicio sin una SEI explícita ya no se exponen como operaciones de servicios web. Para exponerlos, empaquete el WSDL con la aplicación y establezca jaxws.runtime.legacyWebMethod=true.

Procedimiento

  1. Identifique los métodos que desea exponer como operaciones de servicios web.
  2. Revise las reglas para exponer métodos como operaciones en clases anotadas con la anotación @WebService.
  3. Utilice los procedimientos recomendados para aplicar las anotaciones @WebMethod y @WebService en las aplicaciones sin SEI para exponer correctamente los métodos como operaciones dentro de los servicios web.

Resultados

Ha utilizado la anotación @WebMethod para especificar los métodos que se exponen como operaciones de servicios web.

Avoid trouble Avoid trouble:

Si ha actualizado el entorno del servidor de aplicaciones y tiene problemas, revise la información de resolución de siguiente.

Los errores de cliente indican una discrepancia entre el archivo WSDL y portType cuando se utiliza un entorno de herramientas de JAX-WS versión 2.1.6 o posteriores
Es posible que reciba un mensaje de error del lado del cliente como el siguiente:
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 = [....]

Para corregir este problema, debe volver a generar los artefactos de cliente de modo que coincidan con el archivo WSDL.

Best practice Best practice: Asegúrese de volver a generar los artefactos del lado del cliente siempre que reciba un archivo WSDL actualizado. bprac
Los clientes que realizan una operación ?WSDL en servicios web tienen operaciones no asignables
Después de realizar una operación ?WSDL, es posible que reciba un archivo WSDL que contenga más operaciones de las que el entorno de ejecución de JAX-WS puede asignar. Si el cliente intenta invocar cualquiera de las operaciones no asignables, el cliente recibe un error con el mensaje siguiente:
La referencia de punto final (EPR) para la operación que no se ha encontrado es http://localhost:9086/example/BeanImpl2Service y la 
acción de WSA = <acción_WSA_servidor_origen. Si anteriormente se podía localizar esta EPR, póngase en contacto con el administrador del servidor. 
Los clientes sólo deben acceder a las operaciones que el servicio web tiene previsto exponer. Puede corregir este problema mediante uno de los modos siguientes:
  • Modifique las anotaciones @WebMethod en la aplicación de servicios web para que el archivo WSDL resultante exponga el conjunto correcto de operaciones.
  • Establecer la propiedad jaxws.runtime.legacyWebMethod en false para garantizar que se asignen todas las operaciones en el WSDL.
gotcha

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxws_exposewebmethod
File name: twbs_devjaxws_exposewebmethod.html