B JAX-RPC Mapping File Descriptor

The JAX-RPC mapping file is a standard XML file that describes the binding between the WSDL and the Java service endpoint interface(s). A number of WebServicesAssembler commands produce a JAX-RPC mapping file as part of their output. You can edit the contents of the file to customize the contents of the generated WSDL or service endpoint interface.

The published version of the JAX-RPC mapping file schema can be found at the following Web site.

http://java.sun.com/xml/ns/j2ee/j2ee_jaxrpc_mapping_1_1.xsd

This appendix has the following sections.

• Producing a JAX-RPC Mapping File

• Naming Conventions for the JAX-RPC Mapping File

• Customizing the WSDL or Service Endpoint Interface Contents

Producing a JAX-RPC Mapping File

These WebServicesAssembler commands generate a JAX-RPC mapping file as part of their output. Most of these commands are used when developing a Web service bottom up. For more information on these commands, see "WebServicesAssembler Commands" in the Oracle Application Server Web Services Developer's Guide.

• aqAssemble

• assemble

• corbaAssemble

• dbJavaAssemble

• ejbAssemble

• jmsAssemble

• plsqlAssemble

• sqlAssemble

• genInterface

• genValueTypes (produces a "partial" JAX-RPC mapping file)

• genWsdl

Naming Conventions for the JAX-RPC Mapping File

The generated JAX-RPC mapping file has the following naming pattern:<serviceName>java-wsdl-mapping.xml

Where the prefix serviceName is the local part of the qname of the service.

The JAX-RPC mapping file is typically stored in the same directory as the webservices.xml file.

Customizing the WSDL or Service Endpoint Interface Contents

Editing the JAX-RPC mapping file enables you to customize the contents of the generated WSDL (for bottom up Web services development) or the contents of the generated service endpoint interface (for top down Web services development). "Customization Scenarios" describes some common situations where you might want to customize the WSDL or service endpoint interface.

To produce a mapping file that you can edit, WebServicesAssembler provides two commands: genInterface and genWsdl.

• for general top down Web service development, the genInterface command takes a WSDL as input and produces a service endpoint interface and a JAX-RPC mapping file as output.

• for general bottom up Web service development, the genWsdl command takes a service endpoint interface as input and produces a WSDL and a JAX-RPC mapping file as output.

After modifying the mapping file, you can use it as input to any of the WebServicesAssembler commands that develop a Web service top down or bottom up. The resulting service endpoint interface or WSDL will reflect the changes that you specified in the mapping file.

This discussion can be summarized in these steps:

1. Generate a mapping file.

   To do this, use the genInterface command for top down Web service development or genWsdl command for bottom up Web service development.

2. Edit the mapping file.

   The "Customization Scenarios" section describes some of the common ways in which you can edit the JAX-RPC mapping file.

3. Use the modified JAX-RPC mapping file as input to the appropriate WebServicesAssembler command to develop your Web service.

Customization Scenarios

The following sections describe situations where you might want to edit the JAX-RPC mapping file to generate a custom WSDL or service endpoint interface.

• Changing Namespace-to-Java Mappings

• Changing the Names of Java or WSDL Artifacts

• Generating Code into a Single Package from a WSDL with Multiple Namespaces

• Wrapping or Unwrapping Mapping for Document-Literal Operations

• Mapping Between SOAP Headers and Java Method Parameters

Changing Namespace-to-Java Mappings

In the mapping file, the <package-mapping> element identifies the mapping between the namespace and the Java package. The <namespaceURI> sub-element identifies the namespace and the <package-type> sub-element identifies the Java package. A sample <package-mapping> element is displayed in Example B-1.

Example B-1 Package to Namespace Mapping Elements in the JAX-RPC Mapping File

<java-wsdl-mapping version="1.0">
    <package-mapping>
        <package-type>com.foo.mypackage</package-type>
        <namespaceURI>http://www.foo.com</namespaceURI>
    </package-mapping>
</java-wsdl-mapping>

You can change the mapping between the namespace and Java package by changing either of the values within the <package-mapping> element. The generated WSDL or service endpoint interface will use the new namespace or Java package value.

The <package-mapping> element can appear more than once in the mapping file.

Changing the Names of Java or WSDL Artifacts

