6 Assembling a Web Service from 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.

Understanding 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.

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.

These are the 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. "Steps for Assembling the Web Service Top Down" provides more detail on each of these steps.

How to Assemble a Web Service Top Down

This section contains the following subsections:

Prerequisites
Steps for Assembling the Web Service Top Down

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.
- 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.
- National Language Support (also known as "NLS" or "Globalization Support") characters that occur in names in the WSDL, such as in the name of a service, port type, operation, binding or port, are not supported. This may also result in errors during code generation or in the Web Services Test Page.

Decide whether you want to use wrapped or unwrapped parameters. To control this, WebServicesAssembler provides the unwrapParameters command-line option.
If you use nonstandard data types, 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.
See Also:
- Chapter 18, "Using WebServicesAssembler" provides descriptions of WebServicesAssembler commands and arguments.
- "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide and Table 5-1 for more information on using non-standard data types.
- Appendix C, "oracle-webservices.xml Deployment Descriptor Schema" provides more information on this file.
- "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

Steps for Assembling 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.

Command line:
```
java -jar wsa.jar -genInterface 
                  -output build/src/service  
                  -wsdl wsdl/LoggingFacility.wsdl 
                  -unwrapParameters false 
                  -packageName oracle.demo.topdowndoclit.service 
                  -mappingFileName type-mapping.xml
```
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"
/>
```
In this command line and Ant task:
- genInterface—Creates a service endpoint interface for each port type and a Java value type class (beans) for any complex type defined in a WSDL. It also creates a JAX-RPC mapping file that describes the mapping between the XML schema types and the Java value type classes. See "genInterface".
- output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See"output".
- wsdl—Specifies the absolute file path, relative file path, or URL to a WSDL document. See "wsdl".
- unwrapParameters—When set to false the generated service endpoint interface will be generated with wrappers around the input parameter and the return type. See "unwrapParameters".
- packageName—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. See "packageName".
- mappingFileName—Specifies a file location that points to a JAX-RPC mapping file. See "mappingFileName".
- dataBinding—If true, WebServicesAssembler will attempt to generate Java value types that follow the JAX-RPC default type mapping rules for every element in the schema. See "dataBinding".
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. This example assumes that you are creating the service in the file DocLitLoggerImpl.java.
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 classpath argument.
Assemble the service by running the WebServiceAssembler tool with the topDownAssemble command. In this example, doclit_topdown is an application name for the generated Web service. For example:

Command line:
```
java -jar wsa.jar -topDownAssemble 
            -appName doclit_topdown
            -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 
```
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:topDownAssemble>
```
In this command and Ant task:
- topDownAssemble—Creates the required classes and deployment descriptors for a Web service based on a WSDL description. The files can be stored in either an EAR file, a WAR file, or a directory. See "topDownAssemble".
- appName—Specifies the name of an application. Usually, this name is used as a base value for other arguments like context and uri. See "appName".
- wsdl—Specifies the absolute file path, relative file path, or URL to a WSDL document. See "wsdl".
- unwrapParameters—When set to false the generated service endpoint interface will be generated with wrappers around the input parameter and the return type. See "unwrapParameters".
- input—Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes. This argument will be added to the classpath used by the WebServicesAssembler. See "input".
- output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".
- ear—Specifies the name and location of the generated EAR. See "ear".
- mappingFileName—Specifies a file location that points to a JAX-RPC mapping file. See "mappingFileName".
- packageName—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. See "packageName".
- fetchWsdlImports—Indicates if you want to make a local copy of the WSDL and everything it imports. See "fetchWsdlImports".
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 Test Page for each deployed Web service. See "How to Use the Web Services Test Page" for information on accessing and using the Web Service Test 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 15, "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 14, "Assembling a J2EE Web Service Client".
For example, the following command assembles client proxies (stubs) that can be used for a J2SE client. In this example, doclit_topdown is an application name for the generated Web service.

Command line:
```
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
```
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"
/>
```
In this command and Ant task:
- genProxy—Creates a static proxy stub that can be used by a J2SE Web service client. See "genProxy".
- wsdl—Specifies the absolute file path, relative file path, or URL to a WSDL document. See "wsdl".
- unwrapParameters—When set to false the generated service endpoint interface will be generated with wrappers around the input parameter and the return type. See "unwrapParameters".
- output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".
- packageName—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. See "packageName".
- mappingFileName—Specifies a file location that points to a JAX-RPC mapping file. See "mappingFileName".
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 Classpath for a Web Service Proxy" for more information on wsclient_extended.jar and the client classpath.

Limitations

See "Assembling Web Services from a WSDL".

Additional Information

For more information on:

using the Test Page to test Web service deployment, see Chapter 13, "Testing Web Services Deployment".
building a J2EE client, see Chapter 14, "Assembling a J2EE Web Service Client".
building a J2SE client, see Chapter 15, "Assembling a J2SE Web Service Client".
JAX-RPC handlers, see Chapter 16, "Using JAX-RPC Handlers".
using the WebServicesAssembler tool to assemble Web services, see Chapter 18, "Using WebServicesAssembler".
packaging and deploying Web services, see Chapter 19, "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.
Oracle JDeveloper tool support for Web service development, see the Oracle JDeveloper on-line help.