Section A.5. Web Service JavaWSDL Mappings

A.5. Web Service Java/WSDL Mappings

When 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 mappings

Example 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>