Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Web Service Ant Tasks and Command-Line Utilities

The following sections describe WebLogic Web Service Ant tasks and the command-line utilities based on these Ant tasks:

- Overview of WebLogic Web Services Ant Tasks and Command-Line Utilities
- autotype
- clientgen
- servicegen
- source2wsdd
- wsdl2Service
- wsdlgen
- wspackage

# Overview of WebLogic Web Services Ant Tasks and Command-Line Utilities

Ant is a Java-based build tool, similar to the `make` command but much more powerful. Ant uses XML-based configuration files (called `build.xml` by default) to execute tasks written in Java.

BEA provides a number of Ant tasks that help you generate important parts of a Web Service (such as the serialization class, a client JAR file, and the `web-services.xml` file) and to package all the pieces of a WebLogic Web Service into a deployable EAR file.

The Apache Web site provides other useful Ant tasks for packaging EAR, WAR, and EJB JAR files. For more information, 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.

You can also run some of the Ant tasks as a command-line utility, using flags rather than attributes to specify how the utility works. The description of the flags is exactly the same as the description of its corresponding attribute.

Warning: Not all the attributes of the Ant tasks are available as flags to the equivalent command-line utility. See the sections that describe each Ant task for a list of the supported flags when using the command-line equivalent.

For further examples and explanations of using these Ant tasks, see Assembling WebLogic Web Services Using Ant Tasks.

## List of Web Services Ant Tasks and Command-Line Utilities

The following table provides an overview of the Web Service Ant tasks provided by BEA and the name of the corresponding command-line utility.

Table B-1 WebLogic Web Services Ant Tasks

Ant Task | Corresponding Command-Line Utility | Description
--- | --- | ---
autotype | weblogic.webservice.autotype | Generates the serialization class, Java representation, XML Schema representation, and data type mapping information for non-built-in data types used as parameters or return values to a WebLogic Web Service.
clientgen | weblogic.webservice.clientgen | Generates a client JAR file that contains a thin Java client used to invoke a Web Service.
servicegen | Not available. | Main Ant task that performs all the steps needed to assemble a Web Service. These steps include: Creating the Web Service deployment descriptor (`web-services.xml`). Introspecting EJBs and Java classes and generating any needed non-built-in data type supporting components. Generating the client JAR file. Packaging all the pieces into a deployable EAR file.
source2wsdd | Not available | Generates a `web-services.xml` deployment descriptor file from the Java source file for a Java class-implemented WebLogic Web Service.
wsdl2Service | Not available. | Generates the components of a WebLogic Web Service from a WSDL file. The components include the `web-services.xml` deployment descriptor file and a Java source file that you can use as a starting point to implement the Web Service.
wsdlgen | weblogic.webservice.wsdlgen | Generates a WSDL file from the EAR and WAR files that make up the Web Service.
wspackage | Not available. | Packages the components of a WebLogic Web Service into a deployable EAR file.

## Using the Web Services Ant Tasks

To use the Ant tasks, 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 Web Services Ant tasks.

The following example shows a simple `build.xml` file (with details of the Web Services Ant tasks `servicegen` and `clientgen` omitted for clarity):

>     <project name="buildWebservice" default="build-ear">
>       <target name="build-ear">
>         <servicegen attributes go here...>
>           ...
>         </servicegen>
>       </target>
>       <target name="build-client" depends="build-ear">
>         <clientgen attributes go here .../>
>       </target>
>       <target name="clean">
>         <delete>
>           <fileset dir="."
>                    includes="example.ear,client.jar" />
>         </delete>
>       </target>
>     </project>

Later sections provide examples of specifying the Ant task in the `build.xml` file.

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

## Differences in Operating System Case Sensitivity When Manipulating WSDL and XML Schema Files

Many of the WebLogic Web Service Ant tasks have attributes that you can use to specify an operating system file, such as a WSDL or an XML Schema file. For example, you can use the `wsdl` attribute of the `clientgen` Ant task to create the Web Services-specific client JAR file from an existing WSDL file that describes a Web Service.

The Ant tasks process these files in a case-sensitive way. This means that if, for example, the XML Schema file specifies two complex types whose names differ only in their capilatization (for example, `MyReturnType` and `MYRETURNTYPE`), the `clientgen` Ant task correctly generates two separate sets of Java source files for the Java represenation of the complex data type: `MyReturnType.java` and `MYRETURNTYPE.java`.

However, compiling these source files into their respective class files might cause a problem if you are running the Ant task on Microsoft Windows, because Windows is a case insensitive operating system. This means that Windows considers the files `MyReturnType.java` and `MYRETURNTYPE.java` to have the same name. So when you compile the files on Windows, the second class file overwrites the first, and you end up with only one class file. The Ant tasks, however, expect that two classes were compiled, thus resulting in an error similar to the following:

>     c:\src\com\bea\order\MyReturnType.java:14:
>     class MYRETURNTYPE is public, should be declared in a file named   MYRETURNTYPE.java
>     public class MYRETURNTYPE
>            ^

To work around this problem rewrite the XML Schema so that this type of naming conflict does not occur, or if that is not possible, run the Ant task on a case sensitive operating system, such as Unix.

## Setting the Classpath for the WebLogic Ant Tasks

Each WebLogic Ant task accepts a `classpath` attribute or element so that you can add new directories or JAR files to your current CLASSPATH environment variable.

The following example shows how to use the `classpath` attribute of the `servicegen` Ant task to add to the CLASSPATH variable:

>     <servicegen destEar="myEJB.ear"
>                 classpath="${java.class.path};my_fab_directory"
>        ...
>     </servicegen>

The following example shows how to add to the CLASSPATH by using the `<classpath`> element:

>     <servicegen ...>
>        <classpath>
>            <pathelement path="${java.class.path}" />
>            <pathelement path="my_fab_directory" />
>        </classpath>
>     ...
>     </servicegen>

The following example shows how you can build your CLASSPATH variable outside of the WebLogic Web Service Ant task declarations, then specify the variable from within the task using the `<classpath>` element:

>     <path id="myid">
>        <pathelement path="${java.class.path}"/>
>        <pathelement path="${additional.path1}"/>
>        <pathelement path="${additional.path2}"/>
>     </path>

>     <servicegen ....>
>        <classpath refid="myid" />
>     ...
>     </servicegen>

Warning: The WebLogic Web Services Ant tasks support the standard Ant property `build.sysclasspath`. The default value for this property is `ignore`. This means that if you specifically set the CLASSPATH in the `build.xml` file as described in this section, the Ant task you want to run ignores the system CLASSPATH (or the CLASSPATH in effect when Ant is run) and uses only the one that you specifically set. It is up to you to include in your CLASSPATH setting all the classes that the Ant task needs to successfully run. To change this default behavior, set the `build.sysclasspath` property to `last` to concatenate the system CLASSPATH to the end of the one you specified, or `first` to concatenate your specified CLASSPATH to the end of the system one.

Warning: For more information on the `build.sysclasspath` property, see the Ant documentation.

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.

## Using the Web Services Command-Line Utilities

To use the command-line utility equivalents of the Ant tasks, 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. Open a command shell window.
3. Execute the utility using the `java` command, as shown in the following example:

>     prompt> java weblogic.webservice.clientgen \
>                    -ear myapps/myapp.ear \
>                    -serviceName myService \
>                    -packageName myservice.client \
>                     -clientJar myapps/myService_client.jar

