WebLogic Web Services: Reference

Ant Task Reference

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

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

Overview of WebLogic Web Services Ant Tasks

Ant is a Java-based build tool, similar to the make command but much more powerful. Ant uses XML-based configuration files (called build.xml by default) to execute tasks written in Java. BEA provides a number of Ant tasks that help you generate important Web Service-related artifacts.

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

prompt> ant -version 

List of Web Services Ant Tasks

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

Using the Web Services Ant Tasks

To use the Ant tasks:

Setting the Classpath for the WebLogic Ant Tasks

Each WebLogic Ant task accepts a classpath attribute or element so that you can add new directories or JAR files to your current CLASSPATH environment variable.

The following example shows how to use the classpath attribute of the jwsc Ant task to add a new directory to the CLASSPATH variable:

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

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

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

The following example shows how you can build your CLASSPATH variable outside of the WebLogic Web Service Ant task declarations, then specify the variable from within the task using the <classpath> element:

<path id="myClassID">
   <pathelement path="${java.class.path}"/>
   <pathelement path="${additional.path1}"/>
   <pathelement path="${additional.path2}"/>
</path>

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

Differences in Operating System Case Sensitivity When Manipulating WSDL and XML Schema Files

Many WebLogic Web Service Ant tasks have attributes that you can use to specify a file, such as a WSDL or an XML Schema file.

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

However, compiling these source files into their respective class files might cause a problem if you are running the Ant task on Microsoft Windows, because Windows is a case insensitive operating system. This means that Windows considers the files MyReturnType.java and MYRETURNTYPE.java to have the same name. So when you compile the files on Windows, the second class file overwrites the first, and you end up with only one class file. The Ant tasks, however, expect that two classes were compiled, thus resulting in an error similar to the following:

c:\src\com\bea\order\MyReturnType.java:14: 
class MYRETURNTYPE is public, should be declared in a file named   MYRETURNTYPE.java 
public class MYRETURNTYPE 
       ^ 

To work around this problem rewrite the XML Schema so that this type of naming conflict does not occur, or if that is not possible, run the Ant task on a case sensitive operating system, such as Unix.

clientgen

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

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

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.

Taskdef Classname

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

Examples

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

...

<target name="build_client">

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

<javac ... />

</target>

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

If you want the clientgen Ant task to compile and package the generated artifacts for you, specify the destFile attribute rather than destDir:

<clientgen
    wsdl="http://example.com/myapp/myservice.wsdl"
    destFile="/output/jarfiles/myclient.jar"
    packageName="myapp.myservice.client"
    serviceName="StockQuoteService" />

In the preceding 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.

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

wsdl="jar:file:archive_file!WSDL_file"

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

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

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

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

Finally, in the preceding examples, it is assumed that the Web Service for which you are generating client artifacts is based on JAX-RPC 1.1; the following example shows how to use the type attribute to specify that the Web Service is based on JAX-WS 2.0:

<clientgen
 type="JAXWS"
 wsdl="http://${wls.hostname}:${wls.port}/JaxWsImpl/JaxWsImplService?WSDL"
 destDir="/output/clientclasses"
 packageName="examples.webservices.jaxws.client"/>

Child Elements

The clientgen Ant task has one WebLogic-specific child element: <binding>.

SeeStandard Ant Attributes and Elements That Apply To clientgen for the list of elements associated with the standard Ant javac task that you can also set for the clientgen Ant task.

binding

Use the <binding> child element to specify one or more XMLBeans configuration files, which by convention end in .xsdconfig. Use this element if your Web Service uses Tylar 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 for the full list of attributes you can specify.

You can use this child element when generating client files for both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

Attributes

The table in the following section describes the attributes of the clientgen Ant task. SeeStandard Ant Attributes and Elements That Apply To clientgen for the list of attributes associated with the standard Ant javac task that you can also set for the clientgen Ant task.

WebLogic-Specific clientgen Attributes

Standard Ant Attributes and Elements That Apply To clientgen

In addition to the WebLogic-defined clientgen attributes, you can also define the following standard javac attributes; see the Ant documentation for additional information about each attribute:

You can use 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 for the java Ant task for additional information about <sysproperty>.

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

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

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 follows the JAX-RPC 1.1 specification. However, by using the type="JAXWS" attribute of the <jws> child element, you can alternatively specify that the Ant task generate a JAX-WS 2.0 Web Service.

You specify the JWS file or files you want the jwsc Ant task to compile using the <jws> element. 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>.

