The clientgen WebLogic web services Ant task generates, from an existing WSDL file, the client artifacts that client applications use to invoke both WebLogic and non-WebLogic web services. These artifacts 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.

For additional information about the clientgen Ant task, such as all the available attributes, see Ant Task Reference in the WebLogic Web Services Reference for Oracle WebLogic Server.

Update your build.xml file, adding a call to the clientgen Ant task, as shown in the following example:

  <taskdef name="clientgen"
     classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <target name="build-client">
     <clientgen
       wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
       destDir="clientclasses"
       packageName="examples.webservices.simple_client"
       type="JAXWS"/>
  </target>

Before you can execute the clientgen WebLogic web service Ant task, you must specify its full Java classname using the standard taskdef Ant task.

You must include the wsdl and destDir attributes of the clientgen Ant task to specify the WSDL file from which you want to create client-side artifacts and the directory into which these artifacts should be generated. The packageName attribute is optional; if you do not specify it, the clientgen task uses a package name based on the targetNamespace of the WSDL. The type is required in this example.

In this example, the package name is set to the same package name as the client application, examples.webservices.simple_client. If you set the package name to one that is different from the client application, you would need to import the appropriate class files. For example, if you defined the package name as examples.webservices.complex, you would need to import the following class files in the client application:

import examples.webservices.complex.BasicStruct;
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;

If the WSDL file specifies that user-defined data types are used as input parameters or return values of web service operations, clientgen automatically generates a JavaBean class that is the Java representation of the XML Schema data type defined in the WSDL. The JavaBean classes are generated into the destDir directory.

For a full sample build.xml file that contains additional targets from those described in this procedure, such as clean, see Sample Ant Build File for a Java Client.

To execute the clientgen Ant task, along with the other supporting Ant tasks, specify the build-client target at the command line:

prompt> ant build-client

See the clientclasses directory to view the files and artifacts generated by the clientgen Ant task.

In the following code example, a Java application invokes a web service operation. The application uses standard JAX-WS API code and the web service-specific implementation of the Service interface, generated by clientgen, to invoke an operation of the web service.

The example also shows how to invoke an operation that has a user-defined data type (examples.webservices.simple_client.BasicStruct) as an input parameter and return value. The clientgen Ant task automatically generates the Java code for this user-defined data type.

Because the <clientgen> packageName attribute was set to the same package name as the client application, we are not required to import the <clientgen>-generated files.

package examples.webservices.simple_client;
/**
 * This is a simple Java application that invokes the
 * the echoComplexType operation of the ComplexService web service.
 */
public class Main {
  public static void main(String[] args) { 
    ComplexService test = new ComplexService(); 
    ComplexPortType port = test.getComplexPortTypePort();
    BasicStruct in = new BasicStruct();
    in.setIntValue(999);
    in.setStringValue("Hello Struct");
    BasicStruct result = port.echoComplexType(in);
    System.out.println("echoComplexType called. Result: " + result.getIntValue() + ", " + result.getStringValue());
  }
}

In the preceding example:

• The following code shows how to create a ComplexPortType stub:

  ComplexService test = new ComplexService(), 
  ComplexPortType port = test.getComplexPortTypePort();
  

  The ComplexService class implements the JAX-WS Service interface. The getComplexServicePortTypePort() method is used to return an instance of the ComplexPortType stub implementation.

• The following code shows how to invoke the echoComplexType operation of the ComplexService web service:

  BasicStruct result = port.echoComplexType(in);
  

  The echoComplexType operation returns the user-defined data type called BasicStruct.

Add javac tasks to the build-client target in the build.xml file to compile all the Java files (both of your client application and those generated by clientgen) into class files, as shown by the bold text in the following example:

  <target name="build-client">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
      destDir="clientclasses"
      packageName="examples.webservices.simple_client"
      type="JAXWS"/>
    <javac
      srcdir="clientclasses" 
      destdir="clientclasses"
      includes="**/*.java"/>
    <javac
      srcdir="src" 
      destdir="clientclasses"
      includes="examples/webservices/simple_client/*.java"/>
  </target>

In the example, the first javac task compiles the Java files in the clientclasses directory that were generated by clientgen, and the second javac task compiles the Java files in the examples/webservices/simple_client subdirectory of the current directory; where it is assumed your Java client application source is located.

