Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Assembling WebLogic Web Services Using Ant Tasks

The following sections describe how to assemble and deploy WebLogic Web Services using a variety of Ant tasks:

- Overview of Assembling WebLogic Web Services Using Ant Tasks
- Assembling WebLogic Web Services Using the servicegen Ant Task
- Assembling WebLogic Web Services Using Individual Ant Tasks
- The Web Service EAR File Package
- Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks
- Non-Roundtripping of Generated Data Type Components
- Deploying and Testing WebLogic Web Services

# Overview of Assembling WebLogic Web Services Using Ant Tasks

Assembling a WebLogic Web Service refers to gathering all the components of the service (such as the EJB JAR file, the SOAP message handler classes, and so on), generating the `web-services.xml` deployment descriptor file, and packaging everything into an Enterprise Application Archive (EAR) file that can be deployed on WebLogic Server.

There are two ways to assemble a WebLogic Web Service using Ant tasks:

- Using the `servicegen` Ant task, which performs all assembly steps for you.

The `servicegen` Ant takes as input an EJB JAR file (for EJB-implemented Web Services) or a list of Java classes (for Java class-implemented Web Services), and based on information after introspecting the Java code and the attributes of the Ant task, it automatically generates all the components that make up a WebLogic Web Service and packages them into an EAR file.

For detailed information, see Assembling WebLogic Web Services Using the servicegen Ant Task.

- Using a variety of narrowly-focused Ant tasks, such as `autotype`, `source2wsdd`, and so on.

Typically, the `servicegen` Ant task is adequate for assembling most WebLogic Web Services. If, however, you want more control over how your Web Service is assembled, you can use a set of narrowly-focused Ant tasks instead. For example, you can use the `source2wsdd` to generate the `web-services.xml` file, and then you can update this file manually if you want to add more information.

For detailed information, see Assembling WebLogic Web Services Using Individual Ant Tasks.

For detailed reference information on the Web Services Ant tasks, see Web Service Ant Tasks and Command-Line Utilities.

Note: The Java Ant utility included in WebLogic Server uses the `ant` (UNIX) or `ant.bat` (Windows) configuration files in the `WL_HOME``\server\bin` directory to set various Ant-specific variables, where `WL_HOME` is the top-level directory of your WebLogic Platform installation If you need to update these Ant variables, make the relevant changes to the appropriate file for your operating system.

# Examples of Assembling WebLogic Web Services

WebLogic Server includes examples of assembling WebLogic Web Services in the `WL_HOME``/samples/server/examples/src/examples/webservices` directory, where `WL_HOME` refers to the main WebLogic Platform directory. For detailed instructions on how to build and run the examples, open the following Web page in your browser:

>     WL_HOME/samples/server/examples/src/examples/webservices/package-summary.html

# Assembling WebLogic Web Services Using the servicegen Ant Task

The `servicegen` Ant task takes as input an EJB JAR file or list of Java classes, creates all the needed Web Service components, and packages them into a deployable EAR file.

## What the servicegen Ant Task Does

In particular, the `servicegen` Ant task:

- Introspects the Java code, looking for public methods to convert into Web Service operations and non-built-in data types used as parameters or return values of the methods.
- Creates a `web-services.xml` deployment descriptor file, based on the attributes of the `servicegen` Ant task and introspected EJB or Java class information.
- Optionally creates the serialization class that convert the non-built-in data between its XML and Java representations. It also creates XML Schema representations of the Java objects and updates the `web-services.xml` file accordingly. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.
- Packages all the Web Service components into a Web application WAR file, then packages the WAR and EJB JAR files into a deployable EAR file.

## Assembling WebLogic Web Services Automatically: Main Steps

To assemble a Web Service automatically using the `servicegen` Ant task:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a staging directory to hold the components of your Web Service.
3. If the Web Service operations are implemented with EJBs, package them, along with any supporting EJBs, into an EJB JAR file. If the operations are implemented with Java classes, compile them into class files.

For detailed information, refer to Developing WebLogic Server Applications.

4. Copy the EJB JAR file and/or Java class files to the staging directory.
5. In the staging directory, create the Ant build file (called `build.xml` by default) that contains a call to the `servicegen` Ant task.

For details about specifying the `servicegen` Ant task, see Creating the Build File That Specifies the servicegen Ant Task.

