Programming Web Services for WebLogic Server

Ant Task Reference

The following sections provide reference information about the WebLogic Web Services Ant tasks:

For detailed information on how to integrate and use these Ant tasks in your development environment to program a Web Service and a client application that invokes the Web Service, see:

Overview of WebLogic Web Services Ant Tasks

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 Web Service-related artifacts.

The Apache Web site provides other useful Ant tasks for packaging EAR, WAR, and EJB JAR files. For more information, see http://jakarta.apache.org/ant/manual/.

Note: The Apache Jakarta Web site publishes online documentation for only the most current version of Ant, which might be different from the version of Ant that is bundled with WebLogic Server. To determine the version of Ant that is bundled with WebLogic Server, run the following command after setting your WebLogic environment:

prompt> ant -version

To view the documentation for a specific version of Ant, download the Ant zip file from http://archive.apache.org/dist/ant/binaries/ and extract the documentation.

List of Web Services Ant Tasks

The following table provides an overview of the Web Service Ant tasks provided by BEA.

Table A-1 WebLogic Web Services Ant Tasks

Ant Task	Description
clientgen	Generates the JAX-RPC Service stubs and other client-side files used to invoke a Web Service.
jwsc	Compiles a JWS-annotated file into a Web Service. JWS refers to Java Web Service.
wsdlc	Generates a partial Web Service implementation based on a WSDL file.

Using the Web Services Ant Tasks

To use the Ant tasks:

Set your environment.

On Windows NT, execute the setDomainEnv.cmd command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME\user_projects\domains\domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.
On UNIX, execute the setDomainEnv.sh command, located in your domain directory. The default location of WebLogic Server domains is BEA_HOME/user_projects/domains/domainName, where BEA_HOME is the top-level installation directory of the BEA products and domainName is the name of your domain.

Create a file called build.xml that will contain a call to the Web Services Ant tasks.

The following example shows a simple build.xml file with a single target called clean: <project name="my-webservice"> <target name="clean"> <delete> <fileset dir="tmp" /> </delete> </target> </project>
This clean target deletes all files in the temp subdirectory.
Later sections provide examples of specifying the Ant task in the build.xml file.

For each WebLogic Web Service Ant task you want to execute, add an appropriate task definition and target to the build.xml file using the <taskdef> and <target> elements. The following example shows how to add the jwsc Ant task to the build file; the attributes of the task have been removed for clarity:

  <taskdef name="jwsc"
      classname="weblogic.wsee.tools.anttasks.JwscTask" />

  <target name="build-service">
      <jwsc attributes go here...>
      ...
      </jwsc>
  </target>

You can, of course, name the WebLogic Web Services Ant tasks anything you want by changing the value of the name attribute of the relevant <taskdef> element. For consistency, however, this document uses the names jwsc, clientgen, and wsdlc throughout.

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

prompt> ant build-service

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 jwsc Ant task to add a new directory to the CLASSPATH variable:

<jwsc srcdir="MyJWSFile.java"
      classpath="${java.class.path};my_fab_directory"
   ...
</jwsc>

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

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

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="myClassID">
   <pathelement path="${java.class.path}"/>
   <pathelement path="${additional.path1}"/>
   <pathelement path="${additional.path2}"/>
</path>

<jwsc ....>
   <classpath refid="myClassID" />
...
</jwsc>

Note: The Java Ant utility included in WebLogic Server uses the ant (UNIX) or ant.bat (Windows) configuration files in the WL_HOME\server\bin directory to set various Ant-specific variables, where WL_HOME is the top-level directory of your WebLogic Server installation If you need to update these Ant variables, 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 WebLogic Web Service Ant tasks have attributes that you can use to specify a file, such as a WSDL or an XML Schema file.

The Ant tasks process these files in a case-sensitive way. This means that if, for example, the XML Schema file specifies two user-defined types whose names differ only in their capitalization (for example, MyReturnType and MYRETURNTYPE), the clientgen Ant task correctly generates two separate sets of Java source files for the Java representation of the user-defined 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.

clientgen

The clientgen Ant task generates, from an existing WSDL file, the client component files that client applications use to invoke both WebLogic and non-WebLogic Web Services. These files include:

The Java source code for the JAX-RPC Stub and Service interface implementations for the particular Web Service you want to invoke.
The Java source code for any user-defined XML Schema data types included in the WSDL file.
The JAX-RPC mapping deployment descriptor file which contains information about the mapping between the Java user-defined data types and their corresponding XML Schema types in the WSDL file.
A client-side copy of the WSDL file.

Two types of client applications use the generated artifacts of clientgen to invoke Web Services:

Stand-alone Java clients that do not use the J2EE client container.
J2EE clients, such as EJBs, JSPs, and Web Services, that use the J2EE client container.

Taskdef Classname

  <taskdef name="clientgen"
      classname="weblogic.wsee.tools.anttasks.ClientGenTask" />

Examples

<taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />

...

<target name="build_client">

<clientgen
    wsdl="http://example.com/myapp/myservice.wsdl"
    destDir="/output/clientclasses"
    packageName="myapp.myservice.client"
    serviceName="StockQuoteService" />

<javac ... />

</target>

When the sample build_client target is executed, clientgen uses the WSDL file specified by the wsdl attribute to generate all the client-side artifacts needed to invoke the Web Service specified by the serviceName attribute. The clientgen Ant task generates all the artifacts into the /output/clientclasses directory. All generated Java code is in the myapp.myservice.client package. After clientgen has finished, the javac Ant task then compiles the Java code, both clientgen-generated as well as your own client application that uses the generated artifacts and contains your business code.