In the preceding example, the clientgen-generated Java source files and the resulting compiled classes end up in the same directory (clientclasses). Although this might be adequate for prototyping, it is often a best practice to keep source code (even generated code) in a different directory from the compiled classes. To do this, set the destdir for both javac tasks to a directory different from the srcdir directory. To run the client application, add a run target to the build.xml that includes a call to the java task, as shown below:

<path id="client.class.path">
    <pathelement path="clientclasses"/>
    <pathelement path="${java.class.path}"/>
</path>
<target name="run" >
    <java 
       fork="true" 
       classname="examples.webServices.simple_client.Main"
       failonerror="true" >
       <classpath refid="client.class.path"/>
</target>

The path task adds the clientclasses directory to the CLASSPATH. The run target invokes the Main application, passing it the URL of the deployed web service as its single argument.

See Sample Ant Build File for a Java Client for a full sample build.xml file that contains additional targets from those described in this procedure, such as clean.

Rerun the build-client target to regenerate the artifacts and recompile into classes, then execute the run target to invoke the echoStruct operation:

    prompt> ant build-client run

You can use the build-client and run targets in the build.xml file to iteratively update, rebuild, and run the Java client application as part of your development process.

The following example shows a complete build.xml file for generating and compiling a Java client. See Using the clientgen Ant Task To Generate Client Artifacts and Compiling and Running the Client Application for explanations of the sections in bold.

<project name="webservices-simple_client" default="all">
  <!-- set global properties for this build -->
  <property name="wls.hostname" value="localhost" />
  <property name="wls.port" value="7001" />
  <property name="example-output" value="output" />
  <property name="clientclass-dir" value="${example-output}/clientclass" />
  <path id="client.class.path">
    <pathelement path="${clientclass-dir}"/>
    <pathelement path="${java.class.path}"/>
  </path>
  <taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <target name="clean" >
    <delete dir="${clientclass-dir}"/>
  </target>
  <target name="all" depends="clean,build-client,run" />
  <target name="build-client">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
      destDir="${clientclass-dir}"
      packageName="examples.webservices.simple_client"
      type="JAXWS"/>
    <javac
      srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
      includes="**/*.java"/>
    <javac
      srcdir="src" destdir="${clientclass-dir}"
      includes="examples/webservices/simple_client/*.java"/>
  </target>
  <target name="run" >
    <java fork="true"
          classname="examples.webservices.simple_client.Main"
          failonerror="true" >
      <classpath refid="client.class.path"/>
    </java>
  </target>
</project>

The following sample build.xml file shows how to create a web service that itself invokes another web service; the relevant sections that differ from the build.xml for building a simple web service that does not invoke another web service are shown in bold.

The build-service target in this case is very similar to a target that builds a simple web service; the only difference is that the jwsc Ant task that builds the invoking web service also includes a <clientgen> child element of the <jws> element so that jwsc also generates the required JAX-WS client stubs.

