1. WebLogic Web Services Reference for Oracle WebLogic Server
  2. Ant Task Reference

2 Ant Task Reference

WebLogic web services includes a variety of Ant tasks that you can use to centralize many of the configuration and administrative tasks into a single Ant build script.

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. Oracle 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. See the Apache Ant Manual at 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.

The following table provides an overview of the web service Ant tasks provided by Oracle.

Table 2-1 WebLogic Web Service Ant Tasks

Ant Task Description

clientgen

Generates the Service stubs and other client-side artifacts used to invoke a web service.

jwsc

Compiles a Java web service (JWS)-annotated file into a web service.

wsdlc

Generates a partial web service implementation based on a WSDL file.

wsdlget

Downloads to the local directory a WSDL and its imported XML targets, such as XSD and WSDL files.

For detailed information about 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:

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.

The generated artifacts for JAX-WS web services include:

  • The Java class for the Service interface implementation for the particular web service you want to invoke.

  • JAXB data binding artifacts.

  • The Java class for any user-defined XML Schema data types included in the WSDL file.

The generated artifacts for JAX-RPC web services include:

  • The Java class for the 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 Java Platform, Enterprise Edition (Java EE) client container.

  • Java EE clients, such as EJBs, JSPs, and web services, that use the Java EE client container.

By default, the clientgen Ant task generates client artifacts for a JAX-RPC web service. If you are generating client artifacts for a JAX-WS web service, you can set the type attribute to JAXWS. For example: type="JAXWS".

You typically use the destDir attribute of clientgen to specify the directory into which all the artifacts should be generated, and then compile the generate Java files yourself using the javac Ant task. However, clientgen also provides a destFile attribute if you want the Ant task to compile the Java files for you and package them, along with the other generated artifacts, into the specified JAR file. You must specify one of either destFile or destDir, although you cannot specify both.

The following sections provide more information about the clientgen Ant task:

Taskdef Classname

The following shows the task definition for the clientgen classname which must appear in your Ant build file. 

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

Child Elements

The following sections describe the WebLogic-specific child elements for the clientgen Ant task.

binding

Use the <binding> child element to specify one of the following:

You use the <binding> element the same way as the standard Ant FileSet data type, using the same attributes. For example, the following <binding> element specifies the JAX-WS custom binding declarations defined in the file jaxws-binding.xml: 

<binding file="./jaxws-binding.xml"/>

The following example specifies the JAX-WS customization files that are located in the ${basedir} directory: 

<binding dir="${basedir}"/>

For information about the full set of attributes you can specify using the FileSet data type, obtain the documentation for the version of Ant you are using at http://ant.apache.org/index.html and navigate to the description of the FileSet type.

jmstransportclient

Note:

The <jmstransportclient> child element applies to JAX-WS only; this child element is not valid for JAX-RPC.

The <jmstransportclient> element enables and configures SOAP over JMS transport.

Optionally, you can configure the destination name, destination type, delivery mode, request and response queues, and other JMS transport properties, using the <jmstransportclient> element. For a complete list of JMS transport properties supported, see Configuring JMS Transport Properties in Developing JAX-WS Web Services for Oracle WebLogic Server.

The following example shows how to enable and configure JMS transport when generating the web service client using clientgen. 

<target name="clientgen">
<clientgen
      wsdl="./WarehouseService.wsdl"
      destDir="clientclasses"
      packageName="client.warehouse"
      type="JAXWS">
      <jmstransportclient
                targetService="JWSCEndpointService"
                destinationName="com.oracle.webservices.jms.SoapJmsRequestQueue"
                jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory"
                jndiConnectionFactoryName="weblogic.jms.ConnectionFactory"
                jndiURL="t3://localhost:7001"
                deliveryMode="NON_PERSISTENT"
                timeToLive="60000"
                priority="1"
                messageType="TEXT"
                replyToName="com.oracle.webservices.jms.SoapJmsResponseQueue"
     />
</clientgen>
xmlcatalog

Note:

The <xmlcatalog> child element applies to JAX-WS only; this child element is not valid for JAX-RPC.

The <xmlcatalog> child element specifies the ID of an embedded XML catalog. The following shows the element syntax: 

<xmlcatalog refid="id"/>

The ID referenced by <xmlcatalog> must match the ID of an embedded XML catalog. You embed an XML catalog in the build.xml file using the following syntax: 

<xmlcatalog id="id">
     <entity publicid="public_id" location="uri"/>
</xmlcatalog>

In the above syntax, public_id specifies the public identifier of the original XML resource (WSDL or XSD) and uri specifies the replacement XML resource.

The following example shows how to embed an XML catalog and reference it using clientgen. Relevant code lines are shown in bold. 

<target name="clientgen">
<clientgen 
     type="JAXWS"
     wsdl="${wsdl}"
     destDir="${clientclasses.dir}"
     packageName="xmlcatalog.jaxws.clientgen.client"
     catalog="wsdlcatalog.xml">
     <xmlcatalog refid="wsimportcatalog"/>
</clientgen>
</target>
<xmlcatalog id="wsimportcatalog">
     <entity publicid="http://helloservice.org/types/HelloTypes.xsd"
             location="${basedir}/HelloTypes.xsd"/>
</xmlcatalog>

See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

Attributes

The following table describe the WebLogic-specific attributes of the clientgen Ant task, and specifies whether they are valid for JAX-WS or JAX-RPC web services or both.

Table 2-2 WebLogic-specific Attributes of the clientgen Ant Task

Attribute Description Data Type Required? JAX-WS, JAX-RPC, or Both?

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

JAX-RPC

catalog

Specifies an external XML catalog file. See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

String

No

JAX-WS

copyWsdl

Controls whether the WSDL should be copied in the destination directory defined by destDir.

Boolean

No

JAX-WS

destDir

Directory into which the clientgen Ant task generates the client source code, compiled classes, 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 Java EE 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

You must specify either the destFile or destDir attribute, but not both.

Both

destFile

Name of a JAR file or exploded directory into which the clientgen task packages the client source code, compiled classes, WSDL, and client deployment descriptor files. If you specify this attribute, the clientgen Ant task also compiles all Java code into classes.

To create or update a JAR file, use a .jar suffix when specifying the JAR file, such as myclientjar.jar. If the attribute value does not have a .jar suffix, then the clientgen task assumes you are referring to a directory name.

If you specify a JAR file or directory that does not exist, the clientgen task creates a new JAR file or directory.

String

You must specify either the destFile or destDir attribute, but not both.

Both

failonerror

Specifies whether the clientgen Ant task continues executing in the event of an error.

Valid values for this attribute are True or False. The default value is True, which means clientgen continues executing even after it encounters an error.

Boolean

No

Both

generateAsyncMethods

Specifies whether the clientgen Ant task should include methods in the generated 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 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.

Note: If the web service operation is marked as one-way, the clientgen Ant task never generates the asynchronous flavor of the 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

JAX-RPC

generatePolicyMethods

Specifies whether the clientgen Ant task should include WS-Policy-loading methods in the generated stubs. These methods can be used by client applications to load a local WS-Policy file.