You typically execute the clientgen Ant task on a WSDL file that is deployed on the Web and accessed using HTTP. Sometimes, however, you might want to execute clientgen on a static WSDL file that is packaged in an archive file, such as the WAR or JAR file generated by the jwsc Ant task. In this case you must use the following syntax for the wsdl attribute:

wsdl="jar:file:archive_file!WSDL_file"

where archive_file refers to the full (or relative to the current directory) name of the archive file and WSDL_file refers to the full pathname of the WSDL file, relative to the root directory of the archive file. For example:

    <clientgen
      wsdl="jar:file:output/myEAR/examples/webservices/simple/SimpleImpl.war!/WEB-INF/SimpleService.wsdl"
      destDir="/output/clientclasses"
      packageName="myapp.myservice.client"/>

The preceding example shows how to execute clientgen on a static WSDL file called SimpleService.wsdl, which is packaged in the WEB-INF directory of a WAR file called SimpleImpl.war, which is located in the output/myEAR/examples/webservices/simple sub-directory of the directory that contains the build.xml file.

Attributes

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

Table A-2 Attributes of the clientgen Ant Task

Attribute	Description	Data Type	Required?
destDir	Directory into which the `clientgen` Ant task generates the client source code, WSDL, and client deployment descriptor files. You can set this attribute to any directory you want. However, if you are generating the client component files to invoke a Web Service from an EJB, JSP, or other Web Service, you typically set this attribute to the directory of the J2EE component which holds shared classes, such as `META-INF` for EJBs, `WEB-INF/classes` for Web Applications, or `APP-INF/classes` for Enterprise Applications. If you are invoking the Web Service from a stand-alone client, then you can generate the client component files into the same source code directory hierarchy as your client application code.	String	Yes.
generatePolicyMethods	Specifies whether the `clientgen` Ant task should include policy-loading methods in the generated JAX-RPC stubs. These methods can be used by client applications to load a local policy statement. If you specify `True`, four flavors of a method called `getXXXSoapPort()` are added as extensions to the JAX-RPC `Service` interface in the generated client stubs, where `XXX` refers to the name of the Web Service. Client applications can use these methods to load and apply local policy statements, rather than apply any policy statements deployed with the Web Service itself. Client applications can specify whether the local policy statement applies to inbound, outbound, or both SOAP messages and whether to load the local policy from an InputStream or a URI. Valid values for this attribute are `True` or `False`. The default value is `False`, which means the additional methods are not generated. See Using a Client-Side Security WS-Policy File for more information.	Boolean	No.
generateAsyncMethods	Specifies whether the `clientgen` Ant task should include methods in the generated JAX-RPC stubs that client applications can use to invoke a Web Service operation asynchronously. For example, if you specify `True` (which is also the default value), and one of the Web Service operations in the WSDL is called `getQuote`, then the `clientgen` Ant task also generates a method called `getQuoteAsync` in the JAX-RPC stubs which client applications invoke instead of the original `getQuote` method. This asynchronous flavor of the operation also has an additional parameter, of data type `weblogic.wsee.async.AsyncPreCallContext`, that client applications can use to set asynchronous properties, contextual variables, and so on. See Invoking a Web Service Using Asynchronous Request-Response for full description and procedures about this feature. Note: If the Web Service operation is marked as one-way, the `clientgen` Ant task never generates the asynchronous flavor of the JAX-RPC stub, even if you explicitly set the `generateAsyncMethods` attribute to `True`. Valid values for this attribute are `True` or `False`. The default value is `True`, which means the asynchronous methods are generated by default.	Boolean	No.
overwrite	Specifies whether the client component files (source code, WSDL, and deployment descriptor files) generated by this Ant task should be overwritten if they already exist. If you specify `True`, new artifacts are always generated and any existing artifacts are overwritten. If you specify `False`, the Ant task overwrites only those artifacts that have changed, based on the timestamp of any existing artifacts. Valid values for this attribute is `True` or `False`. The default value is `True`.	Boolean	No.
packageName	Package name into which the generated JAX-RPC client interfaces and stub files are packaged. If you do not specify this attribute, the `clientgen` Ant task generates Java files whose package name is based on the targetNamespace of the WSDL file. For example, if the targetNamespace is `http://example.org`, then the package name might be `org.example` or something similar. If you want control over the package name, rather than let the Ant task generate one for you, then you should specify this attribute. If you do specify this attribute, BEA recommends you use all lower-case letters for the package name.	String	No.
serviceName	Name of the Web Service in the WSDL file for which the corresponding client component files should be generated. The Web Service name corresponds to the `<service>` element in the WSDL file. The generated JAX-RPC mapping file and client-side copy of the WSDL file will use this name. For example, if you set `serviceName` to `CuteService`, the JAX-RPC mapping file will be called `cuteService_java_wsdl_mapping.xml` and the client-side copy of the WSDL will be called `CuteService_saved_wsdl.wsdl`.	String	This attribute is required only if the WSDL file contains more than one `<service>` element. The Ant task returns an error if you do not specify this attribute and the WSDL file contains more than one `<service>` element.
wsdl	Full path name or URL of the WSDL that describes a Web Service (either WebLogic or non-WebLogic) for which the client component files should be generated. The generated stub factory classes in the client JAR file use the value of this attribute in the default constructor.	String	Yes.
autoDetectWrapped	Specifies whether the `clientgen` Ant task should try to determine whether the parameters and return type of document-literal Web Services are of type wrapped or bare. When the `clientgen` Ant task parses a WSDL file to create the JAX-RPC stubs, it attempts to determine whether a document-literal Web Service uses wrapped or bare parameters and return types based on the names of the XML Schema elements, the name of the operations and parameters, and so on. Depending on how the names of these components match up, the `clientgen` Ant task makes a best guess as to whether the parameters are wrapped or bare. In some cases, however, you might want the Ant task to always assume that the parameters are of type bare; in this case, set the `autoDetectWrapped` attribute to `False`. Valid values for this attribute are `True` or `False`. The default value is `True`.	Boolean	No.
handlerChainFile	Specifies the name of the XML file that describes the client-side SOAP message handlers that execute when a client application invokes a Web Service. Each handler specified in the file executes twice: directly before the client application sends the SOAP request to the Web Service directly after the client application receives the SOAP response from the Web Service If you do not specify this clientgen attribute, then no client-side handlers execute, even if they are in your CLASSPATH. See Creating and Using Client-Side SOAP Message Handlers for details and examples about creating client-side SOAP message handlers.	String	No
jaxRPCWrappedArrayStyle	When the `clientgen` Ant task is generating the Java equivalent to XML Schema data types in the WSDL file, and the task encounters an XML complex type with a single enclosing sequence with a single element with the `maxOccurs` attribute equal to `unbounded`, the task generates, by default, a Java structure whose name is the lowest named enclosing complex type or element. To change this behavior so that the task generates a literal array instead, set the `jaxRPCWrappedArrayStyle` to `False`. Valid values for this attribute are `True` or `False`. The default value is `True`.	Boolean	No.
classpath	Additions to the CLASSPATH. Use this attribute to add JAR files or directories that contain Java classes to the CLASSPATH used to compile the JWS file.	String	No.
classpathref	Additions to the CLASSPATH, but specified as a reference to a path defined elsewhere in the `build.xml` file.	String	No