For general information about creating Ant build files, see http://jakarta.apache.org/ant/manual/.

Note: The Apache Jakarta Web site publishes online documentation for only the most current version of Ant, which might be different from the version of Ant that is bundled with WebLogic Server. To determine the version of Ant that is bundled with WebLogic Server, run the following command after setting your WebLogic environment:

>     prompt> ant -version

To view the documentation for a specific version of Ant, download the Ant zip file from http://archive.apache.org/dist/ant/binaries/ and extract the documentation.

6. If you previously used the `autotype` Ant task to generate non-built-in data type information from an existing XML Schema file, and then used the `typeMappingFile` attribute of the `servicegen` Ant task to specify the `types.xml` file generated by `autotype` and merge it with any `servicegen`-generated information, and the original XML Schema file uses the `<include>` element to include additional XML Schema files, you must copy these XML Schema files to the root directory of the Web Service Web application WAR file of the generated EAR file. You can use the `wspackage` Ant task do perform this step.

If you are using the `servicegen` Ant task exclusively to generate non-built-in data type components, then you do not need to perform this step.

For details, see Running the wspackage Ant task.

7. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the staging directory, optionally passing the command a target argument (if you have created the `build.xml` file to take arguments):

>     prompt> ant

The Ant task generates the Web Services EAR file in the staging directory which you can then deploy on WebLogic Server.

## Creating the Build File That Specifies the servicegen Ant Task

The following sample `build.xml`, file taken from the `examples.webservices.basic.statelessession` product example, specifies that you will run the `servicegen` Ant task:

>     <project name="buildWebservice" default="ear">
>       <target name="ear">
>         <servicegen
>            destEar="ws_basic_statelessSession.ear"
>            contextURI="WebServices" >
>            <service
>              ejbJar="HelloWorldEJB.jar"
>              targetNamespace="http://www.bea.com/webservices/basic/statelesSession"
>              serviceName="HelloWorldEJB"
>              serviceURI="/HelloWorldEJB"
>              generateTypes="True"
>              expandMethods="True"
>              style="rpc" >
>            </service>
>          </servicegen>
>       </target>
>     </project>

In the example, the `servicegen` Ant task creates one Web Service called `HelloWorldEJB`. The URI to identify this Web Service is`/HelloWorldEJB`; the full URL to access the Web Service is

>     http://host:port/WebServices/HelloWorldEJB

The `servicegen` Ant task packages the Web Service in an EAR file called ws_basic_statelessSession.ear, as specified by the `destEar` attribute. The EAR file contains a WAR file called `web-services.war` (default name) that contains all the Web Service components, such as the `web-services.xml` deployment descriptor file.

Because the `generateTypes` attribute is set to `True`, the WAR file also contains the serialization class for any non-built-in data types used as parameters or return values to the EJB methods. The Ant task introspects the EJBs contained in the HelloWorldEJB.jar file, looking for public operations and non-built-in data types, and updates the `web-services.xml` operation and data type mapping sections accordingly. Because the `expandMethods` attribute is also set to `True`, the Ant task lists each public EJB method as a separate operation in the `web-services.xml` file.

The `style="rpc"` attribute specifies that the operations in the Web Service are all RPC-oriented. If the operations in your Web Service are document-oriented, specify `style="document"`.

Note: BEA recommends that you create an exploded directory, rather than an EAR file, by specifying a value for the `destEar` attribute of `servicegen` that does not have an `.ear` suffix. You can later package the exploded directory into an EAR file when you are ready to deploy the Web Service.

# Assembling WebLogic Web Services Using Individual Ant Tasks

Typically, the `servicegen` Ant task is adequate for assembling most WebLogic Web Services. If, however, you want more control over how your Web Service is assembled, you can use a set of narrowly-focused Ant tasks instead. For example, you can use the `source2wsdd` to generate the `web-services.xml` file, and then you can update this file manually if you want to add more information.

The following sections describe two ways to assemble a Web Service, based on whether you started with Java or with an XML Schema:

- Assembling a Web Service Starting with Java
- Assembling a Web Service Starting with an XML Schema

## Assembling a Web Service Starting with Java

