5 Assembling a Web Service from a WSDL

This chapter describes how to assemble a Web service, starting with a Web Service Description Language (WSDL) file. This is also known as top down Web service generation.

What Is Top Down Assembly?

In top down Web service assembly, you generate a service from an existing WSDL file that models the business processes you want to expose.

A development tool, such as WebServiceAssembler, uses the WSDL to generate the service endpoint interface for the service. You can then implement the service for any supported architecture, such as Java classes. After compiling the implementation, you generate the service and deploy it to the application server.

Chapter 4, "Oracle Application Server Web Services Messages" provides information about the message formats you can assign to a Web service.

How to Assemble a Web Service Top Down

This section describes what you must provide to assemble a Web service top down. Assembling a Web service requires the WebServiceAssembler tool, and Java platform tools such as the javac compiler, that are found in the J2SE 1.4 SDK distribution.

There are three general steps for generating a Web service top down:

Generate the service endpoint interface.

WebServicesAssembler can perform this step.
Implement and compile the services.

The developer performs this step.
Assemble the services.

WebServicesAssembler can perform this step. "Generating the Web Service Top Down" provides more detail on each of these steps.

Prerequisites

Generating a Web service top down with WebServiceAssembler requires you to specify only the WSDL and an output directory.

Before you generate Web services, consider these issues:

WebServicesAssembler places some restrictions on the WSDL that you specify:
- The WSDL should comply with Web Services-Interoperability (WS-I) Basic Profile 1.0. If it does not, WebServiceAssembler provides command-line arguments that enable you to work around many limitations in the WSDL. Chapter 17, "Using WebServicesAssembler" provides descriptions of WebServicesAssembler commands and arguments.
- Only one service element can be implemented. WebServicesAssembler enables you to generate the artifacts for only one service at a time. If more than one service is described in the WSDL, a command line argument, serviceName, enables you to specify the service you want to use.
- The message format is specified in the WSDL. You cannot use WebServicesAssembler to change the message format in top down Web service development.
- The WSDL cannot contain multiple message formats. Remove any ports from the WSDL that reference a binding with a message format that you do not want to use.

If you use nonstandard data types, as described in "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide and Table 4-1, ensure that the oracle-webservices.xml deployment descriptor defines how they will be handled. This file can be used to identify the name of the serialization class that converts the data between XML and Java, the name of the Java class that describes the Java representation of the data, and so on.

"oracle-webservices.xml Deployment Descriptor" provides more information on this deployment descriptor. "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on working with nonstandard data types
Decide whether you want to use wrapped or unwrapped parameters. To control this, WebServicesAssembler provides the unwrapParameters command-line option.

Generating the Web Service Top Down

The following steps illustrate how to assemble a Web service top down. The Web service will provide a logging facility that is defined by the WSDL stored at wsdl/LoggingFacility.wsdl.

Provide a WSDL from which the Web service will be generated as input to the WebServiceAssembler genInterface command. For example:
```
java -jar wsa.jar -genInterface 
                  -output build/src/service  
                  -wsdl wsdl/LoggingFacility.wsdl 
                  -unwrapParameters false 
                  -packageName oracle.demo.topdowndoclit.service 
                  -mappingFileName type-mapping.xml
```
At a minimum, specify the name of the WSDL. For more information on the required and optional arguments to genInterface, see "genInterface".

The WebServiceAssembler tool generates a Java interface for every port type specified in the WSDL, and a Java Bean for each complex type. The name of the directory that stores the generated interface is based on the values of the output and packageName arguments. For this example, the generated interface is stored in build/src/service/oracle/demo/topdowndoclit/service. The value types are stored in the specified output directory, but the package name is based on the type namespace or values in the J AX-RPC mapping file, type-mapping.xml.
Compile the generated interface and type classes. For example:
```
javac build/src/service/*.java -destdir build/classes 
```
Create the service endpoint implementation for your Web service.

The Java service endpoint must have a method signature that matches every method in the generated Java interface.
Compile the Java service endpoint.

For example, you can use the same command as in Step 2 if the Java service endpoint interface source was generated in the same directory where the Impl class was saved. If it was not, then you must change the value of the path argument.
Assemble the service by running the WebServiceAssembler tool with the topDownAssemble command. For example:
```
java -jar wsa.jar -topDownAssemble 
            -wsdl ./wsdl/LoggingFacility.wsdl 
            -unwrapParameters false 
            -className oracle.demo.topdowndoclit.service.DocLitLoggerImpl 
            -input build/classes/service 
            -output build 
            -ear dist/doclit_topdown.ear 
            -mappingFileName type-mapping.xml 
            -packageName oracle.demo.topdowndoclit.service 
            -fetchWsdlImports true 
            -classPath ./build/classes/client 
```
At a minimum, specify the name of the WSDL, the class name that implements the service, and the name of the output directory. The WebServiceAssembler tool outputs an EAR file, and a WAR file within the EAR. The WAR file contains the service artifacts, the implementation classes, the Web deployment descriptor (web.xml) and the JAX-RPC deployment descriptor (webservices.xml). For more information on the required and optional arguments to topDownAssemble, see "topDownAssemble".
Deploy the service.