The following sections discuss additional important information about jwsc:

See Examples for examples of all the topics discussed in these sections.

Specifying the Transport Used to Invoke the Web Service

When you program your JWS file, you can use an annotation to specify the transport that clients use to invoke the Web Service, in particular @weblogic.jws.WLHttpTransport or @weblogic.jws.WLJMSTransport. You can specify only one of instance of a particular transport annotation in the JWS file. For example, although you cannot specify two different @WLHttpTransport annotations, you can specify one @WLHttpTransport and one @WLJmsTransport annotation. However, you might not know at the time that you are coding the JWS file which transport best suits your needs. For this reason, it is often better to specify the transport at build-time.

For this reason, it is often better to specify the transport at build-time The <jws> element includes the following optional child-elements for specifying the transports (HTTP/S or JMS) that are used to invoke the Web Service:

The following guidelines describe the usage of the transport elements for the jwsc Ant task:

How to Determine the Final Context Root of a WebLogic Web Service

There are a variety of places where the context root (also called context path) of a WebLogic Web Service can be specified. This section describes how to determine which is the true context root of the service based on its configuration, even if it is has been set in multiple places.

In the context of this discussion, a Web Service context root is the string that comes after the host:port portion of the Web Service URL. For example, if the deployed WSDL of a WebLogic Web Service is as follows:

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

The context root for this Web Service is financial.

The following list describes the order of precedence, from most to least important, of all possible context root specifications:

Suppose, for example, that you specified the @WLHttpTransport annotation in your JWS file and set its contextPath attribute to financial. If you do not specify any additional contextPath attributes in the jwsc Ant task in your build.xml file, then the context root for this Web Service would be financial.

Assume that you then update the build.xml file and add a <WLHttpTransport> child element to the <jws> element that specifies the JWS file and set its contextPath attribute to finance. The context root of the Web Service would now be finance. If, however, you then group the <jws> element (including its child <WLHttpTransport> element) under a <module> element, and set its contextPath attribute to money, then the context root of the Web Service would now be money.

If you do not specify any contextPath attribute in either the JWS file or the jwsc Ant task, then the context root of the Web Service is the default value: the name of the JWS file without its *.java extension. This means that if you have not specified either the @WLXXXTransport annotations or <WLXXXTransport> child elements of <jws>, but group two or more <jws> elements under a <module> element, then you must specify the contextPath attribute of <module> to specify the common context root used by all the Web Services in the module. This is because the default context roots for all the Web Services in the module are most likely going to be different (due to different names of the implementing JWS files), which is not allowed in a single WAR file.

Generating Client Artifacts for an Invoked Web Service

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.

Updating an Existing Enterprise Application or Web Application

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.

Generating a WSDL for JAX-WS Web Services

For JAX-WS Web Services, the WSDL file is not generated automatically by the jwsc Ant task. To generate a WSDL for JAX-WS Web Services, you need to include two instances of the <jws> child element, as follows:

The following provides an example of a jwsc Ant task that generates a WSDL for a JAX-WS Web Service and subsequently compiles the JWS file:

<jwsc 
   srcdir="src" 
   destdir="${ear-dir}"> 
   <jws file="hello_world.java" wsdlOnly="true" type="JAXWS"> 
      <WLHttpTransport serviceUri="myServiceURI" /> 
   </jws> 
   <jws file="hello_world.java" wsdlOnly="false" type="JAXWS"> 
      <WLHttpTransport serviceUri="myServiceURI" /> 
   </jws> 
</jwsc>

Taskdef Classname

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

Examples

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

The following sample shows a very simple usage of jwsc:

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

In the preceding 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.

The following example shows a more complicated use of jwsc:

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

...

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

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

The example also shows how to specify multiple JWS files, resulting in separate Web Services packaged in their own Web application WAR files, although all are still deployed as part of the same Enterprise Application. If you want all three Web Services packaged in a single WAR file, group the <jws> elements under a <module> element, as shown in the following example:

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

The preceding example shows how to package all three Web Services 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.

The following example shows how to specify that the Web Service can be invoked using all transports (HTTP/HTTPS/JMS):

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

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

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

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

In the preceding 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.

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

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

In the 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, described in the documentation for the standard <FilesSet> task.

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:

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

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