Run the command with no arguments to get a usage message.

# autotype

The `autotype` Ant task generates the following components for non-built-in data types that used as parameters or return values of your Web Service operation:

- Serialization class that converts between the XML and Java representation of the data.
- Given an XML Schema or WSDL file, a Java class to contain the Java representation of the data type.
- Given a Java class that represents the non-built-in data type, an XML Schema representation of the data type.
- Data type mapping information to be included in the `web-services.xml` deployment descriptor file.

For the list of non-built-in data types for which `autotype` can generate data type components, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks.

You can specify one of the following types of input to the `autotype` Ant task:

- A Java class file that represents your non-built-in data types by specifying the `javaTypes` attribute. The `autotype` Ant task generates the corresponding XML Schemas, the serialization classes, and the data type mapping information for the `web-services.xml` file.
- A Java class file of the component that implements your Web Service by specifying the `javaComponents` attribute. If your Web Service is implemented with a Java class, then this attribute points to the Java class. If your Web Service is implemented with a stateless session EJB, then this attribute points to the remote interface of the EJB. The `autotype` Ant task looks for non-built-in data types used as parameters or return values in the component, then generates the corresponding XML Schemas, the serialization classes, and the data type mapping information for the `web-services.xml` file. Be sure to include the Java class for your non-built-in data type in your CLASSPATH.
- An XML Schema file that represents your non-built-in data type by specifying the `schemaFile` attribute. The `autotype` Ant task generates the corresponding Java representations, the serialization classes, and the data type mapping information for the `web-services.xml` file.
- A URL to a WSDL file that contains a description of your non-built-in data type by specifying the `wsdlURI` attribute. The `autotype` Ant task generates the corresponding Java representations, the serialization classes, and the data type mapping information for the `web-services.xml` file.

Use the `destDir` attribute to specify the name of a directory that contains the generated components. The generated XML Schema and data type mapping information are generated in a file called `types.xml`. You can use this file to manually update an existing `web-services.xml` file with non-built-in data type mapping information, or use it in conjunction with the `typeMappingFile` attribute of the `servicegen` or `clientgen` Ant tasks, or the `typesInfo` attribute of the `source2wsdd` Ant task.

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.

Note: The fully qualified name for the `autotype` Ant task is `weblogic.ant.taskdefs.webservices.javaschema.JavaSchema`.

## Example

The following example shows how to create non-built-in data type components from a Java class:

>     <autotype  javatypes="mypackage.MyType"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="output" />

The following example is similar to the preceding one, except it creates non-built-in data type components for an array of `mypackage.MyType` Java data types:

>     <autotype  javaTypes="[Lmypackage.MyType;"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="output" />

Note: The `[L` `classname``;` syntax follows the Java class naming conventions as outlined in the java.lang.Class.getName() method documentation.

The following example shows how to use the `autotype` Ant task against a WSDL file; it also shows how to specify that the Ant task keep the generated Java files for the serialization class:

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

## Attributes

The following table describes the attributes of the `autotype` Ant task.

Table B-2 Attributes of the autotype Ant task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
destDir | Full pathname of the directory that will contain the generated components. The generated XML Schema and data type mapping information are generated in a file called `types.xml`. | String | Yes.
encoding | Specifies whether the `autotype` Ant task uses SOAP or literal encoding when generating the XML Schema file that describes the XML representation of a Java data type. The encoding is particularly important when generating complex XML data types, such as arrays. SOAP arrays are structurally different from non-SOAP arrays, so it is important to always use the correct one for the correct situation. If you are creating a document-oriented Web Service, you must specify that `autotype` use literal encoding, or users might run into interoperability problems when they later invoke your Web Service. Use this attribute only when generating an XML Schema from an existing Java data type. Valid values for this attribute are `soap` and `literal`. The default value is `soap`. | String | No. Use this attribute only in conjunction with either the `javaTypes` or `javaComponents` attributes. An error is returned if you use the `encoding` attribute with the `schemaFile` attribute.
javaComponents | Comma-separated list of Java class names that implement the Web Service. For Java class-implemented Web Services, this attribute points to the Java class. For stateless session EJB-implemented Web Services, this attribute points to the remote interface of the EJB. The Java classes (of both the implementation of the component and the implementation of your non-built-in data type) must be compiled and in your CLASSPATH. For example: `javaComponents="my.class1,my.class2"` The `autotype` Ant task introspects the Java classes to automatically generate the components for all non-built-in data types it finds. | String | You must specify one, and only one, of the following attributes: `schemaFile`, `wsdl`, `javaTypes`, or `javaComponents`.
javaTypes | Comma-separated list of Java class names that represent your non-built-in data types. The Java classes must be compiled and in your CLASSPATH. For example: `javaTypes="my.class1,my.class2"` Note: Use the syntax `[L` `classname``;` to specify an array of the Java data type. For an example, see Example. | String | You must specify one, and only one, of the following attributes: `schemaFile`, `wsdl`, `javaTypes`, or `javaComponents`.
keepGenerated | Specifies whether the `autotype` Ant task should keep (and thus include in the generated components) the Java source code of the serialization class for any non-built-in data types used as parameters or return values to the Web Service operations, or whether the `autotype` Ant task should include only the compiled class file. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No.
packageBase | Base package name of the generated Java classes for any non-built-in data types used as a return value or parameter in a Web Service. This means that each generated Java class will be part of the same package name, although the `autotype` Ant task generates its own specific name for each Java class which it appends to the specified package base name. If you do not specify this attribute, the `autotype` Ant task generates a base package name for you. Note: BEA recommends you not use this attribute, but rather, specify the full package name using the `packageName` attribute. The `packageBase` attribute is available for JAX-RPC compliance. | String | No. If you specify this attribute, you cannot also specify `packageName`.
packageName | Full package name of the generated Java classes for any non-built-in data types used as a return value or parameter in a Web Service. If you do not specify this attribute, the `autotype` Ant task generates a package name for you. Note: Although not required, BEA recommends you specify this attribute in most cases. Currently, the only situation in which you should not specify this attribute is if you use the `javaTypes` attribute to specify a list of Java data types whose class names are the same, but their package names are different. In this case, if you also specify the `packageName` attribute, the `autotype` Ant task generates a serialization class for only the last class. | String | No. If you specify this attribute, you cannot also specify `packageBase`.
schemaFile | Name of a file that contains the XML Schema representation of your non-built-in data types. | String | You must specify one, and only one, of the following attributes: `schemaFile`, `wsdl`, `javaTypes`, or `javaComponents`.
targetNamespace | Namespace URI of the generated XML Schema. | String | Yes.
typeMappingFile | File that contains data type mapping information for non-built-in data types for which have already generated needed components, as well as the XML Schema representation of your non-built-in data types. The format of the information is the same as the data type mapping information in the `<type-mapping>` and `<types>` elements of the `web-services.xml` file. The `autotype` Ant task does not generate non-built-in data type components for any data types listed in this file. It merges the information in this file with the generated information in its output `types.xml` file. | String | No.
wsdl | Full path name or URI of the WSDL that contains the XML Schema description of your non-built-in data type. | String | You must specify one, and only one, of the following attributes: `schemaFile`, `wsdl`, `javaTypes`, or `javaComponents`.

## Equivalent Command-Line Utility