If you specify True, four flavors of a method called getXXXSoapPort() are added as extensions to the 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 WS-Policy files, rather than apply any WS-Policy files deployed with the web service itself. Client applications can specify whether the local WS-Policy file applies to inbound, outbound, or both SOAP messages and whether to load the local WS-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 in Securing WebLogic Web Services for Oracle WebLogic Server for more information.

Boolean

No

JAX-RPC

getRuntimeCatalog

Specifies whether the clientgen Ant task should generate the XML catalog artifacts in the client runtime environment. To disable their generation, set this flag to false. This value defaults to true. See Disabling XML Catalogs in the Client Runtime in Developing JAX-WS Web Services for Oracle WebLogic Server.

Boolean

No

JAX-WS

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

JAX-RPC

includeGlobalTypes

Specifies that the clientgen Ant task should generate Java representations of all XML Schema data types in the WSDL, rather than just the data types that are explicitly used in the web service operations.

Valid values for this attribute are True or False. The default value is False, which means that clientgen generates Java representations for only the actively-used XML data types.

Boolean

No

JAX-RPC

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

JAX-RPC

packageName

Package name into which the generated 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, then you should specify this attribute.

If you do specify this attribute, Oracle recommends you use all lower-case letters for the package name.

String

No

Both

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 mapping file and client-side copy of the WSDL file will use this name. For example, if you set serviceName to CuteService, the 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.

JAX-RPC

sortSchemaTypes

In an XSD file, two complex types are defined, one a named global type and the other an unnamed local type. By default, clientgen automatically generates its own name for the unnamed local type, and the name generated when compiling different WSDL files is not always consistent.

When enabled, the type names in the Java files generated by clientgen will be the same.

Boolean

No

JAX-RPC

type

Specifies the type of web service for which you are generating client artifacts: JAX-WS or JAX-RPC.

Valid values are:

  • JAXWS

  • JAXRPC

Default value is JAXRPC.

String

No

Both

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

Both

wsdlLocation

Specifies the value of the wsdlLocation attribute generated on the @WebServiceClient.

String

No

JAX-WS

Examples

The following examples illustrate how to build a clientgen Ant target.

Example 1   Building a Basic clientgen Ant Target

In the following example, 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. By default, clientgen generates client artifacts based on a JAX-RPC web service. 

<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>
Example 2   Generating a JAX-WS Web Service Client

In the preceding example, it is assumed that the web service for which you are generating client artifacts is based on JAX-RPC; the following example shows how to use the type attribute to specify that the web service is based on JAX-WS: 

<clientgen
 type="JAXWS"
 wsdl="http://${wls.hostname}:${wls.port}/JaxWsImpl/JaxWsImplService?WSDL"
 destDir="/output/clientclasses"
 packageName="examples.webservices.jaxws.client"
/>
Example 3   Compiling and Packaging the Generated Artifacts

If you want the clientgen Ant task to compile and package the generated artifacts for you, specify the destFile attribute rather than destDir. In this example, you do not need to also specify the javac Ant task after clientgen in the build.xml file because the Java code has already been compiled. 

<clientgen
    type="JAXWS"
    wsdl="http://example.com/myapp/myservice.wsdl"
    destFile="/output/jarfiles/myclient.jar"
    packageName="myapp.myservice.client"
    serviceName="StockQuoteService" 
/>
Example 4   Executing clientgen on a Static WSDL File

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.

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

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

You can use the standard Ant <sysproperty> nested element to set Java properties, such as the username and password of a valid WebLogic Server user (if you have enabled access control on the web service) or the name of a client-side trust store that contains trusted certificates, as shown in the following example: 

<clientgen
    type="JAXWS"
    wsdl="http://example.com/myapp/mySecuredService.wsdl"
    destDir="/output/clientclasses"
    packageName="myapp.mysecuredservice.client"
    serviceName="SecureStockQuoteService"
    <sysproperty key="javax.net.ssl.trustStore" 
                 value="/keystores/DemoTrust.jks"/>
    <sysproperty key="weblogic.wsee.client.ssl.stricthostchecking" 
                 value="false"/>
    <sysproperty key="javax.xml.rpc.security.auth.username"
                 value="juliet"/>
    <sysproperty key="javax.xml.rpc.security.auth.password"
                 value="secret"/> 
</clientgen>

jwsc

The jwsc Ant task takes as input one or more Java Web Service (JWS) files that contains both standard and WebLogic-specific JWS annotations and generates all the artifacts you need to create a WebLogic web service.

The generated artifacts for JAX-WS web services include:

  • JSR-109 web service class file at http://www.jcp.org/en/jsr/detail?id=109, such as the service endpoint interface (called JWS_ClassNamePortType.java, where JWS_ClassName refers to the JWS class).

  • JAXB data binding artifact class file.

  • All required deployment descriptors, including:

    • Servlet-based web service deployment descriptor file: web.xml.

    • Ear deployment descriptor files: application.xml and weblogic-application.xml.

      Note:

      For JAX-WS web services:

      • The WSDL file is generated when the service endpoint is deployed.

      • No EJB deployment descriptors are required for EJB 3.0-based web services.

The generated artifacts for JAX-RPC web services include:

  • JSR-109 web service class file at http://www.jcp.org/en/jsr/detail?id=175, such as the service endpoint interface (called JWS_ClassNamePortType.java, where JWS_ClassName refers to the JWS class).

  • All required deployment descriptors, which can include:

    • Standard and WebLogic-specific web services deployment descriptors: webservices.xml, weblogic-webservices.xml, and weblogic-webservices-policy.xml.

    • JAX-RPC mapping files.

    • Java class-implemented web services: web.xml and weblogic.xml.

    • EJB-implemented web services: ejb-jar.xml and weblogic-ejb-jar.xml.

    • Ear deployment descriptor files: application.xml and weblogic-application.xml.

  • The XML Schema representation of any Java user-defined types used as parameters or return values to the web service 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 Web application WAR file, and finally creates an exploded Enterprise Application directory that contains the JAR file. You then deploy this Enterprise Application to WebLogic Server.

By default, the jwsc Ant task generates a web service that conforms to the JAX-RPC specification. You can control the type of web services that is generated using the type attribute of the <jws> child element. For example, to generate a JAX-WS web service, set type="JAXWS" attribute of the <jws> child element.

Note:

Although not typical, you can code your JWS file to explicitly implement javax.ejb.SessionBean. See Should You Implement a Stateless Session EJB? in Developing JAX-WS Web Services for Oracle WebLogic Server for details. Because this case is not typical, it is assumed in this section that jwsc packages your web service in a Web application WAR file, and EJB-specific information is generated only when necessary.

You specify the JWS file or files you want the jwsc Ant task to compile using the <jws> element, as described in jws. If the <jws> element is an immediate child of the jwsc Ant task, then jwsc generates a separate WAR file for each JWS file. If you want all the JWS files, along with their supporting artifacts, to be packaged in a single WAR file, then group all the <jws> elements under a single <module> element. A single WAR file reduces WebLogic server resources and allows the web services to share common objects, such as user-defined data types. Using this method you can also specify the same context path for the web services; if they are each packaged in their own WAR file then each service must also have a unique context path.