In the following procedure, it is assumed that you have already implemented your Web Service by writing the Java code of the back-end components and non-built-in data types, and you want to use individual Ant tasks to generate the XML Schema that represents the non-built-in data types, as well as the other Web Service components such as the `web-services.xml` deployment descriptor file.

1. Package or compile the Java back-end components that implement the Web Service into their respective packages. For example, package stateless session EJBs into an EJB JAR file and Java classes into class files.

For detailed instructions, see Developing WebLogic Server Applications.

2. Create the Web Service deployment descriptor file (`web-services.xml`).

If you implemented your Web Service with a stateless session EJB or a Java class, you can use the `source2wsdd` Ant task to generate a `web-services.xml` file. For details, see Running the source2wsdd Ant Task.

If you used the `wsdl2Service` Ant task to generate a partial implementation of a Web Service from an existing WSDL file, then the Ant task already generated a `web-services.xml` file for you. For details, see Generating a Partial Implementation From a WSDL File.

3. If your Web Service uses non-built-in data types, create all the needed components, such as the serialization class and the XML Schema, by using the `autotype` Ant task to generate these components automatically, as described in Running the autotype Ant Task.
4. Optionally create a client JAR file using the `clientgen` Ant task.

See Running the clientgen Ant Task.

5. Package all components into a deployable EAR file by using the `wspackage` Ant task, as described in Running the wspackage Ant task.

## Assembling a Web Service Starting with an XML Schema

In the following procedure, it is assumed that you are starting with an XML Schema that describes the non-built-in data types of your Web Service, and you want to use the individual Ant tasks to generate the equivalent Java representation of the data types. You then use these generated Java classes to write the back-end component that implements your Web Service, then use Ant tasks to generate the remaining components, such as the `web-services.xml` file. It is assumed that you want to preserve the original XML Schema all the way through the development process, so that at the end, when you deploy the Web Service, the published WSDL contains the exact same XML Schema with which you stared.

1. Run the `autotype` Ant task to generate the Java representations of the non-built-in data types in the XML Schema file. The Ant task also generates the serialization class used to convert the data between XML and Java and the data type mapping file. Use the `schemaFile` attribute of the `autotype` Ant task to specify the name of the file that contains your XML Schema.

For details, see Running the autotype Ant Task.

2. Write the Java code for the stateless session EJB or Java class back-end component that implements your Web Service. Use the Java classes generated by the `autotype` Ant task in the preceding step for the non-built-in data types (originally described in the XML Schema file from which you started) used as parameters or return values of the methods.

For details, see Writing the Java Code for the Components.

3. If necessary, re-run the `autotype` Ant task against your EJB or Java class to generate the non-built-in data type components for any new data types you might have created that are not included in the original XML Schema file. Use the `javaComponents` attribute of the `autotype` Ant task to specify the back-end component you wrote in Step 2.

Be sure you also use the `typeMappingFile` attribute to specify the existing data type mapping file, generated from the first execution of the `autotype` Ant task in Step 1. The `autotype` Ant task merges the existing XML Schema with any generated one, thus preserving the original XML Schema.

For details, see Running the autotype Ant Task.

4. Run the `source2wsdd` Ant task to generate the `web-services.xml` deployment descriptor. If you re-ran the `autotype` Ant task to create a merged data type mapping file, be sure you specify this final file with the `typesInfo` attribute.

For details, see Running the source2wsdd Ant Task.

5. Optionally create a client JAR file by running the `clientgen` Ant task.

For details, see Running the clientgen Ant Task.

6. Package all components into a deployable EAR file by using the `wspackage` Ant task.

If the original XML Schema file from which you originally started uses one or more `<include>` elements to include additional XML Schema files, be sure you explicitly copy these files to the root directory of the Web Service Web application WAR file, located by default in the root directory of the EAR file and called `web-services.war`.

For details and examples of a variety of ways to use the `wspackage` Ant task, see Running the wspackage Ant task.

## Running the source2wsdd Ant Task

Use the `source2wsdd` Ant task to generate a `web-services.xml` deployment descriptor file from the stateless session EJB or Java source file that implements a Web Service.

To run the `source2wsdd` Ant task:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a file called `build.xml` that contains a call to the `source2wsdd` Ant task. For details, see the examples later in this section.
3. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the same directory as the`build.xml` file:

>     prompt> ant

