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

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:

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.

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.

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:

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.

Open a command shell window.

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 [Lclassname; 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 `[Lclassname;` 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.

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 startMethod` `(params, AsyncInfo asyncInfo);result` `endMethod(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.

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

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 `serviceNameHandlerChain`, where `serviceName` is the value of the `serviceName` attribute of the `<service>` parent element.	String	No.

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 serviceNameHandlerChain, 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.

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

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 `serviceNameImpl`, where `serviceName` refers to the value of the similarly-named attribute of the `wsdl2Service` Ant task. The name of the generated Java file is `serviceNameImpl.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.