jwsc

The jwsc Ant task takes as input a Java Web Service (JWS) file that contains both standard (JSR-181) and WebLogic-specific JWS annotations and generates all the artifacts you need to create a WebLogic Web Service. The generated artifacts include:

Java source files that implement a standard JSR-921 Web Service, such as the service endpoint interface (called JWS_ClassNamePortType.java, where JWS_ClassName refers to the JWS class).
All required deployment descriptors. In addition to the standard webservices.xml and JAX-RPC mapping files, the jwsc Ant task also generates the WebLogic-specific Web Services deployment descriptor (weblogic-webservices.xml).
The XML Schema representation of any Java user-defined types used as parameters or return values to the methods of the JWS files that are specified to be exposed as public operations.
The WSDL file that publicly describes the Web Service.

After generating all the artifacts, the jwsc Ant task compiles the Java and JWS files, packages the compiled classes and generated artifacts into a deployable JAR archive file, and finally creates an exploded Enterprise Application directory that contains the JAR file. You then deploy this Enterprise Application to WebLogic Server. If you specify an existing Enterprise Application as the destination directory to jwsc, the Ant task updates any existing application.xml file with the new Web Services information.

Note: The jwsc Ant task typically generates a Java class-implemented Web Service from the specified JWS file and packages it into a Web Application WAR file. In the following cases, however, it creates a stateless session EJB-implemented Web Service and packages it into an EJB JAR file:

The JWS file specifies any of the following JWS annotations: weblogic.jws.Conversation; weblogic.jws.Conversational; weblogic.jws.ServiceClient.
The JWS file uses any EJBGen annotation.
The JWS file explicitly implements javax.ejb.SessionBean.

You invoke and use Java class- and stateless session EJB-implemented Web Services in exactly the same way, so this implementation detail is typically not important to a programmer. It is mentioned in this section only for the case in which a programmer needs to update the Web Service archive and needs to know if it is a WAR or an EJB JAR.

You specify the JWS file you want the jwsc Ant task to compile using the <jws> child-element of the Ant task. The <jws> element includes three optional child-elements for specifying the transports (HTTP/S or JMS) that are used to invoke the Web Service.

See Creating a Web Service With User-Defined Data Types for a complete example of using the jwsc Ant task.

Taskdef Classname

<taskdef name="jwsc"
      classname="weblogic.wsee.tools.anttasks.JwscTask" />

Examples

The following examples show how to use the jwsc Ant task by including it in a build-service target of the build.xml Ant file that iteratively develops your Web Service. See Common Web Services Use Cases and Examples, and Iterative Development of WebLogic Web Services, for samples of complete build.xml files that contain many other targets that are useful when iteratively developing a WebLogic Web Service, such as clean, deploy, client, and run.

The following sample shows a very simple usage of jwsc:

  <target name="build-service">
    <jwsc
      srcdir="src"
      destdir="output/TestEar">
      <jws file="examples/webservices/test/TestServiceImpl.java" />
    </jwsc>
  </target>

In the example, the JWS file called TestServiceImpl.java is located in the src/examples/webservices/test sub-directory of the directory that contains the build.xml file. The jwsc Ant task generates the Web Service artifacts in the output/TestEar sub-directory. In addition to the Web Service JAR file, the jwsc Ant task also generates the application.xml file that describes the Enterprise Application in the output/TestEar/META-INF directory.

The following example shows a more complicated use of jwsc:

  <path id="add.class.path">
    <pathelement path="${myclasses-dir}"/>
    <pathelement path="${java.class.path}"/>
  </path>

...

  <target name="build-service2">
    <jwsc
      srcdir="src" destdir="output/TestEar"
      verbose="on" debug="on"
      keepGenerated="yes"
      classpathref="add.class.path">
      <jws file="examples/webservices/test/TestServiceImpl.java" />
      <jws file="examples/webservices/test/AnotherTestServiceImpl.java"/>
      <jws file="examples/webservices/test/SecondTestServiceImpl.java" />
    </jwsc>
  </target>