All preceding examples generated JAX-RPC 1.1 Web Services by default; the following simple example shows how to generate a JAX-WS 2.0 Web Service by specifying the type="JAXWS" attribute of the <jws> child element:

  <target name="build-service8">

    <jwsc
      srcdir="src"
      destdir="${ear-dir}">

      <jws file="examples/webservices/jaxws/JaxWsImpl.java"
           type="	"
      />

    </jwsc>

  </target>

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

Attributes and Child Elements of the jwsc Ant Task

The jwsc Ant task has a variety of attributes and two child elements: <jws> and <module>. The <module> element simply 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.

The <jws> element (when used as either a child element of <jwsc> or <module>) has three optional child elements: <WLHttpTransport>, <WLHttpsTransport>, and <WLJMSTransport>. See Specifying the Transport Used to Invoke the Web Service for common information about using the transport elements.

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 graphic describes the hierarchy of the jwsc Ant task.

The table in the following section describes the attributes of the jwsc Ant task. SeeStandard Ant Attributes and Child Elements That Apply to jwsc for the list of attributes associated with the standard Ant javac task that you can also set for the jwsc Ant task.

WebLogic-Specific jwsc Attributes

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 for additional information about each attribute:

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

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

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:

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

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. 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-RPC 1.1 and JAX-WS 2.0 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.

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

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 can not mix and match. By default, jwsc always implements your Web Service as a plain Java class; the only exception is if you have explicitly implemented javax.ejb.SessionBean 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 can not 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 and/or <WLXXXTrasnsport> 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.

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

You can use the <module> child element when generating both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. See Examples for examples of using the element.

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

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

WLHttpTransport

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

The <WLHttpTransport> element is a child of the <jws> element.

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

See Specifying the Transport Used to Invoke the Web Service for guidelines to follow when specifying this element.

You can use the <WlHttpTransport> child element when generating both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. See Examples for examples of using the element.

The following table describes the attributes of <WLHttpTransport>.

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

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

WLHttpsTransport

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

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 1.1 Web Services.

See Specifying the Transport Used to Invoke the Web Service for guidelines to follow when specifying this element.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy.

The following table describes the attributes of <WLHttpsTransport>.

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

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

WLJMSTransport

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

The <WLHJmsTransport> element is a child of the <jws> element.

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

You can use the <WLJmsTransport> child element only for generating JAX-RPC 1.1 Web Services.

See Specifying the Transport Used to Invoke the Web Service for guidelines to follow when specifying this element.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. See Examples for examples of using the element.

The following table describes the attributes of <WLJmsTransport>.

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

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

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:

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. 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 for the java Ant task for additional information about <sysproperty>.

You can use the <clientgen> child element for generating both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

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

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:

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.

You can use the <descriptor> child element only for generating JAX-RPC 1.1 Web Services.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. See Examples for examples of using the element.

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

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 for details about <FileSet> and its nested elements.

You can use the <jwsfileset> child element for generating both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

See Figure A-1 for a visual description of where this element fits in the jwsc element hierarchy. See Examples for examples of using the element.

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

binding

Use the <binding> child element to specify one or more XMLBeans configuration files, which by convention end in .xsdconfig. Use this element if your Web Service uses Tylar 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 for the full list of attributes.

You can use the <binding> child element for generating both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

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-RPC 1.1 or JAX-WS 2.0.

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.

Specifically, the wsdlc Ant task generates:

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

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

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

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

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

Taskdef Classname

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

Example

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

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

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

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

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

  </target>

  <target name="build-service">

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

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

    </jwsc>

  </target>

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

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

Child Elements

The wsdlc Ant task has one WebLogic-specific child element: <binding>.

SeeStandard Ant javac Attributes That Apply To wsdlc for the list of elements associated with the standard Ant javac task that you can also set for the wsdlc Ant task.

binding

Use the <binding> child element to specify one or more XMLBeans configuration files, which by convention end in .xsdconfig. Use this element if your Web Service uses Tylar 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 for the full list of attributes you can specify.

You can use the <binding> child element when generating a partial implemention of both JAX-RPC 1.1 and JAX-WS 2.0 Web Services.

Attributes

The table in the following section describes the attributes of the wsdlc Ant task. SeeStandard Ant javac Attributes That Apply To wsdlc for the list of attributes associated with the standard Ant javac task that you can also set for the wsdlc Ant task.

WebLogic-Specific wsdlc Attributes

Standard Ant javac Attributes That Apply To wsdlc

In addition to the WebLogic-defined wsdlc attributes, you can also define the following standard javac attributes; see the Ant documentation for additional information about each attribute:

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