The equivalent command-line utility of the `autotype` Ant task is called `weblogic.webservice.autotype.` The description of the flags of the utility is the same as the description of the Ant task attributes, described in the preceding section.

The `weblogic.webservice.autotype` utility supports the following flags (see the equivalent attribute for a description of the flag):

- `-help (Prints the standard usage message)`
- -version (Prints version information)
- -verbose (Enables verbose output)
- -destDir `dir`
- -schemaFile `pathname`
- -wsdl `uri`
- -javaTypes `classname`
- -javaComponents `classname`
- -packageName `name`
- -packageBase `name`
- -encoding `name`
- -generatePublicFields `true_or_false`
- -typeMappingFile `pathname`
- -keepGenerated `true_or_false`

# clientgen

The `clientgen` Ant task generates a Web Service-specific client JAR file that client applications can use to invoke both WebLogic and non-WebLogic Web Services. Typically, you use the `clientgen` Ant task to generate a client JAR file from an existing WSDL file; you can also use it with an EAR file that contains the implementation of a WebLogic Web Service.

The contents of the client JAR file includes:

- Client interface and stub files (conforming to the JAX-RPC specification) used to invoke a Web Service in static mode.
- Optional serialization class for converting non-built-in data between its XML and Java representation.
- Optional client-side copy of the Web Service WSDL file

You can use the `clientgen` Ant task to generate a client JAR file from the WSDL file of an existing Web Service (not necessarily running on WebLogic Server) or from an EAR file that contains a Weblogic Web Service implementation.

The WebLogic Server distribution includes a client runtime JAR file that contains the client side classes needed to support the WebLogic Web Services runtime component. For more information, see Generating the Client JAR File by Running the clientgen Ant Task.

Warning: The `clientgen` Ant task does not support solicit-response or notification WSDL operations. This means that if you attempt to create a client JAR file from a WSDL file that contains these types of operations, the Ant task ignores the operations.

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.

Note: The fully qualified name of the `clientgen` Ant task is `weblogic.ant.taskdefs.webservices.clientgen.ClientGenTask`.

## Example

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

## Attributes

The following table describes the attributes of the `clientgen` Ant task.

Table B-3 Attributes of the clientgen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
autotype | Specifies whether the `clientgen` task should generate and include in the client JAR file the serialization class for any non-built-in data types used as parameters or return values to the Web Service operations. Valid values are `True` and `False`. Default value is `True`. | Boolean | No.
clientJar | Name of a JAR file or exploded directory into which the `clientgen` task puts the generated client interface classes, stub classes, optional serialization class, and so on. To create or update a JAR file, use a`.jar` suffix when specifying the JAR file, such as `myclientjar.jar`. If the attribute value does not have a`.jar` suffix, then the `clientgen` task assumes you are referring to a directory name. If you specify a JAR file or directory that does not exist, the `clientgen` task creates a new JAR file or directory. | String | Yes.
ear | Name of an EAR file or exploded directory that contains the WebLogic Web Service implementation for which a client JAR file should be generated. Note: If the `saveWSDL` attribute of `clientgen` is set to `True` (the default value), the `clientgen` Ant task generates a WSDL file from the information in the EAR file, and stores it in the generated client JAR file. Because `clientgen` does not know the host name or port number of the WebLogic Server instance which will host the Web Service, `clientgen` uses the following endpoint address in the generated WSDL: `http://localhost:7001/``contextURI``/``serviceURI` where `contextURI` and `serviceURI` are the same values as described in WebLogic Web Services Home Page and WSDL URLs. If this endpoint address is not correct, and your client application uses the WSDL file stored in the client JAR file, you must manually update the WSDL file with the correct endpoint address. | String | Either `wsdl` or `ear` must be specified.
generateAsyncMethods | Specifies that the `clientgen` Ant task should generate two special methods used to invoke each Web Service operation asynchronously, in addition to the standard methods. The special methods take the following form: `FutureResult start` `Method``(``params``, AsyncInfo asyncInfo);` `result` `end` `Method``(FutureResult futureResult);` where: `Method` is the name of the standard method used to invoke the Web Service operation. `params` is the list of parameters to the operation. `result` is the result of the operation. `FutureResult` is a WebLogic object used as a placeholder for the impending result. `AsyncInfo` is a WebLogic object used to pass contextual information. Valid values for this attribute are `True` and `False`. The default value is `False.` | Boolean | No.
generatePublicFields | Specifies whether the clientgen Ant task, when generating the Java representation of any non-built-in data types used by the Web Service, should use public fields for the JavaBean attributes rather than getter and setter methods. Valid values are `True` and `False`. Default values is `False`. | Boolean | No.
j2me | Specifies whether the `clientgen` Ant task should create a J2ME/CDC-compliant client JAR file. Note: The generated client code is not JAX-RPC compliant. Valid values are `True` and `False`. Default value is `False`. | Boolean | No.
keepGenerated | Specifies whether the `clientgen` Ant task should keep (and thus include in the generated JAR file) the Java source code of the serialization class for any non-built-in data types used as parameters or return values to the Web Service operations, or whether the `clientgen` Ant task should include only the compiled class file. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No.
packageName | Package name into which the generated JAX-RPC client interfaces and stub files should be packaged. | String | Yes.
saveWSDL | When set to `True`, specifies that the WSDL of the Web Service be saved in the generated client JAR file. This means that client applications do not need to download the WSDL every time they create a stub to the Web Service, possibly improving performance of the client because of reduced network usage. Valid values are `True` and `False`. Default value is `True`. | Boolean | No.
serviceName | Web Service name for which a corresponding client JAR file should be generated. If you specify the `wsdl` attribute, the Web Service name corresponds to the `<service>` elements in the WSDL file. If you specify the `ear` attribute, the Web Service name corresponds to the `<web-service>` element in the `web-services.xml` deployment descriptor file. If you do not specify the `serviceName` attribute, the `clientgen` task generates client classes for the first service name found in the WSDL or `web-services.xml` file. | String | No.
typeMappingFile | File that contains data type mapping information, used by the `clientgen` task when generating the JAX-RPC stubs. The format of the information is the same as the data type mapping information in the `<type-mapping>` element of the `web-services.xml` file. If you specified the `ear` attribute, the information in this file overrides the data type mapping information found in the `web-services.xml` file. | String | No.
typePackageBase | Specifies the base package name of the generated Java class for any non-built-in data types used as a return value or parameter in a Web Service. This means that each generated Java class will be part of the same package name, although the `clientgen` Ant task generates its own specific name for each Java class which it appends to the specified package base name. If you specify this attribute, you cannot also specify `typePackageName`. If you do not specify this attribute and the XML Schema in the WSDL file defines a target namespace, then the `clientgen` Ant task generates a package name for you based on the target namespace. This means that if your XML Schema does not define a target namespace, then you must specify either the `typePackageName` (preferred) or `typePackageBase` attributes of the `clientgen` Ant task. Note: Rather than using this attribute, BEA recommends that you specify the full package name with the `typePackageName` attribute. The `typePackageBase` attribute is available for JAX-RPC compliance. | String | Required only if you specified the `wsdl` attribute and the XML Schema in the WSDL file does not define a target namespace.
typePackageName | Specifies the full package name of the generated Java class for any non-built-in data types used as a return value or parameter in a Web Service. If you specify this attribute, you cannot also specify `typePackageBase`. If you do not specify this attribute and the XML Schema in the WSDL file defines a target namespace, then the `clientgen` Ant task generates a package name for you based on the target namespace. This means that if your XML Schema does not define a target namespace, then you must specify either the `typePackageName` (preferred) or `typePackageBase` attributes of the `clientgen` Ant task. Note: Although not required, BEA recommends you specify this attribute. | String | Required only if you specified the `wsdl` attribute and the XML Schema in the WSDL file does not define a target namespace..
useLowerCaseMethodNames | When set to true, specifies that the method names in the generated stubs have a lower-case first character. Otherwise, all method names will the same as the operation names in the WSDL file. Valid values are `True` and `False`. Default value is `True`. | Boolean | No.
usePortNameAsMethodName | Specifies where the `clientgen` Ant task should get the names of the operations when generating a client from a WSDL file. If this value is set to true, then operations take the name specified by the `name` attribute of the `<port>` element in the WSDL file (where `<port>` is the child element of the `<service>` element). If `usePortNameAsMethodName` is set to false, then operations take the name specified by the `name` attribute of the `<portType>` element in the WSDL file (where `<portType>` is the child element of the `<definitions>` element). Valid values are `True` and `False`. Default value is `False`. | Boolean | No.
useServerTypes | Specifies where the `clientgen` task gets the implementation of any non-built-in Java data types used in a Web Service: either the task generates the Java code or the task gets it from the EAR file that contains the full implementation of the Web Service. Valid values are `True` (use the Java code in the EAR file) and `False`. Default value is `False`. For the list of non-built-in data types for which `clientgen` can generate data type components, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks. | Boolean | No. Use only in combination with the `ear` attribute.
warName | Name of the WAR file which contains the Web Service(s). The default value is `web-services.war`. | String | No. You can specify this attribute only in combination with the `ear` attribute.
wsdl | Full path name or URL of the WSDL that describes a Web Service (either WebLogic or non-WebLogic) for which a client JAR file should be generated. The generated stub factory classes in the client JAR file use the value of this attribute in the default constructor. | String | Either `wsdl` or `ear` must be specified.

