bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

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" on page B-2

- "autotype" on page B-7

- "clientgen" on page B-12

- "servicegen" on page B-19

- "source2wsdd" on page B-28

- "wsdl2Service" on page B-31

- "wspackage" on page B-33

- "wsgen" on page B-36

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

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 | Not available. | 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 | weblogic.webservice.servicegen | 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.
wspackage | Not available. | Packages the components of a WebLogic Web service into a deployable EAR file.
wsgen | Not available. | Upgrades a 6.1 WebLogic Web service to Version 7.0 of WebLogic Server.

Using the Web Services Ant Tasks

To use the Ant tasks, follow these steps:

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

2. Set your environment.

   On Windows NT, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setWLSEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the same directory as the build.xml file:

   >     prompt> ant

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};d:\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="d:\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>

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 when setting the ANTCLASSPATH variable, where WL_HOME is the top-level directory of your WebLogic Platform installation If you need to update the ANTCLASSPATH variable, make the relevant changes to the appropriate file for your operating system.

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.

Using the Web Services Command-Line Utilities

To use the command-line utility equivalents of the Ant tasks, follow these steps:

1. Open a command shell window.

2. Set your environment.

   On Windows NT, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

   On UNIX, execute the setWLSEnv.sh command, located in the directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Platform installation.

3. Execute the utility using the java command, as shown in the following example:

>     prompt> java weblogic.webservice.clientgen \
>                    -ear c:\myapps\myapp.ear \
>                    -serviceName myService \
>                    -packageName myservice.client \
>                     -clientJar c:/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 serializer classes, and the data type mapping information for the web-services.xml file.

- A Java class file that contains a backend component, such as a stateless session EJB, by specifying the javaComponents attribute. The autotype Ant task looks for non-built-in data types used in the component, then generates the corresponding XML Schemas, the serializer classes, and the data type mapping information for the web-services.xml file.

- 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 serializer 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 serializer 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 serializer 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 for the Java class mypackage.MyType:

>     <autotype  javaTypes="mypackage.MyType"
>                targetNamespace="http://www.foobar.com/autotyper"
>                packageName="a.package.name"
>                destDir="d:\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="d:\output" />

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

The following example shows how to use the autotype Ant task against a WSDL file:

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

Attributes

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

Attribute | Description | Required?
--- | --- | ---
schemaFile | Name of a file that contains the XML Schema representation of your non-built-in data types. | You must specify one, and only one, of the following attributes: schemaFile, wsdl, javaTypes, or javaComponents.
wsdl | Full path name or URI of the WSDL that contains the XML Schema description of your non-built-in data type. | You must specify one, and only one, of the following attributes: schemaFile, wsdl, javaTypes, or javaComponents.
javaTypes | Comma-separated list of Java class names that represent your non-built-in data types. The Java classes must be compiled and in your CLASSPATH. For example: javaTypes="my.class1,my.class2" Note: Use the syntax [L classname; to specify an array of the Java data type. For an example, see Example. | You must specify one, and only one, of the following attributes: schemaFile, wsdl, javaTypes, or javaComponents.
javaComponents | 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: 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. | You must specify one, and only one, of the following attributes: schemaFile, wsdl, javaTypes, or javaComponents.
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. | Yes.
typeMappingFile | File that contains data type mapping information for non-built-in data types for which have already generated needed components. 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. The autotype Ant task does not generate non-built-in data type components for any data types listed in this file. | 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. | 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. | No. If you specify this attribute, you cannot also specify packageBase.
targetNamespace | Namespace URI of the Web service. | Yes.

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 Getting the Java Client JAR Files.

Warning: The serializer 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.

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="c:/myapps/myService_client.jar"
>     />

Attributes

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

Attribute | Description | Required?
--- | --- | ---
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. | Either wsdl or ear must be specified.
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 The 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. | Either wsdl or ear must be specified.
warName | Name of the WAR file which contains the Web service(s). The default value is web-services.war. | No. You can specify this attribute only in combination with the ear attribute.
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. | 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. | No.
packageName | Package name into which the generated JAX-RPC client interfaces and stub files should be packaged. | Yes.
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. | 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. | Yes.
overwrite | Specifies whether to overwrite an existing client JAR file. Valid values are True and False. Default value is True. | 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. | No. Use only in combination with the ear attribute.
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. | 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. | No.
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. | No.
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. | Required only if you specified the wsdl attribute and the XML Schema in the WSDL file does not define a target namespace.
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. | Required only if you specified the wsdl attribute and the XML Schema in the WSDL file does not define a target namespace.
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. | No.

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):