The example shows how to enable debugging and verbose output, and how to specify that jwsc not regenerate any existing temporary files in the output directory. The example shows how to use classpathref attribute to add to the standard CLASSPATH by referencing a path called add.class.path that has been specified elsewhere in the build.xml file using the standard Ant <path> target.

The example also shows how to specify multiple JWS files, resulting in separate Web Services packaged in their own JAR files, although all are still deployed as part of the same Enterprise Application.

The following example shows how to specify the transport that is used to invoke the Web Service:

  <target name="build-service3">
    <jwsc
      srcdir="src"
      destdir="output/TestEar">

      <jws file="examples/webservices/test/TestServiceImpl.java">

        <WLHttpTransport
                contextPath="TestService" serviceUri="TestService"
                portName="TestServicePort1"/>
      </jws>

    </jwsc>

  </target>

The preceding example shows how to specify that the HTTP transport is used to invoke the Web Service.

Attributes and Child Elements of the jwsc Ant Task

The jwsc Ant task has a variety of attributes and one child element: <jws>. The <jws> element has three optional child elements: <WLHttpTransport>, <WLHttpsTransport>, and <WLJMSTransport>. See Transport Child Elements for common information about using the transport elements.

The following graphic describes the hierarchy of the jwsc Ant task.

Figure A-1 Element Hierarchy of jwsc Ant Task

Element Hierarchy of jwsc Ant Task

The following table describes the attributes of the main jwsc Ant task.

Table A-3 Attributes of the jwsc Ant Task

Attribute	Description	Required?
destdir	The full pathname of the directory that will contain the compiled JWS files, XML Schemas, WSDL, and generated deployment descriptor files, all packaged into a JAR or WAR file. The `jwsc` Ant task creates an exploded Enterprise Application at the specified directory, or updates one if you point to an existing application directory. The jwsc task generates the JAR or WAR file that implements the Web Service in this directory, as well as other needed files, such as the `application.xml` file in the `META-INF` directory; the `jwsc` Ant task updates an existing `application.xml` file if it finds one, or creates a new one if not. Use the `applicationXML` attribute to specify a different `application.xml` from the default.	Yes.
keepGenerated	Specifies whether the Java source files and artifacts generated by this Ant task should be regenerated if they already exist. If you specify `no`, new Java source files and artifacts are always generated and any existing artifacts are overwritten. If you specify `yes`, the Ant task regenerates only those artifacts that have changed, based on the timestamp of any existing artifacts. Valid values for this attribute are `yes` or `no`. The default value is `no`.	No.
sourcepath	The full pathname of top-level directory that contains the Java files referenced by the JWS file, such as JavaBeans used as parameters or user-defined exceptions. The Java files are in sub-directories of the sourcepath directory that correspond to their package names. The `sourcepath` pathname can be either absolute or relative to the directory which contains the Ant `build.xml` file. For example, if `sourcepath` is `/src` and the JWS file references a JavaBean called `MyType.java` which is in the `webservices.financial` package, then this implies that the `MyType.java` Java file is stored in the `/src/webservices/financial` directory. The default value of this attribute is the value of the `srcdir` attribute. This means that, by default, the JWS file and the objects it references are in the same package. If this is not the case, then you should specify the `sourcepath` accordingly.	No.
enableAsyncService	Specifies whether the Web Service is using one or more of the asynchronous features of WebLogic Web Service: Web Service reliable messaging, asynchronous request-response, buffering, or conversations. In the case of Web Service reliable messaging, you must ensure that this attribute is enabled for both the reliable Web Service and the Web Service that is invoking the operations reliably. In the case of the other features (conversations, asynchronous request-response, and buffering), the attribute must be enabled only on the client Web Service. When this attribute is set to `true` (default value), WebLogic Server automatically deploys internal modules that handle the asynchronous Web Service features. Therefore, if you are not using any of these features in your Web Service, consider setting this attribute to `false` so that WebLogic Server does not waste resources by deploying unneeded internal modules. Valid values for this attribute are `true` and `false`. The default value is `true`.	No.
verbose	Enables verbose output for debugging purposes. Valid values for this attribute are `on` or `off`. The default value is `off`, which means verbose output is not enabled.	No.
srcdir	The full pathname of top-level directory that contains the JWS file you want to compile (specified with the `file` attribute of the `<jws>` child element). The JWS file is in sub-directories of the `srcdir` directory that corresponds to its package name. The `srcdir` pathname can be either absolute or relative to the directory which contains the Ant `build.xml` file. For example, if `srcdir` is `/src` and the JWS file called `MyService.java` is in the `webservices.financial` package, then this implies that the `MyService.java` JWS file is stored in the `/src/webservices/financial` directory.	Yes.
classpath	Additions to the CLASSPATH. Use this attribute to add JAR files or directories that contain Java classes to the CLASSPATH used to compile the JWS file.	No.
classpathref	Additions to the CLASSPATH, but specified as a reference to a path defined elsewhere in the `build.xml` file.	No.
sourcepathref	Additions to the sourcepath, but specified as a reference to a path defined elsewhere in the `build.xml` file.	No.
nowarn	Specifies whether the compiler should print warning messages or not. Valid values for this attribute are `off` or `on`. The default value is `off`, which means that warnings are printed.	No.
debug	Specifies whether the jwsc Ant task should print debugging information as it compiles your JWS file. Valid values for this attribute are `on` or `off`. The default value is `off`.	No.
optimize	Specifies whether optimization is enabled when compiling JWS files. Valid values for this attribute are `on` or `off`. The default value is `off`.	No.
includeAntRuntime	Specifies whether to include the Ant runtime libraries in the CLASSPATH. Valid values for this attribute are `yes` or `no`. The default value is `yes`.	No.
includeJavaRuntime	Specifies whether to include the default runtime libraries of the Java Virtual Machine which is executing the Ant task in the CLASSPATH. Valid values for this attribute are `yes` or `no`. The default value is `no`.	No.
fork	Specifies whether the jwsc Ant task is executed using the JDK compiler externally. Valid values for this attribute are `yes` and `no`. The default value is `no`.	No.
failonerror	Specifies whether the compilation of the JWS file should continue, even if errors are encountered. Valid values for this attribute are `true` and `false`. The default value is `true`.	No.
tempdir	Specifies the name of the directory that will contain any temporary files used by jwsc. This attribute is useful if the compilation of JWS files is failing due to excessively long path names, in particular on Microsoft Windows operating systems. The default value of this attribute is the value of the `java.io.tmpdir` System property.	No.
deprecation	Specifies whether information about deprecated classes in both the JWS file and generated Java classes should be enabled when compiling the JWS file. Valid values for this attribute are `on` and `off`. The default value is `off`.	No.
applicationXml	Specifies the full name and path of the `application.xml` deployment descriptor of the Enterprise Application. If you specify an existing file, the `jwsc` Ant task updates it to include the Web Services information. If the file does not exist, `jwsc` creates it. The jwsc Ant task also creates or updates the corresponding `weblogic-application.xml` file in the same directory. If you do not specify this attribute, `jwsc` creates or updates the file `destDir/META-INF/application.xml`, where `destDir` is the `jwsc` attribute.	No
srcEncoding	Specifies the character encoding of the input files, such as the JWS file or configuration XML files. Examples of character encodings are SHIFT-JIS and UTF-8. The default value of this attribute is the character encoding set for the JVM.	No.
destEncoding	Specifies the character encoding of the output files, such as the deployment descriptors and XML files. Examples of character encodings are SHIFT-JIS and UTF-8. The default value of this attribute is UTF-8.	No.

