bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search

Programming WebLogic Web Services

 Previous Next Contents View as PDF  

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

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.

wsdlgen

Not available.

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 deplorable EAR file.

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

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

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:

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 from a Java class:

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

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"

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.

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:

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 clientgen Ant task does not support solicit-response or notification WSDL operations. This means that if you attempt to create a client JAR file from a WSDL file that contains these types of operations, the Ant task ignores the operations.

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

keepGenerated

Specifies whether the clientgen 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 clientgen Ant task should include only the compiled class file.

Valid values for this attribute are True and False. The default value is True.

No.

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.

No.

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, the clientgen Ant task generates a package name for you.

Note: Although not required, BEA recommends you specify this attribute.

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, the clientgen Ant task generates a base package name for you.

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.

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.

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

 


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:

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

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 four optional elements: <client>, <reliability>, <handlerChain>, and <security>.

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.

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

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.class1,my.class2"

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.

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.

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.

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.

reliability

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

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

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

Attribute

Description

Required?

duplicateElimination

Specifies whether the WebLogic Web Service operations should ignore duplicate invokes from the same client application.

If this attribute is set to True, the Web Service persists the message IDs from client applications that invoke the Web Service so that it can eliminate any duplicate invokes. If this values is set to False, the Web Service does not keep track of duplicate invokes, which means that if a client retries an invoke, both invokes could return values.

Valid values for this attribute are True and False. The default value is True.

No.

persistDuration

The default minimum number of seconds that the Web Service should persist the history of a reliable SOAP message (received from the sender that invoked the Web Service) in its storage.

The Web Service, after recovering from a WebLogic Server crash, does not dispatch persisted messages that have expired.

The default value of this attribute is 60,000.

No.

handlerChain

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

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

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

Attribute

Description

Required?

name

The name of the handler chain.

Default value is serviceNameHandlerChain, where serviceName is the value of the serviceName attribute of the <service> parent element.

No.

handlers

Comma separated fully qualified list of Java class names that implement the handlers in the handler chain. You must include at least one class name.

Note: If the Java class that implements a handler expects initialization parameters, you must edit the generated web-services.xml file and add an <init-params> child element to the <handler> element. For details of these elements, see WebLogic Web Service Deployment Descriptor Elements.

Yes.

security

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

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

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

Attribute

Description

Required?

username

Specifies the username used in the username token of the SOAP response message.

If you do not specify this attribute, the SOAP response message will not include a username token specification.

Only if your SOAP messages require a username token.

password

Specifies the password used in the username token of the SOAP response message.

If you do not specify this attribute, the SOAP response message will not include a username token specification.

Only if your SOAP messages require a username token.

signKeyName

The name of the key and certificate pair, stored in WebLogic Server's keystore, used to digitally sign the entire SOAP body.

If you do not specify this attribute, no part of the SOAP message will be digitally signed.

Only if you want to digitally sign the SOAP message body.

signKeyPass

The password of the key and certificate pair, stored in WebLogic Server's keystore, used to digitally sign the entire SOAP body.

If you do not specify this attribute, no part of the SOAP message will be digitally signed.

Only if you want to digitally sign the SOAP message body.

encryptKeyName

The name of the key and certificate pair, stored in WebLogic Server's keystore, used to encrypt the entire SOAP body.

If you do not specify this attribute, no part of the SOAP message will be encrypted.

Only if you want to encrypt the SOAP message body.

encryptKeyPass

The password of the key and certificate pair, stored in WebLogic Server's keystore, used to encrypt the entire SOAP body.

If you do not specify this attribute, no part of the SOAP message will be encrypted.

Only if you want to encrypt the SOAP message body.

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

 


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.

 


wsdl2Service

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

The generated Java interface file describes the template for the full Java class-implemented WebLogic Web Service. The template includes full method signatures that correspond to the operations in the WSDL file. You must then write a Java class that implements this interface so that the methods function as you want, following the guidelines in Implementing a Web Service By Writing a Java Class" on page 5-4.

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

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

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

packageName.serviceNameImpl

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

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

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

Example

<wsdl2service
wsdl="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 interface file that represents the implementation of your Web Service.)

Yes.

packageName

The package name for the generated Java interface file that represents the implementation of your 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.

 


wsdlgen

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

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

Example

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

Attributes

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

Attribute

Description

Required?

ear

Name of an EAR file or exploded directory that contains the WebLogic Web Service implementation for which the WSDL file should be generated.

Yes.

warName

Name of the WAR file that contains the web-services.xml deployment descriptor file of your Web Service.

Yes.

serviceName

Web Service name for which a corresponding WSDL file should be generated.

The Web Service name corresponds to the <web-service> element in the web-services.xml deployment descriptor file.

If you do not specify the serviceName attribute, the wsdlgen task generates a WSDL file for the first service name found in the web-services.xml file.

No.

wsdlFile

Name of the output file that will contain the generated WSDL.

Yes.

defaultEndpoint

Endpoint Web Service URL to be included in the generated WSDL file.

The default value is http://localhost:7001.

No.

 


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:

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

 

Back to Top Previous Next