## Equivalent Command-Line Utility

The equivalent command-line utility of the `clientgen` Ant task is called `weblogic.webservice.clientgen.` The description of the flags of the utility is the same as the description of the Ant task attributes, described in the preceding section.

The `weblogic.webservice.clientgen` utility supports the following flags (see the equivalent attribute for a description of the flag):

- `-help (Prints the standard usage message)`
- -version (Prints version information)
- -verbose (Enables verbose output)
- `-wsdl` `uri`
- -`ear` `pathname`
- -`clientJar` `pathname`
- `-packageName` `name`
- `-warName` `name`
- `-serviceName` `name`
- `-typeMappingFile` `pathname`
- `-useServerTypes` `true_or_false`
- -typePackageName `name`
- -typePackageBase `name`
- -useLowerCaseMethodNames `true_or_false`
- -usePortNameAsMethodName `true_or_false`
- -generateAsyncMethods `true_or_false`
- -generatePublicFields `true_or_false`
- -saveWSDL `true_or_false`
- -autotype `true_or_false`
- -overwrite `true_or_false`
- -keepGenerated `true_or_false`

# servicegen

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

In particular, the `servicegen` Ant task:

- Introspects the EJBs and Java classes, looking for public methods to convert into Web Service operations.
- Creates a `web-services.xml` deployment descriptor file, based on the attributes of the `servicegen` Ant task and introspected information.
- Optionally creates the serialization class that converts 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. This feature is referred to as autotyping.
- 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.

You can also configure default configuration for reliable SOAP messaging, handler chains, and data security (digital signatures and encryption) for a Web Service using `servicegen`.

While you are developing your Web Service, 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.

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.

Note: The fully qualified name of the `servicegen` Ant task is `weblogic.ant.taskdefs.webservices.servicegen.ServiceGenTask`.

## Example

>           <servicegen
>              destEar="ears/myWebService.ear"
>              warName="myWAR.war"
>              contextURI="web_services" >
>              <service
>                  ejbJar="jars/myEJB.jar"
>                  targetNamespace="http://www.bea.com/examples/Trader"
>                  serviceName="TraderService"
>                  serviceURI="/TraderService"
>                  generateTypes="True"
>                  expandMethods="True" >
>              </service>
>          </servicegen>

## Attributes and Child Elements

The `servicegen` Ant task has four attributes and one child element (`<service>`) for each Web Service you want to define in a single EAR file. You must specify at least one `<service>` element.

The `<service>` element has four optional elements: `<client>`, `<reliability>`, `<handlerChain>`, and `<security>`.

The following graphic describes the hierarchy of the `servicegen` Ant task.

Figure B-1 Element Hierarchy of servicegen Ant Task

### servicegen

The `servicegen` Ant task is the main task for automatically generating and assembling all the parts of a Web Service and packaging it into a deployable EAR file.

The following table describes the attributes of the `servicegen` Ant task.

Table B-4 Attributes of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
contextURI | Context root of the Web Service. You use this value in the URL that invokes the Web Service. The default value of the `contextURI` attribute is the value of the `warName` attribute. | String | No.
destEar | Pathname of the EAR file or exploded directory which will contain the Web Service and all its components. To create or update an EAR file, use a`.ear` suffix when specifying the EAR file, such as `ears/mywebservice.ear`. If the attribute value does not have a`.ear` suffix, then the `servicegen` task creates an exploded directory. If you specify an EAR file or directory that does not exist, the `servicegen` task creates a new one. | String | Yes
keepGenerated | Specifies whether the `servicegen` Ant task should keep (and thus include in the generated Web Services EAR file) the Java source code of the serialization class for any non-built-in data types used as parameters or return values to the Web Service operations, or whether the `servicegen` Ant task should include only the compiled class file. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
mergeWithExistingWS | Specifies whether the servicegen Ant task should attempt to merge the generated components into existing Web Services in the EAR file specified by the `destEar` attribute. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No
warName | Name of the WAR file or exploded directory into which the Web Service Web application is written. The WAR file or directory is created at the top level of the EAR file. The default value is a WAR file called `web-services.war`. To specify a WAR file, use a `.war` suffix, such as `mywebserviceWAR.war`. If the attribute value does not have a `.war` suffix, then the `servicegen` task creates an exploded directory. | String | No

### service

The `<service>` element describes a single Web Service implemented with either a stateless session EJB or a Java class.

The following table describes the attributes of the `<service>` element of the `servicegen` Ant task. Include one `<service>` element for every Web Service you want to package in a single EAR file.