For reference information about the `source2wsdd` Ant task, see source2wsdd.

The following example shows a simple `build.xml` file.

Listing 6-1 Simple Source2wsdd build.xml File For a Java Source File

>     <project name="buildWebservice" default="generate-typeinfo">
>        <target name="generate-typeinfot">
>           <source2wsdd
>                javaSource="source/MyService.java"
>                typesInfo="autotype/types.xml"
>                ddFile="ddfiles/web-services.xml"
>                serviceURI="/MyService" />
>     </project>

When you run the `source2wsdd` Ant task using the preceding `build.xml` file, the Ant task generates a `web-services.xml` file from the Java source file `source/MyService.java`. It uses non-built-in data type information from the `autotype/types.xml` file; this information includes the XML Schema representation of non-built-in data types used as parameters or return values in your Web Service, as well as data type mapping information that specifies the location of the serialization class, and so on. You typically generate the `types.xml` file using the `autotype` Ant task.

The `source2wsdd` Ant task outputs the generated deployment descriptor information into the file `ddfiles/web-services.xml`. The URI of the Web Service is `/MyService`, used in the full URL that invokes the Web Service once it is deployed.

The following example shows how to generate both a `web-services.xml` file and the WSDL file (called `wsdFiles/Temperature.wsdl`) that describes a stateless session EJB-implemented Web Service. Because the `ejbLink` attribute is specified, the `javaSource` attribute must point to the EJB source file. The `source2wsdd` Ant task uses the value of the `ejbLink` attribute as the value of the `<ejb-link>` child element of the `<stateless-ejb>` element in the generated `web-services.xml` file.

Listing 6-2 Source2wsdd build.xml File for an EJB

>     <source2wsdd
>     	javaSource="source/TemperatureService.java"
>     	ejbLink="TemperatureService.jar#TemperatureServiceEJB"
>     	ddFile="ddfiles/web-services.xml"
>     	typesInfo="autotype/types.xml"
>     	serviceURI="/TemperatureService"
>     	wsdlFile="wsdlFiles/Temperature.wsdl"
>     />

## Running the autotype Ant Task

Use the `autotype` Ant task to generate non-built-in data type components, such as the serialization class. For the list of supported non-built-in data types, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.

To run the `autotype` Ant task:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a file called `build.xml` that contains a call to the `autotype` Ant task. For details, see the examples later in this section.
3. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the same directory as the`build.xml` file:

>     prompt> ant

For reference information about the `autotype` Ant task, see autotype.

The following example shows a simple `build.xml` file.

Listing 6-3 Autotype build.xml File For a Java Class

>     <project name="buildWebservice" default="generate-typeinfo">
>        <target name="generate-typeinfot">
>          <autotype  javatypes="mypackage.MyType"
>                     targetNamespace="http://www.foobar.com/autotyper"
>                     packageName="a.package.name"
>                     destDir="output" />
>        </target>
>     </project>

When you run the `autotype` Ant task using the preceding `build.xml` file, the Ant task creates the non-built-in data type components for a Java class called `mypackage.MyType`. The package name used in the generated serialization class is `a.package.name`. The serialization Java class and XML schema information is generated and placed in the `output` directory. The generated XML Schema and type-mapping information are in a file called `types.xml` in this output directory.

The following excerpt from a sample `build.xml` file shows another way to use the `autotype` task

Listing 6-4 Autotype build.xml File For Starting with WSDL

>     <autotype  wsdl="file:/wsdls/myWSDL"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="output" />

The preceding example is similar to the first, except that instead of starting with a Java representation of a data type, the example starts with an XML Schema representation embedded within the WSDL of a Web Service. In this case, the task generates the corresponding Java representation.

Similarly, if you want to start from an XML Schema file and generate the corresponding Java components, use the `schemaFile` attribute, as shown in the following example.

Listing 6-5 Autotype build.xml File for Starting with XML Schema

>     <autotype  schemaFile="file:/schemas/mySchema.xsd"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="output" />

In the preceding example, the XML Schema in the `mySchema.xsd` file is copied, without any changes, to the `output/types.xml` file that contains the data type mapping information.

The following example shows how to both generate non-built-in data type components for newly implemented Java data types, and carry forward already generated components.

Listing 6-6 Autotype build.xml File That Carries Forward Existing Components