jws

The <jws> child element of the jwsc Ant task specifies the name of a JWS file that implements your Web Service and for which the Ant task should generate Java code and supporting artifacts and then package into a deployable JAR file inside of an Enterprise Application.

You must specify at least one <jws> element. If you specify more than one, the jwsc Ant task generates a separate Web Service for each JWS file, each of which is packaged in its own JAR file.

The following table describes the attributes of the <jws> child element of the jwsc Ant task.

Table A-4 Attributes of the <jws> Child Element of the jwsc Ant Task

Attribute	Description	Required?
file	The name of the JWS file that you want to compile. The `jwsc` Ant task looks for the file in the `srcdir` directory.	Yes.
explode	Specifies whether the generated JAR file which contains the deployable Web Service is in exploded directory format or not. Valid values for this attribute are `true` or `false`. Default value is `false`, which means that the generated JAR file is archived in a JAR and not in an exploded directory format.	No.
name	The name of the generated JAR file (or exploded directory, if the `explode` attribute is set to `true`) that contains the deployable Web Service. If an actual JAR archive file is generated, the name of the file will also have a `.jar` or `.war` extension (depending on whether `jwsc` generates an EJB or Java class implementation.) The default value of this attribute is the name of the JWS file, specified by the `file` attribute.	No.
includeSchemas	The full pathname of the XML Schema file that describes an `XMLBeans` parameter or return value of the Web Service. To specify more than one XML Schema file, use either a comma or semi-colon as a delimiter: `includeSchemas="po.xsd,customer.xsd"` This attribute is only supported in the case where the JWS file explicitly uses an `XMLBeans` data type as a parameter or return value of a Web Service operation. If you are not using the `XMLBeans` data type, the `jwsc` Ant task returns an error if you specify this attribute. Additionally, you can use this attribute only for Web Services whose SOAP binding is document-literal-bare. Because the default SOAP binding of a WebLogic Web Service is document-literal-wrapped, the corresponding JWS file must include the following JWS annotation: `@SOAPBinding( style=SOAPBinding.Style.DOCUMENT, use=SOAPBinding.Use.LITERAL, parameterStyle=SOAPBinding.ParameterStyle.BARE)` For more information on `XMLBeans`, see http://dev2dev.bea.com/technologies/xmlbeans/index.jsp. Note: As of WebLogic Server 9.1, using XMLBeans 1.X data types (in other words, extensions of `com.bea.xml.XmlObject`) as parameters or return types of a WebLogic Web Service is deprecated. New applications should use XMLBeans 2.x data types.	Required if you are using an `XMLBeans` data type as a parameter or return value.
compiledWsdl	Full pathname of the JAR file generated by the `wsdlc` Ant task based on an existing WSDL file. The JAR file contains the JWS interface file that implements a Web Service based on this WSDL, as well as data binding artifacts for converting parameter and return value data between its Java and XML representations; the XML Schema section of the WSDL defines the XML representation of the data. You use this attribute only in the "starting from WSDL" use case, in which you first use the wsdlc Ant task to generate the JAR file, along with the JWS file that implements the generated JWS interface. After you update the JWS implementation class with business logic, you run the `jwsc` Ant task to generate a deployable Web Service, using the `file` attribute to specify this updated JWS implementation file. You do not use the `compiledWsdl` attribute for the "starting from Java" use case in which you write your JWS file from scratch and the WSDL file that describes the Web Service is generated by the WebLogic Web Services runtime.	Only required for the "starting from WSDL" use case.
wsdlOnly	Specifies that only a WSDL file should be generated for this JWS file. Note: Although the other artifacts, such as the deployment descriptors and service endpoint interface, are not generated, data binding artifacts are generated because the WSDL must include the XML Schema that describes the data types of the parameters and return values of the Web Service operations. The WSDL is generated into the `destDir` directory. The name of the file is `JWS_ClassNameService.wsdl`, where `JWS_ClassName` refers to the name of the JWS class. `JWS_ClassNameService` is also the name of Web Service in the generated WSDL file. Valid values for this attribute are `true` or `false`. The default value is `false`, which means that all artifacts are generated by default, not just the WSDL file.	No.