When you use the <module> element, you can use the <jwsfileset> child element to search for a list of JWS files in one or more directories, rather than list each one individually using <jws>.

Typically, jwsc generates a new Enterprise Application exploded directory at the location specified by the destDir attribute. However, if you specify an existing Enterprise Application as the destination directory, jwsc updates any existing application.xml file with the new web services information.

Similarly, jwsc typically generates new Web application deployment descriptors (web.xml and weblogic.xml) that describe the generated Web application. If, however, you have an existing Web application to which you want to add web services, you can use the <descriptor> child element of the <module> element to specify existing web.xml and weblogic.xml files; in this case, jwsc copies these files to the destDir directory and adds new information to them. Use the standard Ant <fileset> element to copy the other existing Web application files to the destDir directory.

Note:

The existing web.xml and weblogic.xml files pointed to by the <descriptor> element must be XML Schema-based, not DTD-based which will cause the jwsc Ant task to fail with a validation error.

If one or more of the JWS files to be compiled itself includes an invoke of a different web service, then you can use the <clientgen> element of jwsc to generate and compile the required client component files, such as the Stub and Service interface implementations for the particular web service you want to invoke. These files are packaged in the generated WAR file so as to make them available to the invoking web service.

The following sections discuss additional important information about jwsc:

Taskdef Classname

The following shows the task definition for the jwsc classname which must appear in your Ant build file. 

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

Child Elements

The following shows the child element hierarchy of the jwsc Ant task. 

<jwsc> {1}
   <jws> {0 or more}
      <WLHttpTransport> {0 or 1}
      <WLHttpsTransport> {0 or 1}
      <jmstransportservice> {0 or 1} -- JAX-WS web services only
      <WLJMSTransport> {0 or 1} -- JAX-RPC web services only
      <clientgen> {0 or more}
      <descriptor> {0 or more}
   <module> {0 or more}
      <jws> {0 or more}
         <WLHttpTransport> {0 or 1}
         <WLHttpsTransport> {0 or 1}
         <jmstransportservice> {0 or 1} -- JAX-WS web services only
         <WLJMSTransport> {0 or 1} -- JAX-RPC web services only
      <clientgen> {0 or more}
      <descriptor> {0 or more}
      <jwsfileset> {0 or more}
   <binding> {0 or more}

The jwsc Ant task has a variety of attributes and three child elements:

  • <jws> element—Used as either a child element of <jwsc> or <module>. Defines the transport (HTTP, HTTPs, or JMS) using on of the following child elements:

    For more information, see jws.

  • <module> element—Groups one or more JWS files (also specified with the <jws> element) into a single module (WAR file); if you do not specify <module>, then each JWS file is packaged into its own module, or WAR file. For more information, see module.

  • <binding> element—Specifies custom binding information. For more information, see binding.

The <clientgen> and <descriptor> elements are children only of the elements that generate modules: either the actual <module> element itself, or <jws> when used as a child of jwsc, rather than a child of <module>.

The <jwsfileset> element can be used only as a child of <module>.

The following sections describe each child element in the jwsc Ant task in more detail.

binding

Use the <binding> child element to specify one of the following:

The <binding> element is similar to the standard Ant <Fileset> element and has all the same attributes. See the Apache Ant documentation on the Fileset element at http://ant.apache.org/manual/Types/fileset.html for the full list of attributes you can specify.

Note:

The <binding> child element is not valid if you specify the compliedWsdl attribute of the <jws> element.

clientgen

Use the <clientgen> element if the JWS file itself invokes another web service and you want the jwsc Ant task to automatically generate and compile the required client-side artifacts and package them in the Web application WAR file together with the web service. The client-side artifacts include:

  • The Java classes or the Stub and Service interface implementations for the particular web service you want to invoke.

  • The Java classes for any user-defined XML Schema data types included in the WSDL file.

  • For JAX-RPC, the 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.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

You can specify the standard Ant <sysproperty> child element to specify properties required by the web service from which you are generating client-side artifacts. For example, if the web service is secured, you can use the javax.xml.rpc.security.auth.username|password properties to set the authenticated username and password. See the Ant documentation at http://ant.apache.org/manual/ for the java Ant task for additional information about <sysproperty>.

You can use the <clientgen> child element for generating both JAX-WS and JAX-RPC web services.

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

Table 2-3 Attributes of the <clientgen> Element

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

autoDetectWrapped

Specifies whether the jwsc 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 jwsc Ant task parses a WSDL file to create the 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 jwsc 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.

No

JAX-RPC

catalog

Specifies an external XML catalog file.

See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

No

JAX-WS

handlerChainFile

Specifies the name of the XML file that describes the client-side SOAP message handlers that execute when the JWS file invokes a web service.

Each handler specified in the file executes twice:

  • directly before the JWS sends the SOAP request to the invoked web service.

  • directly after the JWS receives the SOAP response from the invoked web service.

If you do not specify this attribute, then no client-side handlers execute when the web service is invoked from the JWS file, even if they are in your CLASSPATH.

See Creating and Using Client-Side SOAP Message Handlers in Developing JAX-RPC Web Services for Oracle WebLogic Server for details and examples about creating client-side SOAP message handlers.

No

JAX-RPC

generateAsyncMethods

Specifies whether the jwsc Ant task should include methods in the generated stubs that the JWS file 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 jwsc Ant task also generates a method called getQuoteAsync in the stubs which the JWS file can use 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 the JWS file can use to set asynchronous properties, contextual variables, and so on.

Note: If the operation of the web service being invoked in the JWS file is marked as one-way, the jwsc Ant task never generates the asynchronous flavor of the 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.

No

JAX-RPC

generatePolicyMethods

Specifies whether the jwsc Ant task should include WS-Policy-loading methods in the generated stubs. You can use these methods in your JWS file, when invoking the web service, to load a local WS-Policy file.

If you specify True, four flavors of a method called getXXXSoapPort() are added as extensions to the Service interface in the generated client stubs, where XXX refers to the name of the web service. You can program the JWS file to use these methods to load and apply local WS-Policy files, rather than apply any WS-Policy file deployed with the web service itself. You can specify in the JWS file whether the local WS-Policy file applies to inbound, outbound, or both SOAP messages and whether to load the local WS-Policy file 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 in Securing WebLogic Web Services for Oracle WebLogic Server for more information.

No

JAX-RPC

includeGlobalTypes

Specifies that the jwsc Ant task should generate Java representations of all XML Schema data types in the WSDL, rather than just the data types that are explicitly used in the web service operations.

Valid values for this attribute are True or False. The default value is False, which means that jwsc generates Java representations for only the actively-used XML data types.

No

JAX-RPC

jaxRPCWrappedArrayStyle

When the jwsc 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

No

JAX-RPC

packageName

Package name into which the generated client interfaces and stub files are packaged.

Oracle recommends you use all lower-case letters for the package name.

Yes

Both

serviceName

Name of the web service in the WSDL file for which the corresponding client-side artifacts 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.

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.

JAX-RPC

wsdl

Full path name or URL of the WSDL that describes a web service (either WebLogic or non-WebLogic) for which the client artifacts should be generated.

