A.5. Web Service Java/WSDL MappingsWhen deploying JAX-RPC web services in a J2EE application, each web service must have a mapping file that describes how the Java entities in the service implementation and the XML entities in the WSDL are mapped to each other. The mapping file is included in the component archive and specified in the webservices.xml deployment descriptor. Figure A-16 shows the structure of JAX-RPC mapping files. Example A-16 shows sample Java/WSDL mappings , annotated with descriptive comments. Figure A-16. Web services Java/WSDL mappingsExample A-16. Annotated Java/WSDL mappings<?xml version="1.0" encoding="UTF-8"?> <java-wsdl-mapping xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/j2ee_jaxrpc_mapping_1_1.xsd" version="1.1"> <!-- Each package-mapping element specifies how a Java package is mapped to an XML namespace in the WSDL for the service. --> <package-mapping> <!-- The Java package for the mapping. --> <package-type>com.my.service.datatypes</package-type> <!-- The XML namespace to be mapped to this package. --> <namespaceURI>my-service-ns</namespaceURI> </package-mapping> <!-- Each java-xml-type-mapping element specifies how to map an XML element to a corresponding Java type. --> <java-xml-type-mapping> <!-- The full classname of the Java type. --> <java-type>com.my.service.datatypes.type1</java-type> <!-- The WSDL entity is identified using its qualified name (QName). If the WSDL entity has an anonymous QName, then an anonymous-type-qname element is used here. Otherwise, a root-type-qname element should be used. --> <root-type-qname>my-service-ns:type1</root-type-qname> <!-- Each qualified name must be scoped to the WSDL element type, by specifying simpleType, complexType, or element here. --> <qname-scope>complexType</qname-scope> <!-- If the WSDL entity has child elements that need to be mapped to corresponding properties on the Java type, then one or more variable-mapping elements can be used here. --> <variable-mapping> <!-- The name of the Java property or public data member for the mapping. --> <java-variable-name>id</java-variable-name> <!-- This empty element is used to indicate that the Java variable listed above is a public data member, not a JavaBeans property. --> <data-member/> <!-- The corresponding WSDL entity is specified as either an XML element, using an xml-element-name; an XML attribute, using an xml-attribute-name element; or an XML xsd:any element, using the empty xml-wildcard element --> <xml-attribute-name>id</xml-attribute-name> </variable-mapping> </java-xml-type-mapping> <!-- Each exception-mapping entry maps a WSDL fault entity to a Java exception. --> <exception-mapping> <!-- The fully qualified Java class name of the exception --> <exception-type>com.my.service.BadParameterException</exception-type> <!-- This element specifies the qualified name (QName) of the WSDL message for the fault. --> <wsdl-message>my-service-ns:BadParameterFaultMessage</wsdl-message> <!-- If the fault message has more than one part, you need to use this element to indicate which part is being mapped here. --> <wsdl-message-part-name>fault-part</wsdl-message-part-name> <!-- If the mapped WSDL fault element is a complex type, you can specify the order in which its elements are mapped to the constructor arguments on the exception class. --> <constructor-parameter-order> <!-- The name of an an element of the complex WSDL type. --> <element-name>fault-message</element-name> </constructor-parameter-order> </exception-mapping> <!-- Each service-interface-mapping element maps a WSDL service entity to a corresponding set of Java interfaces. At a minimum, the service itself must be mapped to a corresponding Java interface, but you can also specify how each port in the service is mapped to a getX method on generated service interfaces. --> <service-interface-mapping> <!-- The fully qualified class name of the Java interface for the WSDL service. This can be preexisting, or it can be generated using tools in your web service engine. --> <service-interface>com.my.service.interface</service-interface> <!-- The qualified name of the WSDL service entity. --> <wsdl-service-name>my-service-ns:service1</wsdl-service-name> <!-- Each port-mapping entry generates a getX method on any service interfaces that are automatically generated using this mapping file. If "JavaName" is given as the java-port-name below, then a getJavaName( ) method will be generated on the service interface, and calling this method will return a Java interface for the port named in the port-name element --> <port-mapping> <!-- The WSDL port name to be bound to the Java name below. --> <port-name>port1</port-name> <!-- The name to use for the getX method on the generated service interface. In this case, the method will be getPort1, which will return a Java binding for the WSDL port named port1. --> <java-port-name>Port1</java-port-name> </port-mapping> </service-interface-mapping> <!-- Each service-endpoint-interface-mapping element specifies how a WSDL port is to be mapped to corresponding Java entities. --> <service-endpoint-interface-mapping> <!-- The fully qualified Java class for the port interface. --> <service-endpoint-interface> com.my.service.port1</service-endpoint-interface> <!-- The qualified name of the WSDL port to be mapped. --> <wsdl-port-type>my-service-ns:port1</wsdl-port-type> <!-- The qualified name of the binding of the WSDL port to be mapped. A given WSDL port can potentially be associated with multiple bindings (e.g., HTTP and SMTP bindings of the same service), so this element is needed to uniquely identify the port/binding being mapped. --> <wsdl-binding>urn:my-service-ns/port1-binding1</wsdl-binding> <!-- Each service-endpoint-method-mapping element defines how a method on the Java interface is mapped to specific operations on the WSDL port being mapped. If a default mapping is being used, you don't need to include any method mappings here, but these method mappings can be useful for customizing the mapping. --> <service-endpoint-method-mapping> <!-- The name of the Java method being mapped. --> <java-method-name>doServiceOperation1</java-method-name> <!-- The name of the WSDL operation within the port being mapped --> <wsdl-operation>serviceOperation1</wsdl-operation> <!-- If the operation uses a wrapped element with the same name as the operation, then this element should be present. --> <wrapped-element/> <!-- The Java method arguments can be mapped to input messages on the WSDL operation using method-param-parts-mapping elements. --> <method-param-parts-mapping> <!-- The position of the method argument in the Java method argument list. The position is indexed from zero. --> <param-position>0</param-position> <!-- The Java type of the method argument. --> <param-type>java.lang.String</param-type> <!-- The corresponding WSDL message is specified with this element. --> <wsdl-message-mapping> <!-- The qualified name of the WSDL message. --> <wsdl-message> my-service-ns:operation1Input1</wsdl-message> <!-- The part of the message being mapped. If the method is using a wrapped element (i.e., the wrapped-element entry is specified in the method mapping), then this part name references the name of a child element in the wrapped element. If the method is not using a wrapped element, then the part name here references WSDL message part name. --> <wsdl-message-part-name> elementPart1</wsdl-message-part-name> <!-- This indicates whether the mapping is inbound only (with respect to the SOAP service), outbound only, or both directions. The allowed values are IN, OUT, or INOUT. --> <parameter-mode>INOUT</parameter-mode> <!-- If this element is present, then this mapping is from a Java parameters to a SOAP header, rather than a WSDL message. --> <soap-header/> </wsdl-message-mapping> </method-param-parts-mapping> <!-- The mapping of the output messages (if there are any) on the WSDL operation to the Java return type of the method can be specified using this element. --> <wsdl-return-value-mapping> <!-- The fully qualified Java type of the method return value. --> <method-return-value></method-return-value> <!-- The qualified name of the WSDL message being mapped. --> <wsdl-message> my-service-ns:operation1Output1</wsdl-message> <!-- The part of the message being mapped. If the method is using a wrapped element (i.e., the wrapped-element entry is specified in the method mapping), then this part name references the name of a child element in the wrapped element. If the method is not using a wrapped element, then the part name here references the WSDL message part name. --> <wsdl-message-part-name> elementPart1</wsdl-message-part-name> </wsdl-return-value-mapping> </service-endpoint-method-mapping> </service-endpoint-interface-mapping> </java-wsdl-mapping> |