>     <autotype  javaComponents="my.superService"
>                typeMappingFile="file:/mapfiles/types.xml"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="output" />

In the preceding example, it is assumed that you have previously run the `autotype` Ant task against an XML Schema file and generated the corresponding Java data types and data type mapping file. It is further assumed that you then used these data types to implement a stateless session EJB back-end component, and during that process, you created additional Java data types and want to use the `autotype` Ant task to generate the corresponding XML Schema. However, you want to preserve the original XML Schema from which you started, and carry it forward into the newly generated `types.xml` file. The example uses the `javaComponents` attribute to specify the EJB which has the new Java data types and the `typeMappingFile` attribute to specify the existing file that contains the XML Schema for data types that you do not want regenerated. The Ant task merges the existing data type mapping information in the `file:/mapfiles/types.xml` file with the generated information, and writes the result to the `output/types.xml` file.

## Running the clientgen Ant Task

To run the `clientgen` Ant task and automatically generate a client JAR file:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a file called `build.xml` that contains a call to the `clientgen` Ant task. For details, see the examples later in this section.
3. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the same directory as the`build.xml` file:

>     prompt> ant

For reference information about the `clientgen` Ant task, see clientgen.

The following example shows a simple `build.xml` file.

Listing 6-7 Clientgen build.xml File For Generating Client From EAR File

>     <project name="buildWebservice" default="generate-client">
>        <target name="generate-client">
>           <clientgen ear="myapps/myapp.ear"
>                      serviceName="myService"
>                      packageName="myapp.myservice.client"
>                      useServerTypes="True"
>                      clientJar="myapps/myService_client.jar" />
>        </target>
>     </project>

When you run the `clientgen` Ant task using the preceding `build.xml` file, the Ant task creates the `myapps/myService_client.jar` client JAR file that contains the service-specific client interfaces and stubs and the serialization class used to invoke the WebLogic Web Service called `myService` contained in the EAR file `myapps/myapp.ear`. It packages the client interface and stub files into a package called `myapp.myservice.client`. The `useServerTypes` attribute specifies that the `clientgen` Ant task should get the Java implementation of all non-built-in data types used in the Web Service from the `myapps/myapp.ear` file rather than generating Java code to implement the data types.

The following excerpt from a sample `build.xml` file shows another way to use the `clientgen` task.

Listing 6-8 Clientgen build.xml File For Generating Client From a WSDL File

>     <clientgen wsdl="http://example.com/myapp/myservice.wsdl"
>                packageName="myapp.myservice.client"
>                clientJar="myapps/myService_client.jar"
>     />

In the example, the `clientgen` task creates a client JAR file (called `myapps/myService_client.jar`) to invoke the Web Service described in the `http://example.com/myapp/myservice.wsdl` WSDL file. It packages the interface and stub files in the `myapp.myservice.client` package.

## Running the wspackage Ant task

Use the `wspackage` Ant task to package the various components of a Web Service into a new deployable EAR file or to add additional components to an existing EAR file.

To run the `wspackage` Ant task, follow these steps:

1. Set your environment.

On Windows NT, execute the `setEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``\user_projects\domains\domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

On UNIX, execute the `setEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `BEA_HOME``/user_projects/domains/domainName`, where `BEA_HOME` is the top-level installation directory of the BEA products and `domainName` is the name of your domain.

2. Create a file called `build.xml` that contains a call to the `wspackage` Ant task. For details, see the examples later in this section.
3. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the same directory as the`build.xml` file:

>     prompt> ant

For reference information about the `wspackage` Ant task, see wspackage.

The following example shows a simple `build.xml` file for creating a new deployable EAR file for a Java class-implemented Web Service.

Listing 6-9 Wspackage build.xml File for a Java Class

>     <project name="buildWebservice" default="package-up">
>        <target name="package-up">
>           <wspackage
>                output="ears/myWebService.ear"
>                contextURI="web_services"
>                codecDir="autotype"
>                webAppClasses="example.ws2j.service.SimpleTest"
>                ddFile="ddfiles/web-services.xml" />

>     </project>