- -wsdl uri

- -ear pathname

- -clientJar pathname

- -packageName name

- -warName name

- -serviceName name

- -typeMappings pathname

- -useServerTypes

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.

- Optionally creates a client JAR file that includes the Web service-specific classes, stubs, and interfaces needed by client applications that invoke the Web service. The classes, stubs, and interfaces are based on the JAX-RPC API.

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

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

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

Example

>           <servicegen
>              destEar="c:\myWebService.ear"
>              warName="myWAR.war"
>              contextURI="web_services" >
>              <service
>                  ejbJar="c:\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 one optional <client> element.

The following graphic describes the hierarchy of the 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.

Attribute | Description | Required?
--- | --- | ---
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 c:\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. | 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 servicegen Ant task attempts to merge the contents of the EAR file/directory and information in the web-services.xml file. | 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. | 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. | 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.

Attribute | Description | Required?
--- | --- | ---
ejbJar | JAR file or exploded directory that contains the EJBs that implement the backend component of a Web service operation. The servicegen Ant task introspects the EJBs to automatically generate all the components. | You must specify either the ejbJar, javaClassComponents, or JMS* 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. | You must specify either the ejbJar, javaClassComponents, or JMS* attribute.
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. | 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). | No. Used only in combination with the ejbJar 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). | No. Used only in combination with the ejbJar attribute.
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. | 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 | Yes.
targetNamespace | The namespace URI of the Web service. | Yes.
protocol | Protocol over which this Web service is deployed. Valid values are http and https. The default value is http. | No.
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. | 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. | No.
typeMappingFile | File that contains additional XML data type mapping information. 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. | No.
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. If you specify document for this attribute, the methods that implement the operations of the generated Web service must have only one parameter. 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. Valid values for this attribute are rpc 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. | No.
JMSDestination | JNDI name of a JMS topic or queue. | Yes, if creating a JMS-implemented Web service.
JMSDestinationType | Type of JMS destination, either a Queue or a Topic. Valid values are topic or queue. | Yes, if creating a JMS-implemented Web service.
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. | Yes, if creating a JMS-implemented Web service.
JMSConnectionFactory | JNDI name of the ConnectionFactory used to create a connection to the JMS destination. | Yes, if creating a JMS-implemented Web service.
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. | No.
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 represenation of this non-built-in data type is in your CLASSPATH. | 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.

Attribute | Description | 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. | No.
packageName | Package name into which the generated client interfaces and stub files are packaged. | Yes.
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. | No.
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. | No.

Equivalent Command-Line Utility

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

Warning: If you use the weblogic.webservice.servicegen command-line utility to automatically assemble a Web service, you can create only one Web service in the web-services.xml file.

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

- -destEar pathname

- -warName name

- -ejbJar pathname

- -javaClassComponents list_of_classnames

- -serviceName name

- -serviceURI uri

- -targetNamespace uri

- -protocol protocol

- -expandMethods

- -clientPackageName name

- -clientJarName name

source2wsdd

The source2wsdd Ant task generates a web-services.xml deployment descriptor file from the Java source file for a Java class-implemented WebLogic Web service.

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 Java class If your 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 Java class refers to other Java class files, be sure to set the sourcePath attribute to the directory that contains them.

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

Example

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

Attributes

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

Attribute | Description | Required?
--- | --- | ---
javaSource | Name of the Java source file that implements your Web service component. | Yes.
ddFile | Full pathname of the Web services deployment descriptor file (web-services.xml) which will contain the generated deployment descriptor information. | Yes.
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. | 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 value of this attribute becomes the uri attribute of the <web-service> element in the generated web-services.xml deployment descriptor. | Yes.
sourcePath | Full pathname of the directory that contains any additional classes referred to by the Java source file specified with the javaSource attribute. | 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. | No.