Table B-5 Attributes of the <service> Element of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
ejbJar | JAR file or exploded directory that contains the EJBs that implement the back-end component of a Web Service operation. The `servicegen` Ant task introspects the EJBs to automatically generate all the components. | String | You must specify either the `ejbJar`, `javaClassComponents`, or `JMS*` attribute.
excludeEJBs | Comma-separated list of EJB names for which non-built-in data type components should not be generated. If you specify this attribute, the `servicegen` task processes all EJBs except those on the list. The EJB names correspond to the `<ejb-name>` element in the `ejb-jar.xml` deployment descriptor in the EJB JAR file (specified with the `ejbJar` attribute). | String | No. Used only in combination with the `ejbJar` attribute.
expandMethods | Specifies whether the `servicegen` task, when generating the `web-services.xml` file, should create a separate `<operation>` element for each method of the EJB or Java class, or whether the task should implicitly refer to all methods by specifying only one `<operation>` element that contains a `method="*"` attribute. Valid values are `True` and `False`. Default value is `False`. | Boolean | No.
generateTypes | Specifies whether the `servicegen` task should generate the serialization class and Java representations for non-built-in data types used as parameters or return values. Valid values are `True` and `False`. Default value is `True`. For the list of non-built-in data types for which servicegen can generate data type components, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks. | Boolean | No.
ignoreAuthHeader | Specifies that the Web Service ignore the `Authorization` HTTP header in the SOAP request. Note: Be careful using this attribute. If you set the value of this attribute to `True`, WebLogic Server never authenticates a client application that is attempting to invoke a Web Service, even if access control security constraints have been defined for the EJB, Web Application, or Enterprise Application that make up the Web Service. Or in other words, a client application that does not provide athentication credentials is still allowed to invoke a Web Service that has security constraints defined on it. Valid values are `True` and `False`. Default value is `False`. | Boolean | No.
includeEJBs | Comma-separated list of EJB names for which non-built-in data type components should be generated. If you specify this attribute, the `servicegen` task processes only those EJBs on the list. The EJB names correspond to the `<ejb-name>` element in the `ejb-jar.xml` deployment descriptor in the EJB JAR file (specified with the `ejbJar` attribute). | Boolean | No. Used only in combination with the `ejbJar` attribute.
javaClassComponents | Comma-separated list of Java class names that implement the Web Service operation. The Java classes must be compiled and in your CLASSPATH. For example: `javaClassComponents="my.FirstClass,my.SecondClass"` Note: Do not include the `.class` extension when specifying the class names. The `servicegen` Ant task introspects the Java classes to automatically generate all the needed components. | String | You must specify either the `ejbJar`, `javaClassComponents`, or `JMS*` attribute.
JMSAction | Specifies whether the client application that invokes this JMS-implemented Web Service sends or receives messages to or from the JMS destination. Valid values are `send` or `receive`. Specify `send` if the client sends messages to the JMS destination and `receive` if the client receives messages from the JMS destination. | String | Yes, if creating a JMS-implemented Web Service.
JMSConnectionFactory | JNDI name of the `ConnectionFactory` used to create a connection to the JMS destination. | String | Yes, if creating a JMS-implemented Web Service.
JMSDestination | JNDI name of a JMS queue. | String | Yes, if creating a JMS-implemented Web Service.
JMSDestinationType | Type of JMS destination. Currently only one type is supported: Queue. Valid value is `queue`. | String | Yes, if creating a JMS-implemented Web Service.
JMSMessageType | Data type of the single parameter to the send or receive operation. Default value is `java.lang.String`. If you use this attribute to specify a non-built-in data type, and set the `generateTypes` attribute to `True`, be sure the Java representation of this non-built-in data type is in your CLASSPATH. | String | No.
JMSOperationName | Name of the operation in the generated WSDL file. Default value is either `send` or `receive`, depending on the value of the JMSAction attribute. | String | No.
protocol | Protocol over which this Web Service is deployed. Valid values are `http` and `https`. The default value is `http`. | String | No.
serviceName | Name of the Web Service which will be published in the WSDL. Note: If you specify more than one `<service>` element in your `build.xml` file that calls `servicegen`, and set the `serviceName` attribute for each element to the same value, `servicegen` attempts to merge the multiple `<service>` elements into a single Web Service. | String | Yes.
serviceURI | Web Service URI portion of the URL used by client applications to invoke the Web Service. Note: Be sure to specify the leading "/", such as `/TraderService`. The full URL to invoke the Web Service will be: `protocol://host:port/contextURI/serviceURI` where `protocol` refers to the `protocol` attribute of the `<service>` element `host` refers to the computer on which WebLogic Server is running `port` refers to the port on which WebLogic Server is listening `contextURI` refers to the `contextURI` attribute of the main `servicegen` Ant task `serviceURI` refers to this attribute | String | Yes.
style | Specifies whether the `servicegen` Ant task should generate RPC-oriented or document-oriented Web Service operations. RPC-oriented WebLogic Web Service operations use SOAP encoding. Document-oriented WebLogic Web Service operations use literal encoding. You can use the following two values to generate document-oriented Web Service operations: `document` and `documentwrapped`. If you specify `document` for this attribute, the resulting Web Service operations take only one parameter. This means that the methods that implement the operations must also have only one parameter. In this case, if `servicegen` encounters methods that have more than one parameter, `servicegen` ignores the method and does not generate a corresponding Web Service operation for it. If you specify `documentwrapped`, the resulting Web Service operations can take any number of parameters, although the parameter values will be wrapped into one complex data type in the SOAP messages. If two or more methods of your stateless session EJB or Java class that implement the Web Service have the same number and data type of parameters, and you want the operations to be document-oriented, you must specify `documentwrapped` for this attribute rather than `document`. Valid values for this attribute are `rpc`, `documentwrapped`, and `document`. Default value is `rpc`. Note: Because the `style` attribute applies to an entire Web Service, all operations in a single WebLogic Web Service must be either RPC-oriented or documented-oriented; WebLogic Server does not support mixing the two styles within the same Web Service. | String | No.
typeMappingFile | File that contains additional XML data type mapping information and XML Schema representation of non-built-in data types. The format of the information is the same as the data type mapping information in a `web-services.xml`. Use this attribute if you want to include extra XML data type information in the `<type-mapping>` element of the `web-services.xml` file, in addition to the required XML descriptions of data types used by the EJB or Java class that implements an operation. The `servicegen` task adds the extra information in the specified file to a generated `web-services.xml` file. | String | No.
targetNamespace | The namespace URI of the Web Service. | String | Yes.
useSOAP12 | Specifies whether to use SOAP 1.2 as the message format protocol. By default, WebLogic Web Services use SOAP 1.1. If you specify `useSOAP12="True"`, the generated WSDL of the deployed WebLogic Web Service includes two ports: the standard port that specifies a binding for SOAP 1.1 as the message format protocol, and a second port that uses SOAP 1.2. Client applications, when invoking the Web Service, can use the second port if they want to use SOAP 1.2 as their message format protocol. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.

### client

The optional `<client>` element describes how to create the client JAR file that client applications use to invoke the Web Service. Specify this element only if you want the `servicegen` Ant task to create a client JAR file.

Note: You do not have to create the client JAR file when you assemble your Web Service. You can later use the `clientgen` Ant task to generate the JAR file.

The following table describes the attributes of the `<client>` element.

Table B-6 Attributes of the <client> Element of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
clientJarName | Name of the generated client JAR file. When the `servicegen` task packages the Web Service, it puts the client JAR file in the top-level directory of the Web Service WAR file of the EAR file. Default name is `serviceName``_client.jar`, where `serviceName` refers to the name of the Web Service (the `serviceName` attribute) Note: If you want a link to the client JAR file to automatically appear in the Web Service Home Page, you should not change its default name. | String | No.
packageName | Package name into which the generated client interfaces and stub files are packaged. | String | Yes.
saveWSDL | When set to `True`, saves the WSDL file of the Web Service in the generated client JAR file. This means that client applications do not need to download the WSDL file every time they create a stub to the Web Service, possibly improving performance of the client because of reduced network usage. Valid values are `True` and `False`. Default value is `True`. | Boolean | No.
useServerTypes | Specifies where the `servicegen` task gets the implementation of any non-built-in Java data types used in a Web Service: either the task generates the Java code or the task gets it from the EAR file that contains the full implementation of the Web Service. Valid values are `True` (use the Java code in the EAR file) and `False`. Default value is `False`. For the list of non-built-in data types for which servicegen can generate data type components, see Non-Built-In Data Types Supported by servicegen and autotype Ant Tasks. | Boolean | No.