The generated stub factory classes use the value of this attribute in the default constructor.

Yes

Both
descriptor

Use the <descriptor> element to specify that, rather than create new Web application deployment descriptors when generating the WAR that will contain the implementation of the web service, the jwsc task should instead copy existing files and update them with the new information. This is useful when you have an existing Web application to which you want to add one or more web services. You typically use this element together with the standard <FileSet> Ant task to copy other existing Web application artifacts, such as HTML files and Java classes, to the jwsc-generated Web application.

You can use this element with only the following two deployment descriptor files:

  • web.xml

  • weblogic.xml

Use a separate <descriptor> element for each deployment descriptor file.

The <descriptor> element is a child of either <module> or <jws>, when the latter is a direct child of the main jwsc Ant task.

Note:

The existing web.xml and weblogic.xml files pointed to by the <descriptor> element must be XML Schema-based, not DTD-based which will cause the jwsc Ant task to fail with a validation error.

You can use the <descriptor> child element only for generating JAX-RPC web services. To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

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

Table 2-4 Attributes of the <descriptor> Element

Attribute Description Required?

file

Full pathname (either absolute or relative to the directory that contains the build.xml file) of the existing deployment descriptor file. The deployment descriptor must be XML Schema-based, not DTD-based.

The jwsc Ant task does not update this file directly, but rather, copies it to the newly-generated Web application.

Yes
jmstransportservice

Note:

You can use the <jmstransportservice> child element for configuring SOAP over JMS transport for JAX-WS web services only. For information about configuring SOAP over JMS transport for JAX-RPC web services, see WLJMSTransport.

You cannot use SOAP over JMS transport in conjunction with Web Services reliable messaging or streaming SOAP attachments, as described in Developing JAX-WS Web Services for Oracle WebLogic Server.

Use the <jmstransportservice> element to enable and configure SOAP over JMS transport for JAX-WS web services and clients.

Using SOAP over JMS transport, web services and clients communicate using JMS destinations instead of HTTP connections, offering the following benefits:

  • Reliability

  • Scalability

  • Quality of service

For more information about using SOAP over JMS transport, see Using SOAP Over JMS Transport as the Connection Protocol in Developing JAX-WS Web Services for Oracle WebLogic Server.

The <jmstransportservice> element is a child in the <jws> element of the jwsc Ant task. You can specify zero or one <jmstransportservice> element for a given JWS file.

Optionally, you can configure the destination name, destination type, delivery mode, request and response queues, and other JMS transport properties, using the <jmstransportservice> element. For a complete list of JMS transport properties supported, see Configuring JMS Transport Properties in Developing JAX-WS Web Services for Oracle WebLogic Server.

The following example shows how to enable and configure JMS transport when generating the web service using jwsc. 

<?xml version="1.0"?>
<project name="jaxws.jms.jwsc" default="all">
   <import file="../build-jms.xml"/>
      <path id="client.class.path">
         <pathelement path="${clientclasses.dir}"/>
         <pathelement path="${java.class.path}"/>
      </path>
   <target name="jwsc">
      <jwsc srcdir="." sourcepath="client" destdir="${output.dir}" debug="on" 
            keepGenerated="yes">
         <jws file="JWSCEndpoint.java" type="JAXWS" explode="true">
            <jmstransportservice
               targetService="JWSCEndpointService"
               destinationName="com.oracle.webservices.api.jms.RequestQueue"
               jndiInitialContextFactory="weblogic.jndi.WLInitialContextFactory"
               jndiConnectionFactoryName="weblogic.jms.XAConnectionFactory"
               jndiURL="t3://localhost:7001"
               deliveryMode="PERSISTENT"
               timeToLive="60000"
               priority="1"
               messageType="TEXT"
               activationConfig = "transAttribute=Supports"
            />
      </jws>
   </jwsc>
</target>
</project>
jws

The <jws> element 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 WAR file inside of an Enterprise Application.

You can specify the <jws> element in the following two different levels of the jwsc element hierarchy:

  • An immediate child element of the jwsc Ant task. In this case, jwsc generates a separate WAR file for each JWS file. You typically use this method if you are specifying just one JWS file to the jwsc Ant task.

  • A child element of the <module> element, which in turn is a child of jwsc. In this case, jwsc generates a single WAR file that includes all the generated code and artifacts for all the JWS files grouped within the <module> element. This method is useful if you want all JWS files to share supporting files, such as common Java data types.

You are required to specify either a <jws> or <module> child element of jwsc.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

You can use the standard Ant <FileSet> child element with the <jws> element of jwsc.

You can use the <jws> child element when generating both JAX-WS and JAX-RPC web services.

The following table describes the attributes of the <jws> element. The description specifies whether the attribute applies in the case that <jws> is a child of jwsc, is a child of <module> or in both cases.

Table 2-5 Attributes of the <jws> Element of the jwsc Ant Task

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

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.

Applies to <jws> when used as a child of both jwsc and <module>.

Only required for the "starting from WSDL" use case

Both

contextPath

Context path (or 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 context path for this web service is financial.

The value of this attribute overrides any other context path set for the JWS file. This includes the transport-related JWS annotations, as well as the transport-related child elements of <jws>.

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.

Applies only when <jws> is a direct child of jwsc.

For more information about defining the context path, see:

No

Both

explode

Specifies whether the generated WAR file that 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 jwsc generates an actual WAR archive file, and not an exploded directory.

Applies only when <jws> is a direct child of jwsc.

No

Both

file

The name of the JWS file that you want to compile. The jwsc Ant task looks for the file in the srcdir directory.

Applies to <jws> when used as a child of both jwsc and <module>.

Yes

Both

generateWsdl

Specifies whether the generated WAR file includes the WSDL file in the WEB-INF directory. Valid values for this attribute are true or false. Default value is false, which means that jwsc does not include the WSDL file in the generated WAR file.

Applies to <jws> when used as a child of both jwsc and <module>.

Yes

JAX-WS

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)

Applies to <jws> when used as a child of both jwsc and <module>.

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

JAX-RPC

name

The name of the generated WAR 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 have a .war extension.

The default value of this attribute is the name of the JWS file, specified by the file attribute.

Applies only when <jws> is a direct child of jwsc.

No

Both

type

Specifies the type of web service to generate: JAX-WS or JAX-RPC.

Valid values are:

  • JAXWS

  • JAXRPC

Default value is JAXRPC.

No

Both

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.

If you set this attribute to true but also set the explode attribute to false (which is also the default value), then jwsc ignores the explode attribute and always generates the output in exploded format.

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.

Applies only when <jws> is a child of jwsc.

No

Both
jwsfileset

Use the <jwsfileset> child element of <module> to specify one or more directories in which the jwsc Ant task searches for JWS files to compile. The list of JWS files that jwsc finds is then treated as if each file had been individually specified with the <jws> child element of <module>.

Use the standard nested elements of the <FileSet> Ant task to narrow the search. For example, use the <include> element to specify the pattern matching that <jwsfileset> should follow when determining the JWS files it should include in the list. See the Ant documentation at http://ant.apache.org/manual/ for details about <FileSet> and its nested elements.