Transport Child Elements

When you program your JWS file, you can use an annotation to specify the transport that clients use to invoke the Web Service, in particular @weblogic.jws.WLHttpTransport, @weblogic.jws.WLHttpsTransport, or @weblogic.jws.WLJMSTransport. You can specify only one of these annotations in the JWS file. However, a programmer might not know at the time that they are coding the JWS file which transports best suits their needs. For this reason, it is best to specify the transport at build-time with one of the following transport child-elements of the <jws> element:

You can specify exactly zero or one of the preceding transport elements for a particular JWS file. If you do not specify any transport, as either one of the transport elements to the jwsc Ant task or a transport annotation in the JWS file, then the Web Service's default URL corresponds to the default value of the WLHttpTransport element. Finally, whatever transport you specify to jwsc overrides any transport annotation in the JWS file.

WLHttpTransport

Use the WLHttpTransport element to specify the context path and service URI sections of the URL used to invoke the Web Service over the HTTP transport, as well as the name of the port in the generated WSDL.

See Transport Child Elements for guidelines to follow when specifying this element.

The following table describes the attributes of the <WLHttpTransport> child element of the <jws> element.

Table A-5 Attributes of the <WLHttpTransport> Child Element of the <jws> Element

Attribute

Description

Required?

contextPath

Context root of the Web Service.

For example, assume the deployed WSDL of a WebLogic Web Service is as follows:

http://hostname:7001/financial/GetQuote?WSDL

The contextPath for this Web Service is financial.

The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is HelloWorldImpl.java, then the default value of its contextPath is HelloWorldImpl.

No.

serviceUri

Web Service URI portion of the URL.

For example, assume the deployed WSDL of a WebLogic Web Service is as follows:

http://hostname:7001/financial/GetQuote?WSDL

The serviceUri for this Web Service is GetQuote.

No.

portName

The name of the port in the generated WSDL. This attribute maps to the name attribute of the <port> element in the WSDL.

The default value of this attribute is based on the @javax.jws.WebService annotation of the JWS file. In particular, the default portName is the value of the name attribute of @WebService annotation, plus the actual text SoapPort. For example, if @WebService.name is set to MyService, then the default portName is MyServiceSoapPort.

No.

WLHttpsTransport

Use the WLHttpsTransport element to specify the context path and service URI sections of the URL used to invoke the Web Service over the secure HTTPS transport, as well as the name of the port in the generated WSDL.

See Transport Child Elements for guidelines to follow when specifying this element.

The following table describes the attributes of the <WLHttpsTransport> child element of the <jws> element.

Table A-6 Attributes of the <WLHttpsTransport> Child Element of the <jws> Element

Attribute	Description	Required?
contextPath	Context root of the Web Service. For example, assume the deployed WSDL of a WebLogic Web Service is as follows: `https://hostname:7001/financial/GetQuote?WSDL` The contextPath for this Web Service is `financial`. The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its contextPath is `HelloWorldImpl`.	No.
serviceUri	Web Service URI portion of the URL. For example, assume the deployed WSDL of a WebLogic Web Service is as follows: `https://hostname:7001/financial/GetQuote?WSDL` The serviceUri for this Web Service is `GetQuote`. The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its serviceUri is `HelloWorldImpl`.	No.
portName	The name of the port in the generated WSDL. This attribute maps to the `name` attribute of the `<port>` element in the WSDL. The default value of this attribute is based on the `@javax.jws.WebService` annotation of the JWS file. In particular, the default portName is the value of the `name` attribute of `@WebService` annotation, plus the actual text `SoapPort`. For example, if `@WebService.name` is set to `MyService`, then the default portName is `MyServiceSoapPort`.	No.

Attribute

Description

Required?

contextPath

Context root of the Web Service.

For example, assume the deployed WSDL of a WebLogic Web Service is as follows:

https://hostname:7001/financial/GetQuote?WSDL

The contextPath for this Web Service is financial.

No.

serviceUri

Web Service URI portion of the URL.

For example, assume the deployed WSDL of a WebLogic Web Service is as follows:

https://hostname:7001/financial/GetQuote?WSDL

The serviceUri for this Web Service is GetQuote.

No.

portName

The name of the port in the generated WSDL. This attribute maps to the name attribute of the <port> element in the WSDL.

The default value of this attribute is based on the @javax.jws.WebService annotation of the JWS file. In particular, the default portName is the value of the name attribute of @WebService annotation, plus the actual text SoapPort. For example, if @WebService.name is set to MyService, then the default portName is MyServiceSoapPort.

No.

WLJMSTransport

Use the WLJMSTransport element to specify the context path and service URI sections of the URL used to invoke the Web Service over the JMS transport, as well as the name of the port in the generated WSDL. You also specify the name of the JMS queue and connection factory that you have already configured for JMS transport.

See Transport Child Elements for guidelines to follow when specifying this element.

The following table describes the attributes of the <WLJMSTransport> child element of the <jws> element.