wsdl2Service

The wsdl2Service Ant task takes as input an existing WSDL file, and generates the following WebLogic Web service components:

- the web-services.xml deployment descriptor file

- a Java source file that partially implements the Web service.

The Java source file contains a 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 write the actual code for these methods so that they function as you want.

The wsdl2Service Ant task generates a partial implementation for only one 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 partial implementation 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.

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

Example

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

Attributes

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

Attribute | Description | Required?
--- | --- | ---
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. | Yes.
destDir | The full pathname of the directory that will contain the generated components (web-services.xml file and Java source file that partially implements the Web service.) | Yes.
packageName | The package name for the generated Java source file that partially implements the Web service. | 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. | 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. Set the typeMappingFile attribute equal to this file. | Required only if the operations of the Web service in the WSDL file refer to any non-built-in data types.

wspackage

The wspackage Ant task packages the various components of a WebLogic Web service into a deployable EAR file. It is assumed that you have already generated these 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.

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

Example

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

Attributes

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

Attribute | Description | Required?
--- | --- | ---
output | 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 c:\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. | Yes
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. Note: If you specified an exploded directory with the output attribute, the wspackage task creates an exploded Web application directory, even if you specify a.war suffix for the warName attribute. | 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. | No.
ddFile | Full pathname of an existing Web services deployment descriptor file (web-services.xml). | Yes.
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. | 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. | 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. | No.
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. | No.
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. | No

wsgen

The wsgen Ant task upgrades a Version 6.1 WebLogic Web service to Version 7.0. In particular, it:

- Creates a new web-services.xml file that describes the upgraded Web service. The task uses values found in the 6.1 build.xml file and default values to generate the deployment descriptor.

- Optionally creates a client JAR file that includes all the classes, stubs, and interfaces needed by client applications that invoke the Web service. The classes, stubs, and interfaces are based on the JAX-RPC API.

- Packages all the Web service components into a WAR file called web-services.war, then packages the WAR and EJB JAR files into a deployable EAR file.

The task takes as input the same build.xml file you used in Version 6.1 to create a Web service. You can optionally add two new attributes, as described in "Additional Attributes" on page B-37. The task also takes as input the same archive file or exploded directory that you used to create the 6.1 Web service.

Warning: Do not use this Ant task for assembling a new 7.0 Web service. Instead, use the servicegen Ant task. Because the wsgen Ant task is used only for upgrading Web services from Version 6.1 to 7.0, the task is deprecated in this version of WebLogic Server.

Note: The fully qualified name of the wsgen Ant task is weblogic.ant.taskdefs.webservices.wsgen.WSGenTask.

Example

The following build.xml excerpt is taken from the 6.1 RPC-style Web services example. It includes a new attribute targetNameSpace.

>     <wsgen
>        destpath="weather.ear"
>        context="/weather">
>        <rpcservices path="weather.jar">
>           <rpcservice bean="statelessSession"
>                       uri="/weatheruri"
>                       targetNameSpace="http://www.bea.com/examples"/>
>        </rpcservices>
>     </wsgen>

Additional Attributes

Because you use the 6.1 build.xml file when using wsgen to upgrade your 6.1 Web service to Version 7.0, the attributes and elements of the build.xml file are those documented in the 6.1 version of the Programming WebLogic Web Services guide. For details, see build.xml Attributes and Elements.

You can, however, add the two attributes listed in the following table to your 6.1 build.xml file and wsgen will add the appropriate information to the new web-services.xml deployment descriptor file.

Attribute | Element | Description
--- | --- | ---
targetNameSpace | rpcservice, messageservice | Namespace URI of the Web service. The default value of this attribute, if you do not add it to your existing 6.1 build.xml file, is http://example.org.
packageName | clientjar | Package name into which the generated client interfaces and stub files should be packaged in the client JAR file. The default value of this attribute, if you do not add it to your existing 6.1 build.xml file, is org.example.