You can use the <jwsfileset> child element for generating both JAX-WS and JAX-RPC web services.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

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

Table 2-6 Attributes of the <jwsfileset> Element

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

scrdir

Specifies the directories (separated by semi-colons) that the jwsc Ant task should search for JWS files to compile.

Yes

Both

type

Specifies the type of web service to generate for each found JWS file: JAX-WS or JAX-RPC.

Valid values are:

  • JAXWS

  • JAXRPC

Default value is JAXRPC.

No

Both
module

The <module> element groups one or more <jws> elements together so that their generated code and artifacts are packaged in a single Web application (WAR) file. The <module> element is a child of the main jwsc Ant task.

You can group only web services implemented with the same backend component (Java class or stateless session EJB) under a single <module> element; you cannot mix and match. By default, jwsc always implements your web service as a plain Java class; the only exception is if you have implemented a stateless session EJB in your JWS file. This means, for example, that if one of the JWS files specified by the <jws> child element of <module> implements javax.ejb.SessionBean, then all its sibling <jws> files must also implement javax.ejb.SessionBean. If this is not possible, then you cannot group all the JWS files under a single <module>.

The web services within a module must have the same contextPath, but must have unique serviceURIs. You can set the common contextPath by specifying it as an attribute to the <module> element, or ensuring that the @WLXXXTransport annotations (for JAX-RPC only) and/or <WLXXXTransport> elements for each web service have the same value for the contextPath attribute. The jwsc Ant task validates these values and returns an error if they are not unique. For more information about defining the context path, see:

You must specify at least one <jws> child element of <module>.

You can use the <module> child element when generating both JAX-WS and JAX-RPC web services.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

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

Table 2-7 Attributes of the <module> Element of the jwsc Ant Task

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

contextPath

Context path (or context root) of all the web services contained in this module.

For example, assume the deployed WSDL of a WebLogic web service is as follows:

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

The context path for this web service is financial.

The value of this attribute overrides any other context path set for any of the JWS files contained in this module. This includes the transport-related JWS annotations, as well as the transport-related child elements of <jws>.

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.

For more information about defining the context path, see:

Only required to ensure that the context paths of multiple web services in a single WAR are the same.

Both

ejbWsInWar

Specifies whether to package EJB-based web services in a WAR file instead of a JAR file. Valid values for this attribute are true or false. Default value is false, which means that EJB-based web services are packaged in a JAR file.

No

JAX-WS

explode

Specifies whether the generated WAR file that contains the deployable web service(s) is in exploded directory format or not. Valid values for this attribute are true or false. Default value is false, which means that jwsc generates an actual WAR archive file, and not an exploded directory.

No

Both

generateWsdl

Specifies whether the generated WAR file includes the WSDL file. Valid values for this attribute are true or false. Default value is false, which means that jwsc generates an actual WAR archive file, and not an exploded directory.

No

JAX-WS

name

The name of the generated WAR file (or exploded directory, if the explode attribute is set to true) that contains the deployable web service(s). If an actual WAR archive file is generated, the name of the file will have a .war extension.

The default value of this attribute is jws.

No

Both

wsldOnly

Specifies that only a WSDL file should be generated for each JWS file specified by the <jws> child element of <module>.

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.

If you set this attribute to true but also set the explode attribute to false (which is also the default value), then jwsc ignores the explode attribute and always generates the output in exploded format.

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

Both
WLHttpTransport

Use the WLHttpTransport child element of the <jws> 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.

You can specify one or zero <WLHttpTransport> elements for a given JWS file.

You can use the <WlHttpTransport> child element when generating both JAX-WS and JAX-RPC web services.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

The following table describes the attributes of <WLHttpTransport>.

Table 2-8 Attributes of the <WLHttpTransport> Child Element of the <jws> Element

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

contextPath