Table A-7 Attributes of the <WLJMSTransport> Child Element of the <jws> Element

Attribute	Description	Required?
contextPath	Context root of the Web Service. For example, assume the deployed WSDL of a WebLogic Web Service is as follows: `http://hostname:7001/financial/GetQuote?WSDL` The contextPath for this Web Service is `financial`. The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its contextPath is `HelloWorldImpl`.	No.
serviceUri	Web Service URI portion of the URL. For example, assume the deployed WSDL of a WebLogic Web Service is as follows: `http://hostname:7001/financial/GetQuote?WSDL` The serviceUri for this Web Service is `GetQuote`. The default value of this attribute is the name of the JWS file, without its extension. For example, if the name of the JWS file is `HelloWorldImpl.java`, then the default value of its serviceUri is `HelloWorldImpl`.	No
portName	The name of the port in the generated WSDL. This attribute maps to the `name` attribute of the `<port>` element in the WSDL. The default value of this attribute is based on the `@javax.jws.WebService` annotation of the JWS file. In particular, the default portName is the value of the `name` attribute of `@WebService` annotation, plus the actual text `SoapPort`. For example, if `@WebService.name` is set to `MyService`, then the default portName is `MyServiceSoapPort`.	No.
queue	The JNDI name of the JMS queue that you have configured for the JMS transport. See Using JMS Transport as the Connection Protocol for details about using JMS transport. The default value of this attribute, if you do not specify it, is `weblogic.wsee.DefaultQueue`. You must still create this JMS queue in the WebLogic Server instance to which you deploy your Web Service.	No.

wsdlc

The wsdlc Ant task generates, from an existing WSDL file, a set of artifacts that together provide a partial Java implementation of the Web Service described by the WSDL file. In particular, the Ant task generates:

A JWS interface file that implements the Web Service described by the WSDL file. The interface includes full method signatures that implement the Web Service operations, and JWS annotations (such as @WebService and @SOAPBinding) that implement other aspects of the Web Service.

The wsdlc Ant task generates artifacts for the first <service> element it finds in the WSDL file. You can specify a specific WSDL <binding> by using the srcBindingName attribute.

Warning: The JWS interface is generated into a JAR file, neither of which you should ever update. It is discussed in this section only because later you need to specify this JAR file to the jwsc Ant task when you compile your JWS implementation file into a Web Service.

Data binding artifacts used by WebLogic Server to convert between the XML and Java representations of the Web Service parameters and return values. The XML Schema of the data types is specified in the WSDL, and the Java representation is generated by the wsdlc Ant task.

Warning: These artifacts are generated into a JAR file, along with the JWS interface file, none of which you should ever update. It is discussed in this section only because later you need to specify this JAR file to the jwsc Ant task when you compile your JWS implementation file into a Web Service.

A JWS file that contains a stubbed-out implementation of the generated JWS interface.
Optional Javadocs for the generated JWS interface.

After running the wsdlc Ant task, (which typically you only do once) you update the generated JWS implementation file, in particular by adding Java code to the methods so that they function as you want. The generated JWS implementation file does not initially contain any business logic because the wsdlc Ant task obviously does not know how you want your Web Service to function, although it does know the shape of the Web Service, based on the WSDL file.

When you code the JWS implementation file, you can also add additional JWS annotations, although you must abide by the following rules:

The only standard JSR-181 JWS annotations you can include in the JWS implementation file are @WebService, @HandlerChain, @SOAPMessageHandler, and @SOAPMessageHandlers. If you specify any other JWS-181 JWS annotations, the jwsc Ant task will return an error when you try to compile the JWS file into a Web Service.
Additionally, you can specify only the serviceName and endpointInterface attributes of the @WebService annotation. Use the serviceName attribute to specify a different <service> WSDL element from the one that the wsdlc Ant task used, in the rare case that the WSDL file contains more than one <service> element. Use the endpointInterface attribute to specify the JWS interface generated by the wsdlc Ant task.
You can specify any WebLogic-specific JWS annotation that you want.

Finally, after you have coded the JWS file so that it works as you want, iteratively run the jwsc Ant task to generate a complete Java implementation of the Web Service. Use the compiledWsdl attribute of jwsc to specify the JAR file generated by the wsdlc Ant task which contains the JWS interface file and data binding artifacts. By specifying this attribute, the jwsc Ant task does not generate a new WSDL file but instead uses the one in the JAR file. Consequently, when you deploy the Web Service and view its WSDL, the deployed WSDL will look just like the one from which you initially started.

Note: The only potential difference between the original and deployed WSDL is the value of the location attribute of the <address> element of the port(s) of the Web Service. The deployed WSDL will specify the actual hostname and URI of the deployed Web Service, which is most likely different from that of the original WSDL. This difference is to be expected when deploying a real Web Service based on a static WSDL.

See Creating a Web Service from a WSDL File for a complete example of using the wsdlc Ant task in conjunction with jwsc.

Taskdef Classname

    <taskdef name="wsdlc"
           classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>

Example

The following excerpt from an Ant build.xml file shows how to use the wsdlc and jwsc Ant tasks together to build a WebLogic Web Service. The build file includes two different targets: generate-from-wsdl that runs the wsdlc Ant task against an existing WSDL file, and build-service that runs the jwsc Ant task to build a deployable Web Service from the artifacts generated by the wsdlc Ant task:

  <taskdef name="wsdlc"
           classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>

  <taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />

  <target name="generate-from-wsdl">

    <wsdlc
        srcWsdl="wsdl_files/TemperatureService.wsdl"
        destJwsDir="output/compiledWsdl"
        destImplDir="output/impl"
        packageName="examples.webservices.wsdlc" />

  </target>

  <target name="build-service">

    <jwsc
      srcdir="src"
      destdir="output/wsdlcEar">

      <jws file="examples/webservices/wsdlc/TemperaturePortTypeImpl.java"
           compiledWsdl="output/compiledWsdl/TemperatureService_wsdl.jar" />

    </jwsc>

  </target>