### handlerChain

The optional `<handlerChain>` child element of the `<service>` element adds a handler chain component to the Web Service, and specifies that the handler chain is associated with every operation of the Web Service. A handler chain consists of one or more handlers. For more information on handler chains, see Creating SOAP Message Handlers to Intercept the SOAP Message.

Note: Setting this element in `servicegen` associates the handler chain with every operation in your Web Service. If you want only some operations to be associated with this handler chain, then you must edit the generated `web-services.xml` file and remove the `handler-chain` attribute of the corresponding `<operation>` element. For details of these elements and attributes, see WebLogic Web Service Deployment Descriptor Elements.

The following table describes the attributes of the `<handlerChain>` element.

Table B-7 Attributes of the <handlerChain> Element of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
handlers | Comma separated fully qualified list of Java class names that implement the handlers in the handler chain. You must include at least one class name. Note: If the Java class that implements a handler expects initialization parameters, you must edit the generated `web-services.xml` file and add an `<init-params>` child element to the `<handler>` element. For details of these elements, see WebLogic Web Service Deployment Descriptor Elements. | String | Yes.
name | The name of the handler chain. Default value is `serviceName` `HandlerChain`, where `serviceName` is the value of the `serviceName` attribute of the `<service>` parent element. | String | No.

### reliability

The optional `<reliability>` child element of the `<service>` element specifies that every operation of the Web Service can be invoked asynchronously using reliable SOAP messaging. For more information on reliable SOAP messaging, see Using Reliable SOAP Messaging.

Note: Setting this element in `servicegen` enables reliable SOAP messaging for every operation in your Web Service. If you want only some operations to have reliable SOAP messaging, then you must edit the generated `web-services.xml` file and remove the `<reliable-delivery>` child element of the corresponding `<operation>` element. For details of these elements, see WebLogic Web Service Deployment Descriptor Elements.

The following table describes the attributes of the `<reliability>` element.

Table B-8 Attributes of the <reliability> Element of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
duplicateElimination | Specifies whether the WebLogic Web Service operations should ignore duplicate invokes from the same client application. If this attribute is set to `True`, the Web Service persists the message IDs from client applications that invoke the Web Service so that it can eliminate any duplicate invokes. If this values is set to `False`, the Web Service does not keep track of duplicate invokes, which means that if a client retries an invoke, both invokes could return values. Valid values for this attribute are `True` and `False`. The default value is `True`. | Boolean | No.
persistDuration | The default minimum number of seconds that the Web Service should persist the history of a reliable SOAP message (received from the sender that invoked the Web Service) in its storage. The Web Service, after recovering from a WebLogic Server crash, does not dispatch persisted messages that have expired. The default value of this attribute is 60,000 seconds. | Integer | No.

### security

The optional `<security>` child element of the `<service>` element adds default data security, such as digital signatures and encryption, to your Web Service. For more information about data security, see Configuring Security..

Note: You can encrypt or digitally sign only the entire SOAP message body when you configure data security using the `servicegen` Ant task. If you want to specify particular elements of the SOAP message that are to be digitally signed or encrypted, see Configuring Message-Level Security: Main Steps. This section also describes the general security configuration tasks you must perform with the Administration Console before you can successfully invoke your secure Web Service.

The following table describes the attributes of the `<security>` element.

Table B-9 Attributes of the <security> Element of the servicegen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
enablePasswordAuth | Specifies whether user authentication is enabled or disabled. If enabled, a username token is added to the `<security>` element of the web-services.xml deployment descriptor file. Valid values for the attribute are `True` and `False`. The default value is `False`. | Boolean | No.
encryptKeyName | The name of the key and certificate pair, stored in WebLogic Server's keystore, used to encrypt SOAP message. If you do not specify this attribute, no part of the SOAP message will be encrypted. | String | Only if you want to encrypt the SOAP message.
encryptKeyPass | The password of the key and certificate pair, stored in WebLogic Server's keystore, used to encrypt the SOAP message. If you do not specify this attribute, no part of the SOAP message will be encrypted. | String | Only if you want to encrypt the SOAP message.
password | Specifies the password used in the username token of the SOAP response message. If you do not specify this attribute, the SOAP response message will not include a username token specification. | String | Only if your SOAP messages require a username token.
signKeyName | The name of the key and certificate pair, stored in WebLogic Server's keystore, used to digitally sign the SOAP message. If you do not specify this attribute, no part of the SOAP message will be digitally signed. | String | Only if you want to digitally sign the SOAP message.
signKeyPass | The password of the key and certificate pair, stored in WebLogic Server's keystore, used to digitally sign the SOAP message. If you do not specify this attribute, no part of the SOAP message will be digitally signed. | String | Only if you want to digitally sign the SOAP message.
username | Specifies the username used in the username token of the SOAP response message. If you do not specify this attribute, the SOAP response message will not include a username token specification. | String | Only if your SOAP messages require a username token.

# source2wsdd

The `source2wsdd` Ant task generates a `web-services.xml` deployment descriptor file from the Java source file for a stateless session EJB- or Java class-implemented WebLogic Web Service. You can also specify that the WSDL that describes the Web Service be generated.

The `source2wsdd` Ant task sets the name of the Web Service to the class name of the Java class or EJB that implements the Web Service. This name will also be the public name of the Web Service published in its WSDL.

The `source2wsdd` Ant task does not generate data type mapping information for any non-built-in data types used as parameters or return values of the methods of your EJB or Java class If your EJB or Java class uses non-built-in data types, you must first run the `autotype` Ant task to generate the needed components, then point the `typesInfo` attribute of the `source2wsdd` Ant task to the `types.xml` file generated by the `autotype` Ant task.

If your EJB or Java class refers to other Java class files, be sure to set the `sourcePath` attribute of `source2wsdd` Ant task to the directory that contains them.

Note: The fully qualified name of the `source2wsdd` Ant task is `weblogic.ant.taskdefs.webservices.autotype.JavaSource2DD`.

## Example

The following example shows how to generate a `web-services.xml` file, generated into the `ddfiles` directory, for a Java class-implemented Web Service. The information about the non-built-in data types is contained in the `autotype/types.xml` file. The Web Service portion of the URI used to invoke the service is `/MyService`.

>     <source2wsdd
>           javaSource="source/MyService.java"
>           typesInfo="autotype/types.xml"
>           ddFile="ddfiles/web-services.xml"
>           serviceURI="/MyService"
>     />

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.

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

## Attributes

The following table describes the attributes of the `source2wsdd` Ant task.