When you run the `wspackage` Ant task using the preceding `build.xml` file, the Ant task creates an EAR file called `ears/myWebService.ear`. The context URI of the Web Service, used in the full URL that invokes it, is `web_services`. The class file that contains the serialization class for the non-built-in data types is located in the `autotype` directory. The Java class that implements the Web Service is called `example.ws2j.service.SimpleTest` and will be packaged in the `WEB-INF/classes` directory of the Web application. Finally, the existing deployment descriptor file is `ddfiles/web-services.xml`.

The following example shows another `build.xml` file for adding additional components to an existing EAR file.

Listing 6-10 Wspackage build.xml File For Adding Additional Components to EAR File

>     <project name="buildWebservice" default="package-up">
>        <target name="package-up">
>           <wspackage
>                output="ears/myWebService.ear"
>                overwrite="false"
>                filesToEar="myEJB2.jar"
>            />
>     </project>

In the example, the `wspackage` Ant task adds the file `myEJB2.jar` to the root directory of the existing EAR file called `ears/myWebService.ear`. The `overwrite` attribute is set to `false` to ensure that none of the existing components in the `ears/myWebService.ear` file are overwritten; be sure you always do this when using the `wspackage` Ant task to add additional files to an EAR file.

The following example is similar to the preceding one in that it adds additional components to an existing EAR, but in this case it adds XML Schema files to the root directory of the existing WAR file. You must use the following syntax if you originally used the `autotype` Ant task to generate non-built-in data type components from an XML Schema file, and this Schema file contains one or more `<include>` elements to include additional XML Schema files. When you package the final Web Service into an archive, you must manually add both the original and included XML Schema files to the WAR file.

Listing 6-11 Wspackage build.xml File For Adding Schema Files to the WAR File of an EAR

>     <project name="buildWebservice" default="package-up">
>        <target name="package-up">
>           <wspackage
>                output="ears/myWebService.ear"
>                overwrite="false"
>                warName="myservice.war"
>                filesToWar="original_schema.xsd,included_schema.xsd"
>            />
>     </project>

In the example, the `wspackage` Ant task adds the XML Schema files `original_schema.xsd` and `included_schema.xsd` to the root directory of the existing WAR file called `myservice.war`, located in the root directory of the EAR file called `ears/myWebService.ear`.

# The Web Service EAR File Package

Web Services are packaged into standard Enterprise Application EAR files that contain a Web application WAR file along with the EJB JAR files.

The following graphic shows the hierarchy of a typical WebLogic Web Services EAR file.

Figure 6-1 Hierarchy of WebLogic Web Services EAR File

# Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks

The tables in the following sections list the non-built-in XML and Java data types for which the `servicegen` and `autotype` Ant tasks can generate data type components, such as the serialization class, the Java or XML representation, and so on.

If your XML or Java data type is not listed in these tables, and it is not one of the built-in data types listed in Supported Built-In Data Types, then you must create the non-built-in data type components manually. For details, see Using Non-Built-In Data Types.

Warning: The serialization class and Java and XML representations generated by the `autotype`, `servicegen`, and `clientgen` Ant tasks cannot be round-tripped. For more information, see Non-Roundtripping of Generated Data Type Components.

For information on the ways that WebLogic Web Services are non-compliant with the JAX-RPC specification with respect to data types, see Data Type Non-Compliance with JAX-RPC.

## Supported XML Non-Built-In Data Types

The following table lists the supported XML Schema non-built-in data types. If your XML data type is listed in the table, then the `servicegen` and `autotype` Ant tasks can generate the serialization class to convert the data between its XML and Java representations, as well as the Java representation and type mapping information for the `web-services.xml` deployment descriptor.

For details and examples of the data types, see the JAX-RPC specification.

Table 6-1 Supported Non-Built-In XML Schema Data Types