Context path (or 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.

For more information about defining the context path, see:

No

Both

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.

For JAX-WS, the default value of this attribute is the serviceName element of the @WebService annotation if specified. Otherwise, the name of the JWS file, without its extension, followed by Service. For example, if the serviceName element of the @WebService annotation is not specified and the name of the JWS file is HelloWorldImpl.java, then the default value of its serviceUri is HelloWorldImplService.

For JAX-RPC, 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

Both

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

Both
WLHttpsTransport

Note:

The <WLHttpsTransport> element is deprecated as of version 9.2 of WebLogic Server. You should use the <WLHttpTransport> element instead because it now supports both the HTTP and HTTPS protocols. If you want client applications to access the web service using only the HTTPS protocol, then you must specify the @weblogic.jws.security.UserDataConstraint JWS annotation in your JWS file.

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.

The <WLHttpsTransport> element is a child of the <jws> element. You can specify one or zero <WLHttpsTransport> elements for a given JWS file. You can use the <WlHttpsTransport> child element only for generating JAX-RPC web services.

See Attributes top view where this element fits in the jwsc element hierarchy.

The following table describes the attributes of <WLHttpsTransport>.

Table 2-9 Attributes of the <WLHttpsTransport> Child Element of the <jws> Element

Attribute Description Required?

contextPath

Context path (or 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.

For more information about defining the context path, see:

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.

For JAX-WS, the default value of this attribute is the serviceName element of the @WebService annotation if specified. Otherwise, the name of the JWS file, without its extension, followed by Service. For example, if the serviceName element of the @WebService annotation is not specified and the name of the JWS file is HelloWorldImpl.java, then the default value of its serviceUri is HelloWorldImplService.

For JAX-RPC, 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
WLJMSTransport

Note:

You can use the <WLJmsTransport> child element for configuring SOAP over JMS transport for JAX-RPC web services only. For information about configuring JMS transport for JAX-WS web services, see jmstransportservice.

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.

The <WLJmsTransport> element is a child of the <jws> element. You can specify one or zero <WLJmsTransport> elements for a given JWS file.

To view this element within the jwsc element hierarchy, see Attributes. See Examples for examples of using the element.

The following table describes the attributes of <WLJmsTransport>.

Table 2-10 Attributes of the <WLJMSTransport> Child Element of the <jws> Element

Attribute Description Required?

contextPath

Context path (or 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.

For more information about defining the context path, see:

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.

For JAX-WS, the default value of this attribute is the serviceName element of the @WebService annotation if specified. Otherwise, the name of the JWS file, without its extension, followed by Service. For example, if the serviceName element of the @WebService annotation is not specified and the name of the JWS file is HelloWorldImpl.java, then the default value of its serviceUri is HelloWorldImplService.

For JAX-RPC, 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 in Developing JAX-RPC Web Services for Oracle WebLogic Server 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

connectionFactory

The JNDI name of the JMS connection factory that you have configured for the JMS transport.

The default value of this attribute is the default JMS connection factory for your WebLogic Server instance.

No

Attributes

The following sections describe the attributes of the jwsc Ant task.

WebLogic-Specific jwsc Attributes

The following table summarizes the WebLogic-specific jwsc attributes.

Table 2-11 Attributes of the jwsc Ant Task

Attribute Description Required? JAX-RPC, JAX-WS, or Both?

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. However, jwsc does not automatically copy the updated application.xml file to the destDir; you must manually copy this file to the destDIR.

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

Both

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

Both

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

Both

dotNetStyle

Specifies that the jwsc Ant task should generate a .NET-style web service.

In particular, this means that, in the WSDL of the web service, the value of the name attribute of the <part> element that corresponds to the return parameter is parameters rather than returnParameters. This applies only to document-literal-wrapped web services.

The valid values for this attribute are true and false. The default value is true, which means .NET-style web service are generated by default.

No

JAX-RPC

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.

Note: This attribute is deprecated as of Version 9.2 of WebLogic Server.

No

Deprecated attribute so not applicable.

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

Both

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

Both

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

Both

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

Both
Standard Ant Attributes and Child Elements That Apply to jwsc

In addition to the WebLogic-defined jwsc attributes, you can also define the following standard javac attributes; see the Ant documentation at http://ant.apache.org/manual/ for additional information about each attribute:

  • bootclasspath

  • bootClasspathRef

  • classpath

  • classpathRef

  • compiler

  • debug

  • debugLevel

  • depend

  • deprecation

  • destdir

  • encoding

  • extdirs

  • failonerror

  • fork

  • includeantruntime

  • includejavaruntime

  • listfiles

  • memoryInitialSize

  • memoryMaximumSize

  • nowarn

  • optimize

  • proceed

  • source

  • sourcepath

  • sourcepathRef

  • tempdir

  • verbose

You can also use the following standard Ant child elements with the jwsc Ant task:

  • <SourcePath>

  • <Classpath>

  • <Extdirs>

You can use the following standard Ant elements with the <jws> and <module> child elements of the jwsc Ant task:

  • <FileSet>

  • <ZipFileSet>

Examples

The following examples illustrate how to build a jwsc Ant target. See Developing JAX-WS Web Services for Oracle WebLogic Server or Developing JAX-RPC Web Services for Oracle WebLogic Server 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.

Example 1   Building a Basic jwsc Ant Target

The following sample shows a very simple usage of jwsc. In this example, the JWS file called TestServiceImpl.java is located in the src/examples/webservices/jwsc 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. 

  <target name="build-service">
    <jwsc
      srcdir="src"
      destdir="output/TestEar">
      <jws file="examples/webservices/jwsc/TestServiceImpl.java" />
    </jwsc>
  </target>
Example 2   Generating a JAX-WS Web Service

By default, the jwsc Ant task generates a web service that conforms to the JAX-RPC specification. You can control the type of web services that is generated using the type attribute of the <jws> child element as shown in the following example. In this example, a JAX-WS web service is generated. 

  <target name="build-service8">
    <jwsc
      srcdir="src"
      destdir="${ear-dir}">
      <jws file="examples/webservices/jaxws/JaxWsImpl.java"
           type="JAXWS"
      />
    </jwsc>
  </target>
Example 3   Specifying Multiple JWS Files

This example shows how to specify multiple JWS files, resulting in separate web services packaged in their own Web application WAR files, although all are still deployed as part of the same Enterprise Application.

This example also shows how to enable debugging and verbose output; how to specify that jwsc not regenerate any existing temporary files in the output directory; and 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. 

  <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/jwsc/TestServiceImpl.java"  
         type="JAXWS"/>
      <jws file="examples/webservices/jwsc/AnotherTestServiceImpl.java"
         type="JAXWS"/>
      <jws file="examples/webservices/jwsc/SecondTestServiceImpl.java"      
         type="JAXWS"/>
    </jwsc>
  </target>

Example 4   Packaging Multiple Web Services Into a Single WAR File

If you want to package multiple web services into a single WAR file, group the <jws> elements under a <module> element, as shown in the following example. In this case, the three web services are packaged in a WAR file called myJAR.war, located at the top level of the Enterprise Application exploded directory. The contextPath attribute of <module> specifies that the context path of all three web services is test; this value overrides any context path specified in a transport annotation of the JWS files. 

 <target name="build-service3">
   <jwsc
     srcdir="src"
     destdir="output/TestEar" >
     <module contextPath="test" name="myJar" >
      <jws file="examples/webservices/jwsc/TestServiceImpl.java" 
           type="JAXWS"/>
      <jws file="examples/webservices/jwsc/AnotherTestServiceImpl.java" 
           type="JAXWS"/>
      <jws file="examples/webservices/jwsc/SecondTestServiceImpl.java" 
           type="JAXWS"/>
     </module>
   </jwsc>
 </target>
Example 5   Configuring Multiple Transports

The following example shows how to specify that the JAX-RPC web service can be invoked using all transports (HTTP/HTTPS/JMS).

This example also shows how to use the <clientgen> element to generate and include the client-side artifacts (such as the Stub and Service implementations) of the web service described by http://examples.org/complex/ComplexService?WSDL. This indicates that the TestServiceImpl.java JWS file, in addition to implementing a web service, must also acts as a client to the ComplexService web service and must include Java code to invoke operations of ComplexService. 

 <target name="build-service4">
   <jwsc
     srcdir="src"
     destdir="output/TestEar">
     <jws file="examples/webservices/jwsc/TestServiceImpl.java">
       <WLHttpTransport
          contextPath="TestService" serviceUri="TestService"
          portName="TestServicePortHTTP"/>
       <WLJmsTransport
          contextPath="TestService" serviceUri="JMSTestService"
          portName="TestServicePortJMS"
          queue="JMSTransportQueue"/>
       <clientgen
          wsdl="http://examples.org/complex/ComplexService?WSDL"
          serviceName="ComplexService"
          packageName="examples.webservices.simple_client"/>
     </jws>
   </jwsc>
 </target>
Example 6   Grouping Multiple <jws> Elements into a <module> Element

The following example is very similar to the preceding one, except that it groups the <jws> elements under a <module> element.

In this example, the individual transport elements no longer define their own contextPath attributes; rather, the parent <module> element defines it instead. This improves maintenance and understanding of what jwsc actually does. Also note that the <clientgen> element is a child of <module>, and not <jws> as in the previous example. 

<target name="build-service5">
  <jwsc
    srcdir="src"
    destdir="output/TestEar">
    <module contextPath="TestService" >
      <jws file="examples/webservices/jwsc/TestServiceImpl.java">
        <WLHttpTransport
           serviceUri="TestService"
           portName="TestServicePort1"/>
      </jws>
      <jws file="examples/webservices/jwsc/AnotherTestServiceImpl.java" />
      <jws file="examples/webservices/jwsc/SecondTestServiceImpl.java" />
      <clientgen
         wsdl="http://examples.org/complex/ComplexService?WSDL"
         serviceName="ComplexService"
         packageName="examples.webservices.simple_client" />
    </module>
  </jwsc>
</target>
Example 7   Specifying a File Set

The following example show how to use the <jwsfileset> element.

In this example, jwsc searches for *.java files in the directory src/examples/webservices/jwsc, relative to the directory that contains build.xml, determines which Java files contain JWS annotations, and then processes each file as if it had been specified with a <jws> child element of <module>. The <include> element is a standard Ant element at http://ant.apache.org/manual/, described in the documentation for the standard <FilesSet> task. 

  <target name="build-service6">
    <jwsc
      srcdir="src"
      destdir="output/TestEar" >
      <module contextPath="test" name="myJar" >
         <jwsfileset srcdir="src/examples/webservices/jwsc" >
           <include name="**/*.java" />
         </jwsfileset>
      </module>
    </jwsc>
  </target>
Example 8   Updating Existing Web Application Deployment Descriptors

The following example shows how to specify that the jwsc Ant task not create new Web application deployment descriptors, but rather, add to existing ones.

In this preceding example, the explode="true" attribute of <module> specifies that the generated Web application should be in exploded directory format, rather than the default WAR archive file. The <descriptor> child elements specify jwsc should copy the existing web.xml and weblogic.xml files, located in the webapp/WEB-INF subdirectory of the directory that contains the build.xml file, to the new Web application exploded directory, and that new web service information from the specified JWS file should be added to the files, rather than jwsc creating new ones. The example also shows how to use the standard Ant at http://ant.apache.org/manual/ <FileSet> task to copy additional files to the generated WAR file; if any of the copied files are Java files, the jwsc Ant task compiles the files and puts the compiled classes into the classes directory of the Web application. 

<target name="build-service7">
  <jwsc
    srcdir="src"
    destdir="output/TestEar" >
    <module contextPath="test" name="myJar" explode="true" >
      <jws file="examples/webservices/jwsc/AnotherTestServiceImpl.java" />
      <FileSet dir="webapp" >
        <include name="**/*.java" />
      </FileSet>
      <descriptor file="webapp/WEB-INF/web.xml" />
      <descriptor file="webapp/WEB-INF/weblogic.xml" />
    </module>
  </jwsc>
</target>

You can specify the type attribute for the <jws> or <jwsfileset> elements.

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. By specifying the type attribute, you can generate a partial implementation based on either JAX-WS or JAX-RPC.

By default, it is assumed that the WSDL file includes a single <service> element from which the wsdlc Ant task generates artifacts. You can, however, use the srcServiceName attribute to specify a specific web service, in the case that there is more than one <service> element in the WSDL file, or use the srcPortName attribute to specify a specific port of a web service in the case that there is more than one <port> child element for a given web service.

The wsdlc Ant task generates the following artifacts:

  • A JWS interface file—or service endpoint interface—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. You should not modify this file.

  • 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. You should not modify this file.

  • A JWS file that contains a partial (stubbed-out) implementation of the generated JWS interface. You need to modify this file to include your business code.

  • 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, for example, to add Java code to the methods so that they function as defined by your business requirements. The generated JWS implementation file does not initially contain any business logic because the wsdlc Ant task 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 and @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.

  • You cannot attach policies to the web service within the JWS implementation file using the weblogic.jws.Policy or weblogic.jws.Policies annotations.

    You can attach policies to the deployed web service using the WebLogic Server Administration Console if there is not a policy already defined in the WSDL.

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

  • For JAX-RPC web services, you can specify WebLogic-specific JWS annotations, as required. You cannot use any WebLogic-specific JWS annotations in a JAX-WS web service.

  • For JAX-WS, you can specify JAX-WS (JSR 224 at http://jax-ws.java.net), JAXB (JSR 222 at http://jcp.org/en/jsr/detail?id=222), or Common (JSR 250 at http://jcp.org/en/jsr/detail?id=250) annotations, as required.

After you have coded the JWS file with your business logic, 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.

Depending on the type of partial implementation you generate (JAX-WS or JAX-RPC), the Java package name of the generated complex data types differs, as described in the following guidelines:

  • For JAX-WS, if you specify the packageName attribute, then all artifacts (Java complex data types, JWS interface, and the JWS interface implementation) are generated into this package. If you want to change the package name of the generated Java complex data types in this case, use the <binding> child element of the wsdlc Ant task to specify a custom binding declarations file. For information about creating a custom binding declarations file, see Using JAXB Data Binding in Developing JAX-WS Web Services for Oracle WebLogic Server.

  • For JAX-RPC, if you specify the packageName attribute of the wsdlc Ant task, only the generated JWS interface and implementation are in this package. The package name of the generated Java complex data types, however, always corresponds to the XSD Schema type namespace, whether you specify the packageName attribute or not.

See Creating a web service from a WSDL File in Developing JAX-WS Web Services for Oracle WebLogic Server for a complete example of using the wsdlc Ant task in conjunction with jwsc.

The following sections discuss additional important information about wsdlc:

Taskdef Classname

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

Child Elements

The wsdlc Ant task has the following WebLogic-specific child elements:

For a list of elements associated with the standard Ant javac task that you can also set for the wsdlc Ant task, see Standard Ant javac Attributes That Apply To wsdlc.

binding

Use the <binding> child element to specify one of the following:

  • For JAX-WS, one or more customization files that specify JAX-WS and JAXB custom binding declarations. See Customizing XML Schema-to-Java Mapping Using Binding Declarations in Developing JAX-WS Web Services for Oracle WebLogic Server.

  • For JAX-RPC, one or more XMLBeans configuration files, which by convention end in .xsdconfig. Use this element if your web service uses Apache XMLBeans at http://xmlbeans.apache.org/ data types as parameters or return values.

The <binding> element is similar to the standard Ant <Fileset> element and has all the same attributes. See the Apache Ant documentation on the Fileset element at http://ant.apache.org/manual/Types/fileset.html for the full list of attributes you can specify.

xmlcatalog

The <xmlcatalog> child element specifies the ID of an embedded XML catalog. The following shows the element syntax: 

<xmlcatalog refid="id"/>

The ID referenced by <xmlcatalog> must match the ID of an embedded XML catalog. You embed an XML catalog in the build.xml file using the following syntax: 

<xmlcatalog id="id">
     <entity publicid="public_id" location="uri"/>
</xmlcatalog>

In the above syntax, public_id specifies the public identifier of the original XML resource (WSDL or XSD) and uri specifies the replacement XML resource.

The following example shows how to embed an XML catalog and reference it using wsdlc. Relevant code lines are shown in bold. 

<target name="wsdlc">
    <wsdlc
        srcWsdl="wsdl_files/TemperatureService.wsdl"
        destJwsDir="output/compiledWsdl"
        destImplDir="output/impl"
        packageName="examples.webservices.wsdlc" 
        <xmlcatalog refid="wsimportcatalog"/>
    </wsdlc>
</target>
<xmlcatalog id="wsimportcatalog">
    <entity publicid="http://helloservice.org/types/HelloTypes.xsd"
             location="${basedir}/HelloTypes.xsd"/>
</xmlcatalog>

See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

Attributes

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

WebLogic-Specific wsdlc Attributes

The following table describes the WebLogic-specific wsdlc attributes.

Table 2-12 WebLogic-specific Attributes of the wsdlc Ant Task

Attribute Description Data Type Required? JAX-RPC, JAX-WS, or Both?

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

JAX-RPC

catalog

Specifies an external XML catalog file. See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

String

No

Both

destImplDir

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

Both

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

Both

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

Both

explode

Specifies whether the generated JAR file that contains the generated JWS interface file and data binding artifacts is in exploded directory format or not.

Valid values for this attribute are true or false. Default value is false, which means that wsdlc generates an actual JAR archive file, and not an exploded directory.

Boolean

No

Both

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

JAX-RPC

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

Both

sortSchemaTypes

In an XSD file, two complex types are defined, one a named global type and the other an unnamed local type. By default, clientgen automatically generates its own name for the unnamed local type, and the name generated when compiling different WSDL files is not always consistent.

When enabled, the type names in the Java files generated by clientgen will be the same.

Boolean

No

JAX-RPC

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}MyBinding"

Note: This attribute is deprecated as of Version 9.2 of WebLogic Server. Use srcPortName or srcServiceName instead.

String

Only if the WSDL file contains more than one <binding> element

JAX-RPC

srcPortName

Name of the WSDL port from which the JWS interface file should be generated.

Set the value of this attribute to the value of the name attribute of the <port> element that corresponds to the web service port for which you want to generate a JWS interface file. The <port> element is a child element of the <service> element in the WSDL file.

If you do not specify this attribute, wsdlc generates a JWS interface file from the service specified by srcServiceName.

Note: For JAX-RPC, if you specify this attribute, you cannot also specify srcServiceName.

String

No

Both

srcServiceName

Name of the web service from which the JWS interface file should be generated.

Set the value of this attribute to the value of the name attribute of the <service> element that corresponds to the web service for which you want to generate a JWS interface file.

The wsdlc Ant task generates a single JWS endpoint interface and data binding JAR file for a given web service. This means that if the <service> element contains more than one <port> element, the following must be true:

  • The bindings for each port must be the same or equivalent to each other.

  • The transport for each port must be different. The wsdlc Ant task determines the transport for a port from the address listed in its <address> child element. Because WebLogic web services support only three transports (JMS, HTTP, and HTTPS), this means that there can be at most three <port> child elements for the <service> element specified by this attribute. The generated JWS implementation file will then include the corresponding @WLXXXTransport annotations (for JAX-RPC web services).

If you do not specify either this or the srcPortName attribute, the WSDL file must include only one <service> element. The wsdlc Ant task generates the JWS interface file and data binding JAR file from this single web service.

Note: For JAX-RPC, if you specify this attribute, you cannot also specify srcPortName.

String

No

Both

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

Both

type

Specifies the type of web service for which you are generating a partial implementation: JAX-WS or JAX-RPC.

Valid values are:

  • JAXWS

  • JAXRPC

Default value is JAXRPC.

String

No

Both

typeFamily

Specifies the type of data binding classes to generate.

Valid values are:

  • TYLAR—Refers to the standard WebLogic web services data binding classes, described in Using JAXB Data Binding in Developing JAX-WS Web Services for Oracle WebLogic Server.

  • XMLBEANS

  • XMLBEANS_APACHE

Default value is TYLAR.

Note: JAXB data binding classes are always generated for a JAX-WS web service.

String

No

JAX-RPC

wlw81CallbackGen

Specifies whether to generate a WebLogic Workshop 8.1 style callback.

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

Boolean

No

JAX-RPC
Standard Ant javac Attributes That Apply To wsdlc

In addition to the WebLogic-specific wsdlc attributes, you can also define the following standard javac attributes; see the Ant documentation at http://ant.apache.org/manual/ for additional information about each attribute:

  • bootclasspath

  • bootClasspathRef

  • classpath

  • classpathRef

  • compiler

  • debug

  • debugLevel

  • depend

  • deprecation

  • destdir

  • encoding

  • extdirs

  • failonerror

  • fork

  • includeantruntime

  • includejavaruntime

  • listfiles

  • memoryInitialSize

  • memoryMaximumSize

  • nowarn

  • optimize

  • proceed

  • source

  • sourcepath

  • sourcepathRef

  • tempdir

  • verbose

You can also use the following standard Ant child elements with the wsdlc Ant task:

  • <FileSet>

  • <SourcePath>

  • <Classpath>

  • <Extdirs>

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" 
        type="JAXWS" />
  </target>
  <target name="build-service">
    <jwsc
      srcdir="src"
      destdir="output/wsdlcEar">
      <jws file=
"examples/webservices/wsdlc/TemperatureService_TemperaturePortTypeImpl.java"
           compiledWsdl="output/compiledWsdl/TemperatureService_wsdl.jar" 
           type="JAXWS"/>
    </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).

For JAX-WS, the name of the stubbed-out JWS implementation file is based on the name of the <service> element and its inner <port> element in the WSDL file. For example, if the service name is TemperatureService and the port name is TemperaturePortType, then the generated JWS implementation file is called TemperatureService_TemperaturePortTypeImpl.java.

For JAX-RPC, the name of the stubbed-out JWS implementation file is based on the name of the <portType> element 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 TemperatureService_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.

wsdlget

The wsdlget Ant task downloads to the local directory a WSDL and its imported XML resources.

You may wish to use the download files when defining and referencing an XML catalog to redirect remote XML resources in your application to a local version of the resources.

See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

The following sections discuss additional important information about wsdlget:

Taskdef Classname

    <taskdef name="wsdlget"
           classname="weblogic.wsee.tools.anttasks.WsdlGetTask"/>

Child Elements

The wsdlget Ant task has one WebLogic-specific child element: <xmlcatalog>. The <xmlcatalog> child element specifies the ID of an embedded XML catalog. The following shows the element syntax: 

<xmlcatalog refid="id"/>

The ID referenced by <xmlcatalog> must match the ID of an embedded XML catalog. You embed an XML catalog in the build.xml file using the following syntax: 

<xmlcatalog id="id">
     <entity publicid="public_id" location="uri"/>
</xmlcatalog>

In the above syntax, public_id specifies the public identifier of the original XML resource (WSDL or XSD) and uri specifies the replacement XML resource.

The following example shows how to embed an XML catalog and reference it using wsdlget. Relevant code lines are shown in bold. 

<target name="wsdlget">
<wsdlget 
     wsdl="${wsdl}"
     destDir="${wsdl.dir}"
     catalog="wsdlcatalog.xml"/>
     <xmlcatalog refid="wsimportcatalog"/>
</wsdlget>
</target>
<xmlcatalog id="wsimportcatalog">
     <entity publicid="http://helloservice.org/types/HelloTypes.xsd"
             location="${basedir}/HelloTypes.xsd"/>
</xmlcatalog>

See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

Attributes

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

Table 2-13 WebLogic-specific Attributes of the wsdlget Ant Task

Attribute Description Data Type Required? JAX-RPC, JAX-WS, or Both?

catalog

Specifies an external XML catalog file. See Using XML Catalogs in Developing JAX-WS Web Services for Oracle WebLogic Server.

String

No

Both

destDir

Directory into which the XML resources are copied.

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

Yes

Both

wsdl

Name of the WSDL to copy to the local directory.

String

No

Both

Example

The following excerpt from an Ant build.xml file shows how to use the wsdlget Ant task to download a WSDL and its imported XML resources. The XML resources will be saved to the wsdl folder in the directory from which the Ant task is run. 

<target name="wsdlget"
     <wsdlget 
          wsdl="http://host/service?wsdl"
          destDir="./wsdl/"
     />
</target>