Deploy the EAR file in the standard manner into a running instance of OC4J. For more information on deploying EAR files, see the Oracle Containers for J2EE Deployment Guide. The following is a sample deployment command.
```
java -jar <oc4jHome>/j2ee/home/admin_client.jar deployer:oc4j:localhost:port <user> <password> 
            -deploy 
            -file dist/doclit_topdown.ear 
            -deploymentName doclit_topdown 
            -bindWebApp default-web-site
```
The following list describes the parameters in this code example:
- <oc4j_Home>—the directory containing the OC4J installation.
- <user>—the user name for the OC4J instance. The user name is assigned at installation time.
- <password>—the password for the OC4J instance. The password is assigned at installation time.
- doclit_topdown—the name of the application.
- default-web-site—the Web site to which the application will be bound. This is usually default-web-site. To configure Web sites, see the server.xml file in <oc4j_home>/j2ee/home/config.
(Optional) Check that deployment succeeded. OracleAS Web Services provides a Web Service Home Page for each deployed Web service. See "Using the Web Services Home Page" for information on accessing and using the Web Service Home Page.
Generate the client code:
- For the J2SE environment, generate stubs (client proxies) for a J2SE Web service client by running the WebServicesAssembler tool with the genProxy command. For more information on generating and assembling client-side code for a J2SE Web service, see Chapter 14, "Assembling a J2SE Web Service Client".
- For the J2EE environment, generate a service endpoint interface and a JAX-RPC mapping file for a J2EE Web service client by running the WebServicesAssembler tool with the genInterface command. For more information on generating and assembling client-side code for a J2EE Web service, see Chapter 13, "Assembling a J2EE Web Service Client".
For example, the following command generates client proxies (stubs) that can be used for a J2SE client:
```
java -jar wsa.jar -genProxy 
                -wsdl http://localhost:8888/doclit_topdown/doclit_topdown?WSDL
                -unwrapParameters false  
                -output build/src/client 
                -packageName oracle.demo.topdowndoclit.stubs 
                -mappingFileName type-mapping.xml
```
In this example, doclit_topdown is an application name for the generated Web service.

At a minimum, specify the name of the WSDL and the name of the output directory. The WebServiceAssembler tool generates a stub. A client application uses the stub to invoke operations on a remote service. For more information on the required and optional arguments to genProxy, see "genProxy".
Compile and run the client.

List the appropriate JARs on the classpath before compiling the client. Table A-2, "Classpath Components for a Client Using a Client-Side Proxy" lists all of the JAR files that can possibly be used on the client classpath. As an alternative to listing individual JARs, you can include the client-side JAR, wsclient_extended.jar on the client classpath. This JAR file contains all the classes necessary to compile and run a Web service client. The classes are from the individual JAR files listed in Table A-2. See "Setting the Web Service Proxy Client Classpath" for more information on wsclient_extended.jar and the client classpath.

Generating a Web Service Top Down with Ant Tasks

The current release supports Ant tasks for Web services development. The following examples show how the WebServiceAssembler commands in the preceding examples can be rewritten as Ant tasks.

In these examples, doclit_topdown is an application name for the generated Web service.

For more information on Ant tasks for WebServiceAssembler commands, see "WebServicesAssembler Commands".

For the genInterface command, here is an example Ant task:

<oracle:genInterface wsdl="wsdl/LoggingFacility.wsdl" 
              output= "build/src/service"   
              packageName= "oracle.demo.topdowndoclit.service" 
              mappingFileName="type-mapping.xml" 
              dataBinding="true" 
              unwrapParameters="false"
/oracle:genInterface>

For the topDownAssemble command, here is an example Ant task:

<oracle:topDownAssemble appName="doclit_topdown"
         wsdl="./wsdl/LoggingFacility.wsdl"
         unwrapParameters="false"
         input="build/classes/service "
         output="build"
         ear="dist/doclit_topdown.ear"
         mappingFileName="type-mapping.xml"
         packageName="oracle.demo.topdowndoclit.service"
         fetchWsdlImports="true"
         >
            <oracle:portType
               className="oracle.demo.topdowndoclit.service.DocLitLoggerImpl"
            </oracle:portType>
  />

For the genProxy command, here is an example Ant task:

<oracle:genProxy
    wsdl="http://localhost:8888/doclit_topdown/doclit_topdown?WSDL"
    unwrapParameters="false"
    output="build/src/client"
    packageName="oracle.demo.topdowndoclit.stubs"
    mappingFileName="type-mapping.xml"
/>

Limitations

See "Assembling Web Services from a WSDL".

Additional Information

For more information on:

using the Home Page to test Web service deployment, see Chapter 12, "Testing Web Service Deployment".
building a J2EE client, see Chapter 13, "Assembling a J2EE Web Service Client".
building a J2SE client, see Chapter 14, "Assembling a J2SE Web Service Client".
JAX-RPC handlers, see Chapter 15, "Understanding JAX-RPC Handlers".
using the WebServicesAssembler tool to assemble Web services, see Chapter 17, "Using WebServicesAssembler".
packaging and deploying Web services, see Chapter 18, "Packaging and Deploying Web Services".
Web services interoperability, see "Ensuring interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
using quality of service features in Web service clients, see "Managing Web Service" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding security to a Web service, see the Oracle Application Server Web Services Security Guide.
adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.
processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.
data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
JDeveloper tool support for Web service development, see the JDeveloper on-line help.