XML Schema Data Type | Equivalent Java Data Type or Mapping Mechanism
--- | ---
Enumeration | Typesafe enumeration pattern. For details, see Section 4.2.4 of the JAX-RPC specification.
`<xsd:complexType>` with elements of both simple and complex types. | JavaBean
`<xsd:complexType>` with simple content. | JavaBean
`<xsd:attribute>` in `<xsd:complexType>` | Property of a JavaBean
Derivation of new simple types by restriction of an existing simple type. | Equivalent Java data type of simple type.
Facets used with restriction element. Note: The base primitive type must be one of the following: `string`, `decimal`, `float`, or `double`. Pattern facet is not enforced. | Restriction enforced during serialization and deserialization.
`<xsd:list>` | Array of the list data type.
Array derived from `soapenc:Array` by restriction using the `wsdl:arrayType` attribute. | Array of the Java equivalent of the `arrayType` data type.
Array derived from `soapenc:Array` by restriction. | Array of Java equivalent.
Derivation of a complex type from a simple type. | JavaBean with a property called `simpleContent` of type `String`.
`<xsd:anyType>` | java.lang.Object.
`<xsd:nil>` and `<xsd:nillable>` attribute | Java `null` value. If the XML data type is built-in and usually maps to a Java primitive data type (such as `int` or `short`), then the XML data type is actually mapped to the equivalent object wrapper type (such as `java.lang.Integer` or `java.lang.Short`).
Derivation of complex types by extension | Mapped using Java inheritance.
Abstract types | Abstract Java data type.

## Supported Java Non-Built-In Data Types

The following table lists the supported Java non-built-in data types. If your Java data type is listed in the table, then the `servicegen` and `autotype` Ant tasks can generate the serialization class to convert the data between its Java and XML representations.

Table 6-2 Supported Non-Built-In Java Data Types

Java Data Type | Equivalent XML Schema Data Type
--- | ---
Array of any supported data type. | SOAP Array.
JavaBean whose properties are any supported data type. | <xsd:sequence>
java.util.List | SOAP Array.
java.util.ArrayList | SOAP Array.
java.util.LinkedList | SOAP Array.
java.util.Vector | SOAP Array.
java.util.Stack | SOAP Array.
java.util.Collection | SOAP Array.
java.util.Set | SOAP Array.
java.util.HashSet | SOAP Array.
java.util.SortedSet | SOAP Array.
java.util.TreeSet | SOAP Array
java.lang.Object Note: The data type of the runtime object must be a known type: either a built-in data type or one that has type mapping information. | <xsd:anyType>
JAX-RPC-style enumeration class | <xsd:simpleType> with enumeration facets

## Data Type Non-Compliance with JAX-RPC

The `autotype` Ant task does not comply with the JAX-RPC specification if the XML Schema data type (for which it is generating the Java representation) has all the following characteristics:

- The data type is a `complexType`.
- The `complexType` contains a single `sequence`.
- The `sequence` contains a single `element` with `maxOccurs` greater than 1 or unbounded.

The following example shows such an XML Schema data type:

>     <xsd:complexType name="Response">
>         <xsd:sequence >
>             <xsd:element name="code" type="xsd:string" maxOccurs="10" />
>         </xsd:sequence>
>     </xsd:complexType>

The `autotype` Ant task maps this type of XML Schema data type directly to a Java array of the specified element. In the previous example, the `autotype` Ant task maps the `Response` XML Schema data type to a `java.lang.String[]` Java type. This is similar to the type of mapping that .NET does.

The JAX-RPC specification, in turn, states that this type of XML Schema data type should map to a Java array with a pair of setter and getter methods in a JavaBean class. WebLogic Web Services do not follow this last part of the specification.

# Non-Roundtripping of Generated Data Type Components

When you use the `servicegen` or `autotype` Ant tasks to create the serialization class and Java or XML representation of non-built-in data types, note that the process cannot be round-tripped. This means that if, for example, you use the `autotype` Ant task to generate the Java representation of an XML Schema data type, and then use `autotype` to create an XML Schema data type from the generated Java type, the original and generated XML Schema data type will not necessarily look the same, although they both describe the same XML data. This is also true if you start from Java, generate an XML Schema, then generate a new Java data type from the generated XML Schema: the original and generated Java type will not necessarily look exactly the same. For example, the original and generated Java type might list the parameters of the constructor in a different order.

This behavior has a variety of repercussions. For example, assume you are developing a Web Service from an existing stateless session EJB that uses non-built-in data types. You use the `autotype` Ant task to generate the serialization class and Java and XML representation of the data types and you use this generated code in your server-side code that implements your Web Service. Later you use the `clientgen` Ant task to generate the Web Service-specific client JAR file, which also includes a serialization class and the Java representation of the non-built-in data types. However, because `clientgen` by default generates these components from the WSDL of the Web Service (and thus from an XML Schema), the `clientgen`-generated client-side Java representation might look different from the `autotype`-generated server-side Java code. This means that you might not necessarily be able to reuse any server-side code that handles the data type in your client application. If you want the `clientgen` Ant task to always use the generated serialization class and code from the WebLogic Web Service EAR file, specify the `useServerTypes` attribute.