In the example, the wsdlc Ant task takes as input the TemperatureService.wsdl file and generates the JAR file that contains the JWS interface and data binding artifacts into the directory output/compiledWsdl. The name of the JAR file is TemperatureService_wsdl.jar. The Ant task also generates a JWS file that contains a stubbed-out implementation of the JWS interface into the output/impl/examples/webservices/wsdlc directory (a combination of the value of the destImplDir attribute and the directory hierarchy corresponding to the specified packageName). The name of the stubbed-out JWS implementation file is based on the name of the <portType> element in the WSDL file that corresponds to the first <service> element. For example, if the portType name is TemperaturePortType, then the generated JWS implementation file is called TemperaturePortTypeImpl.java.

After running wsdlc, you code the stubbed-out JWS implementation file, adding your business logic. Typically, you move this JWS file from the wsdlc-output directory to a more permanent directory that contains your application source code; in the example, the fully coded TemperaturePortTypeImpl.java JWS file has been moved to the directory src/examples/webservices/wsdlc/. You then run the jwsc Ant task, specifying this JWS file as usual. The only additional attribute you must specify is compiledWsdl to point to the JAR file generated by the wsdlc Ant task, as shown in the preceding example. This indicates that you do not want the jwsc Ant task to generate a new WSDL file, because you want to use the original one that has been compiled into the JAR file.

Attributes

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

Table A-8 Attributes of the wsdlc Ant Task

Attribute	Description	Data Type	Required?
srcWsdl	Name of the WSDL from which to generate the JAR file that contains the JWS interface and data binding artifacts. The name must include its pathname, either absolute or relative to the directory which contains the Ant `build.xml` file.	String	Yes.
srcBindingName	Name of the WSDL binding from which the JWS interface file should be generated. The `wsdlc` Ant task runs against the first `<service>` element it finds in the WSDL file. Therefore, you only need to specify the `srcBindingName` attribute if there is more than one `<binding>` element associated with this first `<service>` element. If the namespace of the binding is the same as the namespace of the service, then you just need to specify the name of the binding for the value of this attribute. For example: `srcBindingName="MyBinding"` However, if the namespace of the binding is different from the namespace of the service, then you must also specify the namespace URI, using the following format: `srcBindingName="{URI}BindingName"` For example, if the namespace URI of the `MyBinding` binding is `www.examples.org`, then you specify the attribute value as follows: `srcBindingName="{www.examples.org}MyB inding"`	String.	Only if the WSDL file contains more than one `<binding>` element
packageName	Package into which the generated JWS interface and implementation files should be generated. If you do not specify this attribute, the `wsdlc` Ant task generates a package name based on the `targetNamespace` of the WSDL.	String	No.
destJwsDir	Directory into which the JAR file that contains the JWS interface and data binding artifacts should be generated. The name of the generated JAR file is `WSDLFile_wsdl.jar`, where `WSDLFile` refers to the root name of the WSDL file. For example, if the name of the WSDL file you specify to the `file` attribute is `MyService.wsdl`, then the generated JAR file is `MyService_wsdl.jar`.	String	Yes.
desImplDir	Directory into which the stubbed-out JWS implementation file is generated. The generated JWS file implements the generated JWS interface file (contained within the JAR file). You update this JWS implementation file, adding Java code to the methods so that they behave as you want, then later specify this updated JWS file to the `jwsc` Ant task to generate a deployable Web Service.	String	No.
destJavadocDir	Directory into which Javadoc that describes the JWS interface is generated. Because you should never unjar or update the generated JAR file that contains the JWS interface file that implements the specified Web Service, you can get detailed information about the interface file from this generated Javadoc. You can then use this documentation, together with the generated stubbed-out JWS implementation file, to add business logic to the partially generated Web Service.	String	No.
autoDetectWrapped	Specifies whether the `wsdlc` Ant task should try to determine whether the parameters and return type of document-literal Web Services are of type wrapped or bare. When the `wsdlc` Ant task parses a WSDL file to create the partial JWS file that implements the Web Service, it attempts to determine whether a document-literal Web Service uses wrapped or bare parameters and return types based on the names of the XML Schema elements, the name of the operations and parameters, and so on. Depending on how the names of these components match up, the `wsdlc` Ant task makes a best guess as to whether the parameters are wrapped or bare. In some cases, however, you might want the Ant task to always assume that the parameters are of type bare; in this case, set the `autoDetectWrapped` attribute to `False`. Valid values for this attribute are `True` or `False`. The default value is `True`.	Boolean	No.
jaxRPCWrappedArrayStyle	When the `wsdlc` Ant task is generating the Java equivalent to XML Schema data types in the WSDL file, and the task encounters an XML complex type with a single enclosing sequence with a single element with the `maxOccurs` attribute equal to `unbounded`, the task generates, by default, a Java structure whose name is the lowest named enclosing complex type or element. To change this behavior so that the task generates a literal array instead, set the `jaxRPCWrappedArrayStyle` to `False`. Valid values for this attribute are `True` or `False`. The default value is `True`.	Boolean	No.
failonerror	Specifies whether the execution of the `wsdlc` Ant task should continue, even if errors are encountered. Valid values for this attribute are `true` and `false`. The default value is `true`.	Boolean.	No.