<project name="webservices-service_to_service" default="all">
  <!-- set global properties for this build -->
  <property name="wls.username" value="weblogic" />
  <property name="wls.password" value="weblogic" />
  <property name="wls.hostname" value="localhost" />
  <property name="wls.port" value="7001" />
  <property name="wls.server.name" value="myserver" />
  <property name="ear.deployed.name" value="ClientServiceEar" />
  <property name="example-output" value="output" />
  <property name="ear-dir" value="${example-output}/ClientServiceEar" />
  <property name="clientclass-dir" value="${example-output}/clientclasses" />
  <path id="client.class.path">
    <pathelement path="${clientclass-dir}"/>
    <pathelement path="${java.class.path}"/>
  </path>
  <taskdef name="jwsc"
    classname="weblogic.wsee.tools.anttasks.JwscTask" />
  <taskdef name="clientgen"
    classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
  <taskdef name="wldeploy"
    classname="weblogic.ant.taskdefs.management.WLDeploy"/>
  <target name="all" depends="clean,build-service,deploy,client" />
  <target name="clean" depends="undeploy">
    <delete dir="${example-output}"/>
  </target>
  <target name="build-service">
    <jwsc
        srcdir="src"
        destdir="${ear-dir}" >
        <jws
         file="examples/webservices/service_to_service/ClientServiceImpl.java"
         type="JAXWS">
          <clientgen
                wsdl="http://${wls.hostname}:${wls.port}/complex/ComplexService?WSDL"
                packageName="examples.webservices.complex" />
        </jws>
    </jwsc>
  </target>
  <target name="deploy">
    <wldeploy action="deploy" name="${ear.deployed.name}"
      source="${ear-dir}" user="${wls.username}"
      password="${wls.password}" verbose="true"
      adminurl="t3://${wls.hostname}:${wls.port}"
      targets="${wls.server.name}" />
  </target>
  <target name="undeploy">
    <wldeploy action="undeploy" name="${ear.deployed.name}"
      failonerror="false"
      user="${wls.username}"
      password="${wls.password}" verbose="true"
      adminurl="t3://${wls.hostname}:${wls.port}"
      targets="${wls.server.name}" />
  </target>
  <target name="client">
    <clientgen
      wsdl="http://${wls.hostname}:${wls.port}/ClientService/ClientService?WSDL"
      destDir="${clientclass-dir}"
      packageName="examples.webservices.service_to_service.client"
      type="JAXWS"/>
    <javac
      srcdir="${clientclass-dir}" destdir="${clientclass-dir}"
      includes="**/*.java"/>
    <javac
      srcdir="src" destdir="${clientclass-dir}"
      includes="examples/webservices/service_to_service/client/**/*.java"/>
  </target>
  <target name="run">
    <java classname="examples.webservices.service_to_service.client.Main"
          fork="true"
          failonerror="true" >
          <classpath refid="client.class.path"/>
    </java>
  </target>
</project>

The following sample JWS file, called ClientServiceImpl.java, implements a web service called ClientService that has an operation that in turn invokes the echoComplexType operation of a web service called ComplexService. This operation has a user-defined data type (BasicStruct) as both a parameter and a return value. The relevant code is shown in bold and described after the example.

package examples.webservices.service_to_service;

import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.xml.ws.WebServiceRef;

// Import the BasicStruct data type, generated by clientgen and used
// by the ComplexService Web Service
import examples.webservices.complex.BasicStruct;

// Import the JAX-WS stubs generated by clientgen for invoking
// the ComplexService web service.
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;

@WebService(name="ClientPortType", serviceName="ClientService",
            targetNamespace="http://examples.org")
public class ClientServiceImpl {
// Use the @WebServiceRef annotation to define a reference to a web service.
  @WebServiceRef()
  ComplexService test;

  @WebMethod()
  public String callComplexService(BasicStruct input, String serviceUrl) 
  {
    // Create a port stub to invoke ComplexService
    ComplexPortType port = test.getComplexPortTypePort();

    // Invoke the echoComplexType operation of ComplexService
    BasicStruct result = port.echoComplexType(input);
    System.out.println("Invoked ComplexPortType.echoComplexType." );
    return "Invoke went okay!  Here's the result: '" + result.getIntValue() + 
           ",  " + result.getStringValue() + "'";
  }
}

Follow these guidelines when programming the JWS file that invokes another web service; code snippets of the guidelines are shown in bold in the preceding example:

• Import any user-defined data types that are used by the invoked web service. In this example, the ComplexService uses the BasicStruct JavaBean:

  import examples.webservices.complex.BasicStruct;
  

• Import the JAX-WS interfaces of the ComplexService web service; the stubs are generated by the <cliengen> child element of <jws>:

  import examples.webservices.complex.ComplexPortType;
  import examples.webservices.complex.ComplexService;
  
  

• Define a reference to a web service and an injection target for it using the @WebServiceRef annotation:

  @WebServiceRef()
  ComplexService service;
  

  For more information about @WebServiceRef, see Defining a Web Service Reference Using the @WebServiceRef Annotation.

  Alternatively, you can create a proxy stub to the ComplexService web service, as shown below:

  ComplexService service = new ComplexService();  
  

• Return an instance of the ComplexPortType stub implementation by calling the getComplexPortTypePort() operation on the web service reference:

  ComplexPortType port = service.getComplexPortTypePort();
  

• Invoke the echoComplexType operation of ComplexService using the port you just instantiated:

  BasicStruct result = port.echoComplexType(input);
  