# Deploying and Testing WebLogic Web Services

Deploying a WebLogic Web Service refers to making it available to remote clients. Because WebLogic Web Services are packaged as standard J2EE Enterprise applications, deploying a Web Service is the same as deploying an Enterprise application.

For detailed information on deploying Enterprise applications, see Deploying WebLogic Server Applications.

You can use the WebLogic Web Services Home Page to test your Web Services, as described in WebLogic Web Services Home Page and WSDL URLs.

## WebLogic Web Services Home Page and WSDL URLs

Every Web Service deployed on WebLogic Server has a Home Page. From the Home page you can:

- View the WSDL that describes the service.
- Test each operation to ensure that it is working correctly.
- View the SOAP request and response messages from a successful test of an operation.

Note: You cannot use two-way SSL when testing a Web Service from its Home Page.

The following URLs show first how to invoke the Web Service Home page and then the WSDL in your browser:

>     [protocol]://[host]:[port]/[contextURI]/[serviceURI]

>     [protocol]://[host]:[port]/[contextURI]/[serviceURI]?WSDL

where:

- protocol refers to the protocol over which the service is invoked, either HTTP or HTTPS. This value corresponds to the `protocol` attribute of the `<web-service>` element that describes the Web Service in the `web-servicex.xml` file. If you used the `servicegen` Ant task to assemble your Web Service, this value corresponds to the `protocol` attribute.
- host refers to the computer on which WebLogic Server is running.
- port refers to the port number on which WebLogic Server is listening (default value is `7001`).
- contextURI refers to the context root of the Web application, corresponding to the `<context-root>` element in the `application.xml` deployment descriptor of the EAR file. If you used the `servicegen` Ant task to assemble your Web Service, this value corresponds to the `contextURI` attribute.

If your `application.xml` file does not include the `<context-root>` element, then the value of `contextURI` is the name of the Web application archive file or exploded directory.

- serviceURI refers to the URI of the Web Service. This value corresponds to the `uri` attribute of the `<web-service>` element in the `web-services.xml` file. If you used the `servicegen` Ant task to assemble your Web Service, this value corresponds to the `serviceURI` attribute.

For example, assume you used the following `build.xml` file to assemble a WebLogic Web Service using the `servicegen` Ant task:

>     <project name="buildWebservice" default="build-ear">
>       <target name="build-ear">
>           <servicegen
>              destEar="myWebService.ear"
>              warName="myWAR.war"
>              contextURI="web_services">
>              <service
>                  ejbJar="myEJB.jar"
>                  targetNamespace="http://www.bea.com/examples/Trader"
>                  serviceName="TraderService"
>                  serviceURI="/TraderService"
>                  generateTypes="True"
>                  expandMethods="True" >
>              </service>
>          </servicegen>
>       </target>
>     </project>

The URL to invoke the Web Service Home Page, assuming the service is running on a host called `ariel` at the default port number, is:

>     http://ariel:7001/web_services/TraderService

The URL to get the automatically generated WSDL of the Web Service is:

>     http://ariel:7001/web_services/TraderService?WSDL

## Denying Access to the WSDL and Home Page of a WebLogic Web Service

Because the WSDL defines the public contract of a Web Service, you usually want to make it readily available. By default, the WSDL that describes a WebLogic Web Service is always publicly accessible. The WSDL is also accessible from the Web Service's Home Page.

You might, however, sometimes want to turn off public access to the WSDL or the Home Page. To do this, update the appropriate `<web-service>` element of the `web-services.xml` deployment descriptor file that describes the WebLogic Web Service, adding the attribute `exposeWSDL="False"` or `exposeHomePage="False"`, as shown in the following excerpt:

>     <web-service targetNamespace="http://example.com"
>                  name="myorderproc"
>                  uri="myOrderProcessingService"
>                  exposeWSDL="False"
>                  exposeHomePage="False">
>     ...
>     </web-service>

You must redeploy the Web Service after updating its deployment descriptor for the change to take effect.