Table B-10 Attributes of the source2wsdd Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
ddFile | Full pathname of the Web Services deployment descriptor file (`web-services.xml`) which will contain the generated deployment descriptor information. | String | Yes.
ejblink | Specifies the value of the `<ejb-link>` child element of the `<stateless-ejb>` element in the generated deployment descriptor file for a stateless session EJB-implemented Web Service. Use this attribute only if you are generating the `web-services.xml` file from an EJB. Note: The `source2wsdd` Ant task does not use this attribute to determine the EJB which it needs to introspect. Rather, it uses this attribute to determine what value it should use for the `<ejb-link>` element in the generated `web-services.xml` file. Use the `javaSource` attribute to point to the actual EJB source file. The format of this attribute is as follows: `jar-name`#`ejb-name` `jar-name` refers to the name of the JAR file, contained within the Web Service EAR file, that contains the stateless session EJB. The name should include pathnames relative to the top level of the EAR file. `ejb-name` refers to the name of the stateless session EJB, corresponding to the `<ejb-name>` element in the `ejb-jar.xml` deployment descriptor file in the EJB JAR file. Example: `myapp.jar#StockQuoteBean` | String | No. If you specify this attribute, the required `javaSource` attribute must point to the EJB source file.
handlerInfo | Full pathname of the XML file that contains information about the SOAP message handlers and handler chains defined for the Web Service. You must create this file manually. The root element of the file is `<handler-chains>`. For more information about how to populate the file, see `Updating the web-services.xml File with SOAP Message Handler Information` and `WebLogic Web Service Deployment Descriptor Elements.` If you do not specify this attribute, the generated `web-services.xml` file does not contain any SOAP message handlers or handler chain information. | String | No.
ignoreAuthHeader | Specifies that the Web Service ignore the `Authorization` HTTP header in the SOAP request. Note: Be careful using this attribute. If you set the value of this attribute to `True`, WebLogic Server never authenticates a client application that is attempting to invoke a Web Service, even if access control security constraints have been defined for the EJB, Web Application, or Enterprise Application that make up the Web Service. Or in other words, a client application that does not provide athentication credentials is still allowed to invoke a Web Service that has security constraints defined on it. Valid values are `True` and `False`. Default value is `False`. | Boolean | No.
javaSource | Name of the stateless session EJB or Java source file that implements your Web Service component. | String | Yes.
mergeWithExistingWS | Specifies whether the `source2wsdd` Ant task should attempt to merge the generated `web-services.xml` deployment descriptor information with an existing file, specified with the `ddFile` attribute. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No.
serviceURI | Web Service URI portion of the URL used by client applications to invoke the Web Service. Note: Be sure to specify the leading "/", such as `/TraderService`. The value of this attribute becomes the `uri` attribute of the `<web-service>` element in the generated `web-services.xml` deployment descriptor. | String | Yes.
sourcePath | Full pathname of the directory that contains any additional classes referred to by the Java source file specified with the javaSource attribute. | String | No.
typesInfo | Name of the file that contains the XML Schema representation and data type mapping information for any non-built-in data types used as parameters or return value of the Web Service. The format of the data type mapping information is the same as that in the `<type-mapping>` element of the `web-services.xml` file. Typically you have already run the `autotype` Ant task to generate this information into a file called `types.xml`. | String | Yes.
wsdlFile | Specifies that, in addition to the `web-services.xml` deployment descriptor, you also want to generate the WSDL that describes the Web Service. Set this value to the name of the output file that will contain the generated WSDL. | String | No.

# wsdl2Service

The `wsdl2Service` Ant task takes as input an existing WSDL file and generates:

- the Java interface that represents the implementation of your Web Service based on the WSDL file
- the Java exception class for user-defined exceptions specified in the WSDL file
- an empty Java implementation class
- the `web-services.xml` file that describes the Web Service

The generated Java interface file describes the template for the full Java class-implemented WebLogic Web Service. The template includes full method signatures that correspond to the operations in the WSDL file. You must then write a Java class that implements this interface so that the methods function as you want, following the guidelines in Implementing a Web Service By Writing a Java Class. You can generate a skeleton of the implementation class by specifying the `generateImpl="True"` attribute; add the business logic Java code to this class to complete the implementation.

The `wsdl2Service` Ant task generates a Java interface for only one Web Service in a WSDL file (specified by the `<service>` element.) Use the `serviceName` attribute to specify a particular service; if you do not specify this attribute, the `wsdl2Service` Ant task generates a Java interface for the first `<service>` element in the WSDL.

The `wsdl2Service` Ant task does not generate data type mapping information for any non-built-in data types used as parameters or return values of the operations in the WSDL file. If the WSDL uses non-built-in data types, you must first run the `autotype` Ant task to generate the data type mapping information, then point the `typeMappingFile` attribute of the `wsdl2Service` Ant task to the `types.xml` file generated by the `autotype` Ant task.

Warning: The `wsdl2Service` Ant task, when generating the `web-services.xml` file for your Web Service, assumes you use the following convention when naming the Java class that implements the generated Java interface:

Warning: `packageName.serviceName` `Impl`

Warning: where `packageName` and `serviceName` are the values of the similarly-named attributes of the `wsdl2Service` Ant task. The Ant task puts this information in the `class-name` attribute of the `<java-class>` element of the `web-services.xml` file.

Warning: If you name your Java implementation class differently, you must manually update the generated `web-services.xml` file accordingly.

Note: The fully qualified name of the `wsdl2Service` Ant task is `weblogic.ant.taskdefs.webservices.wsdl2service.WSDL2Service`.

## Example

>     <wsdl2service
>           wsdl="wsdls/myService.wsdl"
>           destDir="myService/implementation"
>           typeMappingFile="autotype/types.xml"
>           packageName="example.ws2j.service"
>     />

## Attributes

The following table describes the attributes of the `wsdl2Service` Ant task.

Table B-11 Attributes of the wsdl2Service Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
ddFile | Full pathname of the generated Web Services deployment descriptor file (`web-services.xml`) which will contain the deployment descriptor information. If you do not specify this attribute, the `web-services.xml` file is generated in the directory specified by the `destDir` attribute. | String | No.
destDir | The full pathname of the directory that will contain the generated components (`web-services.xml` file and Java interface file that represents the implementation of your Web Service and optional implementation class.) | String | Yes.
generateImpl | Specifies that the `wsdl2Service` Ant task should generate an empty implementation Java class file. The name of the Java class is `serviceName` `Impl`, where `serviceName` refers to the value of the similarly-named attribute of the `wsdl2Service` Ant task. The name of the generated Java file is `serviceName` `Impl.java`, and the file is generated in the directory specified by the `destDir` attribute. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
keepGenerated | Specifies whether the `wsdl2Service` Ant task should keep (and thus include in directory specified by the `destDir` attribute) the Java source code of the interface that represents your Web service and the user-defined exceptions in the WSDL file. The default behavior is for the Ant task to include only the compiled class files. Valid values for this attribute are `True` and `False`. The default value is `False`. | Boolean | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No.
packageName | The package name for the generated Java interface file that represents the implementation of your Web Service. | String | Yes.
serviceName | The name of the Web Service in the WSDL file for which a partial WebLogic implementation will be generated. The name of a Web Service in a WSDL file is the value of the `name` attribute of the `<service>` element. If you do not specify this attribute, the `wsdl2Service` Ant task generates a partial implementation for the first `<service>` element it finds in the WSDL file. Note: The `wsdl2Service` Ant task generates a partial WebLogic Web Service implementation for only one service in a WSDL file. If your WSDL file contains more than one Web Service, then you must run `wsdl2Service` multiple times, changing the value of this attribute each time. | String | No.
typeMappingFile | File that contains data type mapping information for all non-built-in data types referred to by the operations of the Web Service in the WSDL file. The format of the information is the same as the data type mapping information in the `<type-mapping>` element of the `web-services.xml` file. Typically, you first run the `autotype` Ant task (specifying the `wsdl` attribute) against the same WSDL file and generate all the non-built-in data type components. One of the components is a file called `types.xml` that contains the non-built-in data type mapping information and the XML Schema of the non-built-in data types. Set the `typeMappingFile` attribute equal to this file. | String | Required only if the operations of the Web Service in the WSDL file refer to any non-built-in data types.
wsdl | The full path name or URL of the WSDL that describes a Web Service for which a partial WebLogic Web Service implementation will be generated. | String | Yes.