To provide its client ID, the web service client can pass an instance of the ClientIdentityFeature containing the client ID to the web service port at initialization time.

The client ID must be unique within the Web application or EJB that contains the client. It is recommended that the client ID appropriately reflect the business purpose. In order to ensure that the client ID is unique, the system prepends the names of the containing server, application, and component (Web application or EJB) to the client ID.

The following example demonstrates this method of specifying the client ID. It is recommended that you close the client instance once all processing has been complete, as shown.

This example is excerpted from Roadmap for Developing JAX-WS Web Service Clients.

Client IDs that are generated automatically by the server use the following format:

applicationname[_applicationversion]:componentname:uniqueID

Where:

• applicationname—Name of the application hosting the client.

• applicationversion—Version of the application. Only used if multiple versions of the same application is running simultaneously.

• componentname—Name of the component (Web application or EJB) hosting the client.

• uniqueID—Calculated based on the information that is available when the client instance is created. The uniqueID is constructed by choosing one of the following (whichever is available):

  • Web service reference name, as defined by the @WebServiceRef annotation.

  • [portNamespaceURI:portLocalName][:][endpointAddress]—port name, endpoint address, or both (separated by a colon).

  • Port class simple name.

  The following information, when available, may also be concatenated to the uniqueID, separated by a colon (:), in the order presented below:

  • WSDL location (minus ?wsdl)

  • Features used to create the client instance, represented by the features class name and separated by dash (-).

For example, assume that you deploy a web service client with the following information associated with it:

• Application name: example

• Component: Web application called BestPracticeClient

• Port name: http://example/BackendServicePort

• Port class: BackendService

• WSDL: jar:file:/C:/example/BackendService.war!/WEB-INF/BackendServiceService.wsdl

The server-generated client ID will be:

example:BestPracticeClient:http://example/:BackendServicePort:jar:file:/C:/example/BackendService.war!/WEB-INF/BackendServiceService.wsdl:AsyncClientTransportFeature()-ClientIdentityFeature

Each time the code is executed, assuming it is in the same containment hierarchy, the same client ID is generated. This provides a stable client ID that can be used across server VM instances and allows for asynchronous responses to be delivered to the client even after a server restart.

The following example demonstrates how to access the server-generated client ID. This example is excerpted from Table 7-1.

A client ID is registered with the web services runtime when the first client instance (port or Dispatch instance) using the client ID is created. Any asynchronous response endpoint associated with the client instances is also tracked along with the registered client ID.

The client ID remains registered until one of the following occurs:

• The client ID is explicitly disposed using the dispose() method on ClientIdentityFeature, as described in Table 8-3.

• The container for the client instances that use the client ID is deactivated (for example, the host Web application or EJB is deactivated).

You can programmatically specify within the Java client application itself the details of the proxy server that will proxy the web service invoke using the weblogic.wsee.jaxws.proxy.ClientProxyFeature API. See ClientProxyFeature in Java API Reference for Oracle WebLogic Server.

The proxy server settings defined by the ClientProxyFeature override the settings defined at the JVM-level, as described in Using System Properties to Specify the Proxy Server.

You can configure the proxy server information using the ClientProxyFeature and pass the feature as an argument when creating the web service port, as shown in the following example.

Alternatively, you can configure the proxy server information after the port is created, as shown in the following example. In this case, you execute the attachsPort() method to attach the ClientProxyFeature to the existing port.

If after configuring the ClientProxyFeature and attaching it to the port you want to disable the client proxy settings, you set the proxy port to a negative value. For example:

To use system properties to specify the proxy server, write your client application in the standard way, and then specify Java system properties when you execute the client application.

The following table summarizes the Java system properties.

The following excerpt from an Ant build script shows an example of setting Java system properties when invoking a client application called clients.InvokeMyService:

  <target name="run-client">
     <java fork="true"
           classname="clients.InvokeMyService"
           failonerror="true">
       <classpath refid="client.class.path"/>
       <arg line="${http-endpoint}"/>
       <jvmarg line=
         "-Dhttp.proxyHost=${proxy-host} 
         -Dhttp.proxyPort=${proxy-port}
         -Dhttp.nonProxyHosts=${myhost}"
       />
     </java>
   </target>