6 Invoking Web Services

Using the clientgen Ant Task To Generate Client Artifacts

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 Oracle Fusion Middleware 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; otherwise, it defaults to JAXRPC.

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 Stand-Alone 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.

Getting Information About a Web Service

You need to know the name of the Web Service and the signature of its operations before you write your Java client application code to invoke an operation. There are a variety of ways to find this information.

The best way to get this information is to use the clientgen Ant task to generate the Web Service-specific Service files and look at the generated *.java files. These files are generated into the directory specified by the destDir attribute, with subdirectories corresponding to either the value of the packageName attribute, or, if this attribute is not specified, to a package based on the targetNamespace of the WSDL.

• The ServiceName.java source file contains the getPortName() methods for getting the Web Service port, where ServiceName refers to the name of the Web Service and PortName refers to the name of the port. If the Web Service was implemented with a JWS file, the name of the Web Service is the value of the serviceName attribute of the @WebService JWS annotation and the name of the port is the value of the portName attribute of the <WLHttpTransport> child element of the <jws> element of the jwsc Ant task.

• The PortType.java file contains the method signatures that correspond to the public operations of the Web Service, where PortType refers to the port type of the Web Service. If the Web Service was implemented with a JWS file, the port type is the value of the name attribute of the @WebService JWS annotation.

You can also examine the actual WSDL of the Web Service; see Browsing to the WSDL of the Web Service for details about the WSDL of a deployed WebLogic Web Service. The name of the Web Service is contained in the <service> element, as shown in the following excerpt of the TraderService WSDL:

  <service name="TraderService">
    <port name="TraderServicePort"
         binding="tns:TraderServiceSoapBinding">
  ...
    </port>
  </service>

The operations defined for this Web Service are listed under the corresponding <binding> element. For example, the following WSDL excerpt shows that the TraderService Web Service has two operations, buy and sell (for clarity, only relevant parts of the WSDL are shown):

  <binding name="TraderServiceSoapBinding" ...>
    ...
    <operation name="sell">
    ...
    </operation>
    <operation name="buy">
    </operation>
  </binding>

Writing the Java Client Application Code to Invoke a Web Service

In the following code example, a stand-alone 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 stand-alone client 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.

Compiling and Running the Client Application

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 Stand-Alone 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.

Sample Ant Build File for a Stand-Alone Java Client

The following example shows a complete build.xml file for generating and compiling a stand-alone 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>

Sample build.xml File for a Web Service Client

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

Sample JWS File That Invokes a Web Service

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 the BasicStruct data type, generated by clientgen and used
// by the ComplexService Web Service
import examples.webservices.complex.BasicStruct;
// Import the JAX-WS Stubs for invoking the ComplexService Web Service.
// Stubs generated by clientgen
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;
@WebService(name="ClientPortType", serviceName="ClientService",
            targetNamespace="http://examples.org")
public class ClientServiceImpl {
  @WebMethod()
  public String callComplexService(BasicStruct input, String serviceUrl) 
  {
    // Create service and port stubs to invoke ComplexService
    ComplexService test = new 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;
  
  

• Create the JAX-WS Service and PortType instances for the ComplexService:

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

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

  BasicStruct result = port.echoComplexType(input);
  

Defining a Web Service Reference Using the @WebServiceRef Annotation

The @WebServiceRef annotation enables you to define a reference to a Web Service. For example, in the following sample, a reference to the ComplexService is defined by passing the WSDL of the Web Service to the @WebServiceRef annotation.

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 interfaces for invoking the ComplexService Web Service.
// Interfaces generated by clientgen
import examples.webservices.complex.ComplexPortType;
import examples.webservices.complex.ComplexService;
@WebService(name="ClientPortType", serviceName="ClientService",
            targetNamespace="http://examples.org")
public class ClientServiceImpl {
    @WebServiceRef()
    ComplexService service;
  @WebMethod()
  public String callComplexService(BasicStruct input)
  {
    // Create service and port stubs to invoke ComplexService
    ComplexPortType port = service.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() + "'";
  }
}

In the preceding example:

• The @WebServiceRef annotation is used to define a reference to a Web Service and an injection target for it:

  @WebServiceRef()
  ComplexService service;
  

• The following code shows how to return an instance of the ComplexPortType stub implementation using the Web Service reference:

  ComplexPortType port = service.getComplexPortTypePort();
  

• The following code shows how to invoke the sayHello operation of the ComplexService Web Service:

  BasicStruct result = port.echoComplexType(input);