# wsdlgen

The `wsdlgen` Ant task generates a WSDL file from the EAR and WAR files that implement your Web Service. The EAR file contains the EJBs that implement your Web Service and the WAR file contains the `web-services.xml` deployment descriptor file.

The fully qualified name of the `wsdlgen` Ant task is `weblogic.ant.taskdefs.webservices.wsdlgen.WSDLGen`.

## Example

>     <wsdlgen ear="myapps/myapp.ear"
>              warName="myapps/myWAR.war"
>              serviceName="myService"
>              wsdlFile="wsdls/myService.WSDL"
>     />

## Attributes

The following table describes the attributes of the `wsdlgen` Ant task.

Table B-12 Attributes of the wsdlgen Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
ear | Name of an EAR file or exploded directory that contains the WebLogic Web Service implementation for which the WSDL file should be generated. | String | Yes.
defaultEndpoint | Endpoint Web Service URL to be included in the generated WSDL file. The default value is `http://localhost:7001`. | String | No.
overwrite | Specifies whether the components generated by this Ant task should be overwritten if they already exist. If you specify `True`, new components are always generated and any existing components are overwritten. If you specify `False`, the Ant task overwrites only those components that have changed, based on the timestamp of any existing components. Valid values for this attribute is `True` or `False`. The default value is `True`. | Boolean | No.
serviceName | Web Service name for which a corresponding WSDL file should be generated. The Web Service name corresponds to the `<web-service>` element in the `web-services.xml` deployment descriptor file. If you do not specify the `serviceName` attribute, the `wsdlgen` task generates a WSDL file for the first service name found in the `web-services.xml` file. | String | No.
warName | Name of the WAR file that contains the `web-services.xml` deployment descriptor file of your Web Service. | String | Yes.
wsdlFile | Name of the output file that will contain the generated WSDL. | String | Yes.

## Equivalent Command-Line Utility

The equivalent command-line utility of the `wsdlgen` Ant task is called `weblogic.webservice.wsdlgen.` The description of the flags of the utility is the same as the description of the Ant task attributes, described in the preceding section.

The `weblogic.webservice.wsdlgen` utility supports the following flags (see the equivalent attribute for a description of the flag):

- `-help (Prints the standard usage message)`
- -version (Prints version information)
- -verbose (Enables verbose output)
- -warName `name`
- -serviceName `name`
- -defaultEndpoint `address`

# wspackage

Use the `wspackage` Ant task to:

- package the various components of a WebLogic Web Service into a new deployable EAR file.
- add extra components to an already existing EAR file.

It is assumed that you have already generated the components, which can include:

- The `web-services.xml` deployment descriptor file
- The EJB JAR file that contains the EJBs the implement a Web Service
- The Java class file that implements a Web Service
- A client JAR file that users can download and use to invoke the Web Service
- Implementations of SOAP handlers
- Components for any non-built-in data types used as parameters and return values for the Web Service. These components include the XML and Java representations of the data type and the serialization class that converts the data between its two representations.

Typically you use other Ant tasks, such as `clientgen`, `autotype`, `source2wsdd`, and `wsdl2Service`, to generate the preceding components.

When you use the `wspackage` Ant task to add additional components to an existing EAR file, be sure you specify the `overwrite="false"` attribute to ensure that none of the existing components are overwritten. Use the `output` attribute to specify the full pathname of the existing EAR file.

Note: The fully qualified name of the `wspackage` Ant task is `weblogic.ant.taskdefs.webservices.wspackage.WSPackage`.

## Example

The following example shows how to use the `wspackage` Ant task to package WebLogic Web Service components into a new EAR file:

>     <wspackage
>           output="ears/myWebService.ear"
>           contextURI="web_services"
>           codecDir="autotype"
>           webAppClasses="example.ws2j.service.SimpleTest"
>           ddFile="ddfiles/web-services.xml"
>     />

The following example shows how to add additional components to an existing EAR file called `ears/myWebService.ear`.

>     <wspackage
>           output="ears/myWebService.ear"
>           overwrite="false"
>           filesToEar="myEJB2.jar"
>     />

## Attributes

The following table describes the attributes of the `wspackage` Ant task.

Table B-13 Attributes of the wspackage Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
codecDir | Name of the directory that contains the serialization classes for any non-built-in data types used as parameters or return values in your Web Service. | String | No.
contextURI | Context root of the Web Service. You use this value in the URL that invokes the Web Service. The default value of the `contextURI` attribute is the value of the `warName` attribute. | String | No.
ddFile | Full pathname of an existing Web Services deployment descriptor file (`web-services.xml`). If you do not specify this attribute, it is assumed that you are using the `wspackage` Ant task to add additional components to an existing EAR file. In this case, you must also specify `overwrite="false"` and point the `output` attribute to the existing EAR file. | String | No.
filesToEar | Comma-separated list of files to be packaged in the root directory of the EAR. Use this attribute to specify the EJB JAR files that implement a Web Service, as well as any other supporting EJB JAR files. | String | No.
filesToWar | Comma-separated list of additional files, such as the client JAR file, to be packaged in the root directory of the Web Service's Web application. | String | No.
output | Pathname of the EAR file or exploded directory which will contain the Web Service and all its components. If you are using the `wspackage` Ant task to add additional components to an existing EAR file, this attribute specifies the full pathname of the existing file. To create or update an EAR file, use a`.ear` suffix when specifying the EAR file, such as `ears/mywebservice.ear`. If the attribute value does not have a`.ear` suffix, then the `wspackage` task creates an exploded directory. If you specify an EAR file or directory that does not exist, the `wspackage` task creates a new one. | String | Yes
overwrite | Specifies whether you want the components of an existing EAR file or directory to be overwritten. The components include the `web-services.xml` file, serialization class, client JAR files, and so on. Valid values for this attribute are `True` and `False`. The default value is `True`. If you specify `False`, the `wspackage` Ant task attempts to merge the contents of the EAR file/directory and information in the `web-services.xml` file. If you are using the wspackage Ant task to add additional components to an existing EAR file, you must specify `overwrite="false"`. | Boolean | No
utilJars | Comma-separated list of files that should be packaged in the `WEB-INF/lib` directory of the Web Service Web application. | String | No.
warName | Name of the WAR file into which the Web Service is written. The WAR file is created at the top level of the EAR file. The default value is `web-services.war`. | String | No
webAppClasses | Comma-separated list of class files that should be packaged in the `WEB-INF/classes` directory of the Web Service's Web application. Use this attribute to specify the Java class that implements a Web Service, SOAP handler classes, and so on. | String | No.