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 Me