Correlación entre el lenguaje Java, WSDL y XML para aplicaciones JAX-RPC
Los datos para las aplicaciones JAX-RPC (Java™ API for XML-based Remote Procedure Call) fluyen como XML (Extensible Markup Language). Las aplicaciones JAX-RPC utilizan correlaciones para describir la conversión de datos entre tecnologías de lenguaje Java y XML (Extensible Markup Language), entre las que se incluyen XML Schema, WDSL (Web Services Description Language) y SOAP, que admite el servidor de aplicaciones.
Para las aplicaciones JAX-RPC, la mayor parte de las correlaciones entre el lenguaje Java y XML se especifican mediante la especificación JAX-RPC. También están soportadas algunas correlaciones opcionales o no especificadas en JAX-RPC. Consulte la especificación JAX-RPC si desea una lista completa de las API. Para obtener una lista completa de los estándares y las especificaciones a los que se da soporte, consulte las especificaciones y la documentación de la API de los servicios web.
Convenciones de notación
Prefijo de espacio de nombres | Espacio de nombres |
---|---|
xsd | http://www.w3.org/2001/XMLSchema |
xsi | http://www.w3.org/2001/XMLSchema-instance |
soapenc | http://schemas.xmlsoap.org/soap/encoding/ |
wsdl | http://schemas.xmlsoap.org/wsdl/ |
wsdlsoap | http://schemas.xmlsoap.org/wsdl/soap/ |
ns | nombre de espacio definido por el usuario |
apache | http://xml.apache.org/xml-soap |
wasws | http://websphere.ibm.com/webservices/ |
Información detallada sobre correlación
En los apartados siguientes se identifican las correlaciones soportadas, incluidas:Correlación de Java con WSDL
En este apartado se resumen las reglas de correlación de Java con WSDL. El mandato Java2WSDL utiliza las reglas de correlación Java-to-WSDL para el proceso ascendente. En el proceso ascendente, se utiliza la implementación de un servicio Java existente para crear archivos WSDL que definen el servicio web. Es posible que sea necesario editar, manualmente, el archivo WSDL generado, por los siguientes motivos:- No todas las clases y constructores Java se correlacionan con archivos WSDL. Por ejemplo, las clases Java que no cumplen con las reglas de especificación de beans Java podría ser que no se correlacionen con constructores WSDL.
- Algunos constructores y clases Java tienen varias correlaciones con un archivo WSDL. Por ejemplo, una clase java.lang.String puede correlacionarse con un constructor xsd:string o una soapenc:string. El mandato Java2WSDL selecciona una de estas correlaciones, aunque debe editarse el archivo WSDL si se desea una correlación distinta.
- Hay varios modos de generar constructores WSDL. Por ejemplo, puede generar wsdl:part en wsdl:message con un atributo de tipo o elemento. El mandato Java2WSDL realiza una selección en función de los valores de las opciones -style y -use.
- El archivo WSDL describe los elementos de datos de instancia enviados en el mensaje SOAP. Si desea modificar los nombres o el formato utilizado en el mensaje, debe editarse el archivo WSDL. Por ejemplo, el mandato Java2WSDL se correlaciona con una propiedad Java bean como elemento XML. En algunas circunstancias es posible que desee cambiar el archivo WSDL de forma que se correlacione con la propiedad Java bean como si fuera un atributo XML.
- Será necesario editar el archivo WSDL si se desea soporte de cabecera o de archivos adjuntos.
- Será necesario editar el archivo WSDL si se desea un WSDL de varias partes, utilizando el constructor wsdl:import.
- Correlación de paquetes con espacios de nombres
La especificación JAX-RPC no indica la correlación predeterminada de nombres de paquetes Java con espacios de nombres XML. La especificación JAX-RPC especifica que cada paquete Java debe tener correlación con un solo espacio de nombres XML. Asimismo, cada espacio de nombres XML debe tener correlación con un solo paquete Java. Se proporciona un algoritmo de correlación predeterminado que construye el espacio de nombres invirtiendo los nombres del paquete Java y añadiendo el prefijo http://. Por ejemplo, un paquete llamado com.ibm.webservice se correlaciona con el espacio de nombres XML http://webservice.ibm.com.
La correlación predeterminada entre espacios de nombres XML y nombres de paquetes Java se puede alterar temporalmente utilizando las opciones -NStoPkg y -PkgtoNS de los mandatos WSDL2Java y Java2WSDL.
- Correlación de identificador:
Los identificadores Java se correlacionan directamente con identificadores WSDL y XML.
Los nombres de propiedades de beans Java se correlacionan con los identificadores XML. Por ejemplo, un bean Java con los métodos getInfo y setInfo se correlaciona con un constructor XML con el nombre info.
Los nombres de parámetros de método de la interfaz de punto final de servicio, si están disponibles, se correlacionan directamente con los identificadores XML y WDSL. Consulte la información sobre la opción -implClass del mandato WSDL2Java para obtener más datos.
- Resumen de constructores WSDL
Tabla 2. Correlación de Java a WSDL o un constructor XML. Describe la correlación de constructores Java con los constructores WSDL y XML relacionados. Constructor Java Constructor WSDL y XML Interfaz de punto final de servicio wsdl:portType Método wsdl:operation Parámetros wsdl:input, wsdl:message, wsdl:part Valor de retorno wsdl:output, wsdl:message, wsdl:part Genera wsdl:fault, wsdl:message, wsdl:part Tipos primitivos Tipos simples xsd y soapenc Beans Java xsd:complexType Propiedades de beans Java Elementos xsd:elements anidados de xsd:complexType Matrices xsd:complexType o xsd:element definido por JAX-RPC con un atributo maxOccurs="unbounded" Excepciones definidas por el usuario xsd:complexType - Construcción de enlaces y servicios
Se genera un enlace wsdl:binding que cumple el tipo de puerto wsdl:portType generado. Se genera un servicio wsdl:service que contiene un puerto que hace referencia al enlace wsdl:binding generado. Los nombres y valores del servicio los controla el mandato Java2WSDL.
- style y useUtilice las opciones -style y -use para generar distintos tipos de archivos WSDL. Las cuatro combinaciones soportadas son:
- -style DOCUMENT -use LITERAL
- -style RPC -use LITERAL
- -style DOCUMENT -use LITERAL -wrapped false
- -style RPC -use ENCODED
- DOCUMENT LITERAL:
El mandato Java2WSDL genera una especificación WS-I (Web Services - Interoperability) que cumple con el archivo WDSL literal de documentos. El wsdl:binding se genera con los atributos style="document" y use="literal" incorporados. Se genera un xsd:element para cada método de interfaz de punto final de servicio para describir el mensaje de solicitud. Se genera un xsd:element similar para cada método de interfaz de punto final de servicio para describir el mensaje de respuesta.
- RPC LITERAL:
El mandato Java2WSDL genera un archivo WSDL rpc-literal que cumple con la especificación WS-I. El wsdl:binding se genera con los atributos style="rpc" y use="literal" incorporados. Las construcciones wsdl:message se generan para las entradas y salidas para cada método de interfaz de punto final de servicio. Los parámetros del método los describen los elementos part dentro de las construcciones wsdl:message.
- DOCUMENT LITERAL sin envoltura:
El mandato Java2WSDL genera un archivo WSDL de literal de documento de acuerdo con la especificación JAX-RPC. Este archivo WSDL no cumple con las especificaciones .NET. La principal diferencia entre DOCUMENT LITERAL y DOCUMENT LITERAL sin envoltura es el uso de construcciones wsdl:message para definir los mensajes de solicitud y respuesta.
- RPC ENCODED:
El mandato Java2WSDL genera un archivo WSDL con codificación RPC de acuerdo con la especificación JAX-RPC. Este archivo WSDL no cumple con la especificación WS-I. El wsdl:binding se genera con los atributos style="rpc" y use="encoded". Se utilizan determinadas correlaciones soapenc para representar tipos y matrices.
Muchos tipos Java se correlacionan directamente con tipos XML estándar. Por ejemplo, un java.lang.String se correlaciona con un xsd:string. Estas correlaciones se describen en la especificación JAX-RPC.
Los tipos Java que no se pueden correlacionar directamente con tipos XML estándar se generan en la sección wsdl:types. Las clases Java que coinciden con el patrón de beans Java se correlacionan con xsd:complexType. Revise la especificación JAX-RPC para obtener una descripción de todas las reglas de correlación. En el siguiente ejemplo se muestra la correlación clases Java base y derivadas de muestra.Java: public abstract class Base { public Base() {} public int a; // correlacionada private int b; // correlacionada mediante setter/getter private int c; // no correlacionada private int[] d; // correlacionada mediante setter/getter indexado public int getB() { return b;} // correlacionar la propiedad b public void setB(int b) {this.b = b;} public int[] getD() { return d;} // correlacionar la propiedad indexada d public void setD(int[] d) {this.d = d;} public int getD(int index) { return d[index];} public void setB(int index, int value) {this.d[index] = value;} public void someMethod() {...} // no correlacionado } public class Derived extends Base { public int x; // correlacionada private int y; // no correlacionada } Se correlaciona con: <xsd:complexType name="Base" abstract="true"> <xsd:sequence> <xsd:element name="a" type="xsd:int"/> <xsd:element name="b" type="xsd:int"/> <xsd:element name="d" minOccurs="0" maxOccurs="unbounded" type="xsd:int"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="Derived"> <xsd:complexContent> <xsd:extension base="ns:Base"> <xsd:sequence> <xsd:element name="x" type="xsd:int"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType>
- Clases no soportadas:
Si una clase no se puede asignar a un tipo XML, el mandato Java2WSDL emite un mensaje y se genera una referencia xsd:anyType en el archivo WSDL. En estas situaciones, modifique la implementación del servicio web para utilizar las clases compatibles con JAX-RPC.
Correlación de WSDL con Java
El mandato WSDL2Java genera clases Java con la información describa en el archivo WSDL.
- Correlación de un espacio de nombres con un paquete
JAX-RPC no especifica la correlación de espacios de nombres XML con nombres de paquetes Java. JAX-RPC especifica que cada paquete Java tiene correlación con un solo espacio de nombres XML. Asimismo, cada espacio de nombres XML debe tener correlación con un solo paquete Java. El algoritmo de correlación predeterminado omite todo protocolo del espacio de nombres XML e invierte los nombres. Por ejemplo, un espacio de nombres XML http://websphere.ibm.com se convierte en un paquete Java con el nombre com.ibm.websphere.
La correlación predeterminada de un espacio de nombres XML con un paquete Java no tiene en cuenta el directorio raíz de contexto. Si dos espacios de nombres son iguales hasta la primera barra inclinada, se correlacionan con el mismo paquete Java. Por ejemplo, los espacios de nombres XML http://websphere.ibm.com/foo y http://websphere.ibm.com/bar se correlacionan con el paquete Java com.ibm.websphere. La correlación predeterminada entre espacios de nombres XML y nombres de paquetes Java se puede alterar temporalmente utilizando las opciones -NStoPkg y -PkgtoNS de los mandatos WSDL2Java y Java2WSDL.
Los nombres XML tienen más posibilidades de formato que los identificadores Java. Pueden incluir caracteres que no se permiten en identificadores Java. Consulte el apéndice 20 de la especificación JAX-RPC para obtener las reglas que establecen las correlaciones de nombres XML con identificadores Java.
- Resumen de constructores Java: En la tabla siguiente se resume la construcción de XML a Java. Consulte la especificación JAX-RPC para obtener una descripción de estas correlaciones.
Tabla 3. Correlación de un constructor WSDL o XML con Java. Describe la correlación entre las construcciones para XML y Java. Construcción WSDL y XML Construcción Java xsd:complexType Clase de bean Java, clase de excepción Java o matriz Java nested xsd:element/xsd:attribute Propiedad de bean Java xsd:simpleType (enumeration) Clase de enumeración JAX-RPC wsdl:message: la signatura de parámetro de método viene determinada generalmente por el mensaje wsdl:message. Signatura del método de interfaz de punto final de servicio wsdl:portType Interfaz de punto final de servicio wsdl:operation Método de interfaz de punto final de servicio wsdl:binding Stub wsdl:service Interfaz de servicio wsdl:port Método de acceso de puerto de la interfaz de servicio - Correlación de tipos XML estándar:
- Correlación de tipos XML simple JAX-RPC
Muchos de los tipos XML se correlacionan directamente con tipos Java. Consulte la especificación JAX-RPC para obtener una descripción de estas correlaciones.
El mandato WSDL2Java genera tipos Java para el esquema XML definidos en la sección wsdl:types. El lenguaje de esquema XML es más amplio que el subconjunto necesario u opcional definido en la especificación JAX-RPC. El mandato WSDL2Java da soporte a las correlaciones obligatorias y a la mayoría de las correlaciones opcionales, así como a las correlaciones de esquemas XML que no se incluyen en la especificación JAX-RPC. El mandato WSDL2Java ignora algunas construcciones a las que no da soporte. Por ejemplo, el mandato no da soporte al atributo predeterminado. Si se define un elemento xsd:element con el atributo predeterminado, éste se ignora. En algunos casos, el mandato correlaciona construcciones no soportadas con la interfaz Java, javax.xml.soap.SOAPElement.
La correlación de beans Java estándar se define en la sección 4.2.3 de la especificación JAX-RPC. xsd:complexType define el tipo. Los elementos xsd:elements anidados en grupos de xsd:sequence o xsd:all se correlacionan con propiedades de beans Java. Por ejemplo:XML: <xsd:complexType name="Sample"> <xsd:sequence> <xsd:element name="a" type="xsd:string"/> <xsd:element name="b" maxOccurs="unbounded" type="xsd:string"/> </xsd:sequence> </xsd:complexType> Java: public class Sample { // .. public Sample() {} // Propiedad de Bean a public String getA() {...} public void setA(String value) {...} // Propiedad de bean indexado b public String[] getB() {...} public String getB(int index) {...} public void setB(String[] values) {...} public void setB(int index, String value) {...} }
- Correlación del constructor wsdl:portType
El constructor wsdl:portType se correlaciona con la interfaz de punto final de servicio. El nombre del constructor wsdl:portType se correlaciona con el nombre de la clase de la interfaz de punto final de servicio.
- Correlación del constructor wsdl:operationUn constructor wsdl:operation dentro de un wsdl:portType se correlaciona con un método de la interfaz de punto final de servicio. El nombre de wsdl:operation se correlaciona con el nombre del método. wsdl:operation contiene elementos wsdl:input y wsdl:output que hacen referencia a los constructores de mensaje wsdl:message de solicitud y de respuesta que utilizan el atributo message. La operación wsdl:operation puede contener un elemento wsdl:fault que hace referencia a un mensaje wsdl:message que describe el error. Estos errores se correlacionan con clases Java que amplían la excepción java.lang.Exception tal como se describe en la sección 4.3.6 de la especificación JAX-RPC.
- Efecto del formato literal de envoltura de documentoSi el archivo WSDL utiliza el documento y el formato literal de documento de envoltura, los parámetros del método se correlacionan desde el xsd:element de envoltura. El mandato WSDL2Java detecta automáticamente el formato de literal y el formato literal de envoltura de documento. Deben cumplirse los criterios siguientes:
- El archivo WSDL debe tener style="document" en los constructores wsdl:binding.
- Los constructores input y output de las operaciones dentro de wsdl:binding deben contener elementos soap:body que contienen use="literal".
- El mensaje wsdl:message al que hace referencia el constructor de entrada de operación wsdl:operation debe tener un sola parte.
- La parte debe utilizar el atributo de elemento para hacer referencia a un xsd:element.
- El xsd:element al que se hace referencia o, el elemento de envoltura, debe tener el mismo nombre que la operación wsdl:operation.
- El elemento de envoltura no debe contener ningún atributo xsd:attributes.
WSDL: <xsd:element name="myMethod"> <xsd:complexType> <xsd:sequence> <xsd:element name="param1" type="xsd:string"/> <xsd:element name="param2" type="xsd:int"/> </xsd:sequence> </xsd:complexType> </xsd:element> ... <wsdl:message name="response"/> <part name="parameters" element="ns:myMethod"/> </wsdl:message name="response"/> <wsdl:message name="response"/> ... <wsdl:operation name="myMethod"> <input name="input" message="request"/> <output name="output" message="response"/> </wsdl:operation> Java: void myMethod(String param1, int param2) ...
- Correlación de parámetro:
Si no se detecta el documento y el formato literal de envoltura la correlación de parámetros sigue las reglas habituales de correlación JAX-RPC establecidas en la sección 4.3.4 de la especificación JAX-RPC.
Todos los parámetros se definen mediante una parte wsdl:message a la que se hace referencia en elementos input y output.- La parte wsdl:part del mensaje wsdl:message de solicitud se correlaciona con el parámetro input.
- La parte wsdl:part del mensaje wsdl:message de respuesta se correlaciona con el valor return. Si hay varias partes wsdl:parts en el mensaje de respuesta, se correlacionan con parámetros output.
- Se genera una clase Holder para cada parámetro output como se describe en la sección 4.3.5 de la especificación JAX-RPC.
- La parte wsdl:part que es un mensaje wsdl:message de solicitud y de
respuesta se correlaciona con un parámetro inout.
- Se genera una clase Holder para cada parámetro inout como se describe en la sección 4.3.5 de la especificación JAX-RPC.
- El atributo wsdl:operation parameterOrder define el orden de los parámetros.
XML: <wsdl:message name="request"> <part name="param1" type="xsd:string"/> <part name="param2" type="xsd:int"/> </wsdl:message name="response"/> <wsdl:message name="response"/> ... <wsdl:operation name="myMethod" parameterOrder="param1, param2"> <input name="input" message="request"/> <output name="output" message="response"/> </wsdl:operation> Java: void myMethod(String param1, int param2) ...
- Efecto del formato literal de envoltura de documento
- Correlación de wsdl:binding:El mandato WSDL2Java utiliza la información de wsdl:binding para generar en el cliente un apéndice específico de implementación. WebSphere Application Server utiliza la información de wsdl:binding en el servidor para deserializar correctamente la solicitud, invocar al servicio web y serializar la respuesta. La información del elemento wsdl:binding no influye en la generación de la interfaz de punto final de servicio, excepto cuando se utiliza el formato de envoltura de documento y literal, o cuando hay conexiones MIME.
- Adjuntos MIME:Para un archivo WSDL compatible con WSDL 1.1, la parte de un mensaje de operación que se define en el enlace como una conexión MIME, pasa a ser un parámetro del tipo de la conexión independientemente de la parte declarada. Por ejemplo:
La especificación JAX-RPC requiere soporte de los tipos MIME siguientes:XML: <wsdl:types> <schema ...> <complexType name="ArrayOfBinary"> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/> </restriction> </complexType> </schema> </wsdl:types> <wsdl:message name="request"> <part name="param1" type="ns:ArrayOfBinary"/> <wsdl:message name="response"/> <wsdl:message name="response"/> ... <wsdl:operation name="myMethod"> <input name="input" message="request"/> <output name="output" message="response"/> </wsdl:operation> ... <binding ... <wsdl:operation name="myMethod"> <input> <mime:multipartRelated> <mime:part> <mime:content part="param1" type="image/jpeg"/> </mime:part> </mime:multipartRelated> </input> ... </wsdl:operation> Java: void myMethod(java.awt.Image param1) ...
Tabla 4. Correlación de un tipo MIME y un tipo Java. Describe la correlación entre tipos MIME y tipos Java. Tipo MIME Tipo Java image/gif java.awt.Image image/jpeg java.awt.Image text/plain java.lang.String multipart/* javax.mail.internet.MimeMultipart text/xml javax.xml.transform.Source application/xml javax.xml.transform.Source
- Adjuntos MIME:
- Correlación de wsdl:service:
El elemento wsdl:service se correlaciona con una interfaz de servicio generada. La interfaz de servicio generada contiene métodos para acceder a cada uno de los puertos en el elemento wsdl:service. La interfaz de servicio generada se describe en las secciones 4.3.9, 4.3.10 y 4.3.11 de la especificación JAX-RPC.
Además, el elemento wsdl:service se correlaciona con la clase ServiceLocator específica de la implementación, que es una implementación de la interfaz de servicio generada.
- Correlación de tipos XML simple JAX-RPC
Consulte la información acerca de la herramienta de línea de mandatos WSDL2Java para las aplicaciones JAX-RPC (Java API for XML-based RPC) para obtener más información acerca de esta herramienta.
Correlación entre mensajes WSDL y SOAP
El archivo WSDL define el formato del mensaje SOAP que se transmite a través de conexiones de red. El mandato WSDL2Java y el programa de ejecución de WebSphere Application Server utilizan la información del archivo WSDL para asegurarse de que el mensaje SOAP se serializa y deserializa correctamente.
Si un elemento wsdl:binding indica que se ha enviado un mensaje en formato RPC, el mensaje SOAP contiene un elemento que define la operación. Si un elemento wsdl:binding indica que el mensaje se envía en un formato de documento, el mensaje SOAP no contiene el elemento de operación.
Si se define el elemento wsdl:part con el atributo de tipo, en el mensaje se utilizan el nombre y el tipo de la parte. Si se define el elemento wsdl:part con el atributo de elemento, en el mensaje se utilizan el nombre y el tipo del elemento. El atributo de elemento no recibe soporte en la especificación JAX-RPC cuando use="encoded".
DOCUMENT/LITERAL
WSDL:
<xsd:element name="c" type="xsd:int"/>
<xsd:element name="method">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="a" type="xsd:string"/>
<xsd:element ref="ns:c"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
...
<wsdl:message name="request">
<part name="parameters" element="ns:method"/>
</wsdl:message>
...
<wsdl:operation name="method">
<input message="request"/>
...
Mensaje:
<soap:body>
<ns:method>
<a>ABC</a>
<c>123</a>
<ns:method>
</soap:body>
RPC/ENCODED
WSDL:
<xsd:element name="c" type="xsd:int"/>
...
<wsdl:message name="request">
<part name="a" type="xsd:string"/>
<part name="b" element="ns:c"/>
</wsdl:message>
...
<wsdl:operation name="method">
<input message="request"/>
...
Mensaje:
<soap:body>
<ns:method>
<a xsi:type="xsd:string">ABC</a>
<no se permite el atributo de elemento en modalidad rpc/codificada>
</ns:method>
</soap:body>
DOCUMENT/LITERAL sin envoltura
WSDL:
<xsd:element name="c" type="xsd:int"/>
...
<wsdl:message name="request">
<part name="a" type="xsd:string"/>
<part name="b" element="ns:c"/>
</wsdl:message>
...
<wsdl:operation name="method">
<input message="request"/>
...
Mensaje:
<soap:body>
<a>ABC</a>
<c>123</a>
</soap:body>