In the mapping file, you can change the names of Java or WSDL artifacts. For example, for top down Web service development, assume that you want to change the mapping of the wsdl-say-hello operation in your given WSDL. You can use the WSDL as input to genInterface, then edit the resulting JAX-RPC mapping file to map the wsdl-say-hello WSDL operation from its default to a javaSayHello method that you provide.Similarly, for bottom up Web service development, you can use a given service endpoint interface, such as MyServiceEndpoint, as input to genWsdl. You can then edit the resulting JAX-RPC mapping file to map the service endpoint interface to a port-type, such as my-service-port-type, in the WSDL.

See the JAX-RPC mapping file schema for more information on where the names of the Java and WSDL artifacts can be changed.

http://java.sun.com/xml/ns/j2ee/j2ee_jaxrpc_mapping_1_1.xsd

Generating Code into a Single Package from a WSDL with Multiple Namespaces

If you are working with a WSDL with multiple namespaces, WebServicesAssembler places all generated code into a package that corresponds to the namespace of the WSDL and schema value types. If the WSDL contains multiple namespaces, then one package will be created for each namespace. Importing multiple packages can be inconvenient when writing your implementation class.

WebServicesAssembler does not provide an argument that allows all code to be generated in the same package. For example, the packageName argument effects only the package name for service endpoint interface and any schema types that have the same target namespace as the WSDL. If there are schema value types in a different namespace, then WebServicesAssembler generates them into a different package by default.

You can direct WebServicesAssembler to generate a single package by editing the JAX-RPC mapping file. For each namespace, the file contains a <package-mapping> clause with a <package-type> and <namespaceURI> element. These elements identify the mapping between the namespace and a Java package. Edit each instance of the <package-type> element to enter the name of the single package where you want the generated code to reside.

Example B-2 illustrates the contents of a JAX-RPC mapping file that has been edited to place the generated code from three different namespaces into the package MyPackage. The <package-type> and <namespaceURI> elements are highlighted in bold.

Example B-2 Mapping File that Specifies a Single Package for Multiple Namespaces

<java-wsdl-mapping version="1.1">
    <package-mapping>
        <package-type>MyPackage</package-type>
        <namespaceURI>namespace1 in the WSDL</namespaceURI>
    </package-mapping>
    <package-mapping>
        <package-type>MyPackage</package-type>
        <namespaceURI>namespace2 in the WSDL</namespaceURI>
    </package-mapping>
     ...
    <package-mapping>
        <package-type>MyPackage</package-type>
        <namespaceURI>namespaceN in the WSDL</namespaceURI>
    </package-mapping>
</java-wsdl-mapping>

How to Generate Code into a Single Package Using a WSDL with Multiple Namespaces

The following steps summarize how you can direct WebservicesAssembler to generate code into a single package when the WSDL contains multiple namespaces.

1. Generate a JAX-RPC mapping file for the Web service.

   Use the genInterface command if you are assembling a Web service top down or the genWsdl command if you are assembling a Web service bottom up. You can also write your own JAX-RPC mapping file by hand.

2. Edit the JAX-RPC mapping file so that each instance of the <package-type> element in the <package-mapping> clause contains the name of the single package where you want the generated code to reside.

3. Assemble the Web service using the appropriate *Assemble command. Use the mappingFileName argument to specify the edited JAX-RPC mapping file.

   All of the generated code will reside in the same package.

"Default Algorithms to Map Between Target WSDL Namespaces and Java Package Names" in the Oracle Application Server Web Services Developer's Guide provides more information on how WebServicesAssembler constructs a default type namespace from the package name.

Wrapping or Unwrapping Mapping for Document-Literal Operations

The <service-endpoint-method-mapping> element defines the mapping of Java methods to WSDL operations. If a <wrapped-element/> is specified under this element and you are working with document-literal WSDL operations, then each Java method parameter that is not mapped to a SOAP header is mapped to a sub-element of a complexType. This complexType is used as the type of a wrapper element. Any Java method parameters that are not mapped to a SOAP header, must be mapped to a sub-element of a complexType (that is, they must be wrapped).

Mapping Between SOAP Headers and Java Method Parameters

The <wsdl-message-mapping> element defines the unique mapping from a specific Java method parameter to a specific message and its part. Parts within a message context are uniquely identified with their names.

If <soap-header/> is specified under a <wsdl-message-mapping> element, then:

• this Java method parameter is exposed as a SOAP header for bottom up development

• the corresponding SOAP header is mapped to a Java method parameter for top down development