For executing stub-based Web Service clients, you require a path or a URL for a WSDL. During this, WSDLs to be referenced differs depending on the combination of the following conditions:

• When injecting service classes and ports by using the javax.xml.ws.WebServiceRef annotation
  For the WSDL documents that are referenced when injecting service classes or ports, see 19.3.1(2) The wsdlLocation element (javax.xml.ws.WebServiceRef).
  
• When generating service class instances by using a constructor for service classes
• WSDLs to be referenced vary for different combinations of the following conditions:
  
  • Which constructor of a service class is to be used
  • Whether the cjwsimport command is executed by specifying the -wsdllocation option

The following table describes the mapping between each condition and the referenced WSDL. For the examples of each condition, see 3.6.1(5)(a) Creating service class instances.

Table 3-5 Mapping between the combination of conditions and referenced WSDLs

Legend:

Y: When the option is specified.

N: When the option is not specified.

--: Specifying the option does not affect the referenced WSDL.

#1

When you execute a Web service client, the WSDL must exist at the location same as would exist during the execution of the cjwsimport command. Even when you specify a relative path for executing the cjwsimport command, the WSDL must exist at the location same as would exist during the execution of the cjwsimport command.

#2

When you specify an absolute URL, the WSDL must exist at the location that is indicated in the URL during the execution of the Web Services client.

When you specify a relative URL, the WSDL must exist at the location where the relative URL is resolved with the current directory as a base.

For a URL (endpoint address) of the Web Service to be connected, the address information (location attribute of the soap:address child element) included in the WSDL port (wsdl:port element) will be used by default. However, if using the javax.xml.ws.service.endpoint.address property of the message context, you can dynamically change the endpoint address. For the examples about dynamically changing the endpoint addresses, see 3.6.1(5)(c) Invoking a method of the port.

The generation of a service class and acquisition of ports involves a processing cost, and therefore, we recommend that you inject or reuse ports as follows:

• When implementing Web Services clients as servlets or EJB
  Inject ports when implementing Web Services clients as servlets or EJB. For details on the port injection, see 10.21 Injection.
  
• When implementing a Web Services client by using a different application (such as a command line application)
  You can use the initialization process to generate service classes and acquire ports, and reuse the generated classes and the acquired ports. You need not generate a service class every time you acquire a port or acquire a port every time you call a method.
  

When a WSDL of the Web Service to be invoked contains multiple services (wsdl:service element), use a constructor with the java.net.URL and javax.xml.namespace.QName objects as parameters for generating service classes, and clearly specify whether to invoke the services (wsdl:service element) with the javax.xml.namespace.QName object.

To implement a Web Services client, you can generate a service class by using a constructor or can use the port injection. This sub-section describes the procedure to implement the Web Services client when generating a service class by using a constructor. For details on the port injection, see 10.21.1 Injecting service classes and ports.

When developing stub-based Web Service clients, use the cjwsimport command to generate the Java sources required for invoking Web Services. Execute the cjwsimport command without specifying the -generateService option.

The stub-based Web Service client uses the following Java sources to invoke Web Services:

• Service class
  A service class corresponds to the WSDL services (wsdl:service element) that are used for invoking Web Services defined in the JAX-WS 2.2 specifications. The wsdl:service element compiles multiple ports in such a way so that the wsdl:port elements are compiled.
  For implementing a Web Service client, first of all generate the instances of the service classes.
  
• Port
  This is an instance corresponding to the WSDL port (wsdl:port element), and the interface is the Service Endpoint Interface (SEI). To operate as a proxy of remote connection-destination Web Services, the Web Service client can invoke a method of this port for transparently invoking the operations of the Web Services.
  

To implement a Web Services client for invoking the operations of Web Services:

1. Create a service class instance
2. Acquire a port
3. Invoke a method of the port

This point describes an implementation example for a Web Service client that invokes a Web Service (Web Service that performs additions) with the configuration described in 5.1 Configuration of development examples (Starting from SEI).

The following table describes the classes and methods used for implementing Web Service clients. As and when required, see the contents of service class products described in 5.5.1 Generating a service class.

Table 3-6 Classes and methods used in the implementation example for Web Service clients

(a) Creating service class instances

The following is an example of generating objects of a service class using the default constructor:

// Creating a service class instance
AddNumbersImplService service = new AddNumbersImplService();

In this case, the WSDL that is specified in the arguments of the cjwsimport command or in the -wsdllocation option is referenced.

The following are three examples of the cases when you do not specify the -wsdllocation option while executing the cjwsimport command:

Execution example 1

> "%COSMINEXUS_HOME%\jaxws\bin\cjwsimport.bat" D:\dev\development.wsdl

D:\dev\development.wsdl must also exist during the execution of the Web Service client, and must be available for the reference.

Execution example 2

> D: > cd D:\dev\ > "%COSMINEXUS_HOME%\jaxws\bin\cjwsimport.bat" relative\development.wsdl

D:\dev\relative\development.wsdl must exist during the execution of the Web Service client, and must also be available for the reference.

Execution example 3

> "%COSMINEXUS_HOME%\jaxws\bin\cjwsimport.bat" http://sample.com/fromjava/AddNumbersImplService?wsdl

http://sample.com/fromjava/AddNumbersImplService?wsdl must exist during the execution of the Web Service client, and must also be available for the reference.

The following are two examples of the cases when you specify the -wsdllocation option while executing the cjwsimport command:

Execution example 1

> "%COSMINEXUS_HOME%\jaxws\bin\cjwsimport.bat" -wsdllocation file:/home/wsdl4runtime/master.wsdl D:\dev\development.wsdl

file:/home/wsdl4runtime/master.wsdl must exist during the execution of the Web Service client, and must also be available for the reference. D:\dev\development.wsdl is used only to generate the Java code required for the implementation, for developing a Web Service client. Therefore, there is no problem even if D:\dev\development.wsdl does not exist during the execution or D:\dev\development.wsdl is not available for the reference.

Execution example 2

> "%COSMINEXUS_HOME%\jaxws\bin\cjwsimport.bat" -wsdllocation ./wsdl4runtime/master.wsdl D:\dev\development.wsdl

When you assume the current directory during the execution of the Web Service client as runtime-current-directory, runtime-current-directory/wsdl4runtime/master.wsdl must exist and available for the reference.

The following example describes a case when using a constructor having the java.net.URL object and the javax.xml.namespace.QName object as parameters, instead of using the default constructor:

// Creating a service class instance
java.net.URL wsdlLocation = new java.io.File( "./wsdl4runtime/master.wsdl" ).toURL();
javax.xml.namespace.QName serviceName =
  new javax.xml.namespace.QName( "http:/sample.com/", "AddNumbersImplService");
AddNumbersImplService service = 
  new AddNumbersImplService( wsdlLocation, serviceName );

Because a WSDL with the URL specified by the java.net.URL object is referenced, it is all right even if the WSDL specified by the arguments of the cjwsimport command and by the -wsdllocation option do not exist or cannot be referenced during the execution of the Web Service client. However, when you assume runtime-current-directory as the current directory during the execution of the Web Service client, runtime-current-directory/wsdl4runtime/master.wsdl must exist and available for the reference.

(b) Acquiring a port

The following is an example of acquiring a port from the service class for which instances are created:

// Acquire a port
AddNumbersImpl port = service.getAddNumbersImplPort();

(c) Invoking a method of the port

The following is an example of invoking a method of the port acquired from the service class for which instances are created:

// Invoke a method of the port
int returnValue = port.add(205, 103)

In this execution example, if you pass two values to the arguments of the method of the port, the addition processing will be performed in the Web Services. The result of addition will be returned as the return value.

By default, the address information (location attribute of the soap:address child element) included in the WSDL port (wsdl:port element) is used as the URL (endpoint address) of the Web Service to be connected. However, if you use the javax.xml.ws.service.endpoint.address property of the message context, you can dynamically change the endpoint address.

If you are not dynamically changing the endpoint address, check that a URL that can be accessed from the Web Service client is coded in the location attribute of the soap:address child element of the referenced WSDL.

If you are dynamically changing the endpoint address, acquire a request context before invoking a method of the port, and then change the value of the javax.xml.ws.service.endpoint.address property. The following is an example:

// Acquire a request context
java.util.Map<String, Object> context =
  ( ( javax.xml.ws.BindingProvider )port ).getRequestContext();
 
// Change the endpoint address
// (javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY is a constant
//  defining "javax.xml.ws.service.endpoint.address")
context.put( javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
   "http://other.remote.org/fromjava/AddNumbersImplService" );
 
// Invoke a method of the port
int returnValue = port.add(205, 103)

Notes

The generation of a service class and acquisition of a port involve a processing cost, so we recommend the re-usage of the generated or acquired service classes and ports. For invoking a Web method of port multiple times, you need not generate the service class and acquire the port multiple times However, when sharing the port with multiple threads, the changes in the property of request context of the port to be shared must be performed before operating multiple threads. If the changes are performed when operating multiple threads, communication might fail and an invalid SOAP message might be sent.

The following is an example of invoking a method of port multiple times:

// Create a service class instance AddNumbersImplService service = new AddNumbersImplService(); // Acquire a port AddNumbersImpl port = service.getAddNumbersImplPort(); // Invoke a method of the port multiple times for (int i = 0; i < 10; i++) { int returnValue = port.add(i, i); }

From a Web Service client for a Java application, use the service classes to implement the processing for invoking a Web Service.

This point describes an implementation example for a Web Service client that invokes a Web Service (Web Service that performs additions) with the configuration described in 5.1 Configuration of development examples (Starting from SEI). The following table describes the classes and methods used for implementing Web Service clients. As and when required, see the contents of service class products described in 5.5.1 Generating a service class.

Table 3-7 Classes and methods used in the implementation example for Web Service clients (Web Service client for a Java application)

The following is an execution example for Java applications:

package com.example.sample.client;
 
import com.example.sample.AddNumbersImplTestJaxWs;
import com.example.sample.AddNumbersImplTestJaxWsService;
import com.sample.AddNumbersFault_Exception;
 
// Sample implementation of web service's client
public class TestClient {
    public static void main( String[] args ) {
        try {
            // Create a service class instance
            AddNumbersImplTestJaxWsService service = new AddNumbersImplTestJaxWsService();
            // Acquire a port
            AddNumbersImplTestJaxWs port = service.getAddNumbersImplPortTestJaxWs();
            
            // Invoke a method of the port
            port.jaxWsTest1( ... );
            int number1 = 205;
            int number2 = 103;
            int returnValue = port.add(number1, number2);
 
            // Display the results
            System.out.println( "[RESULT] " + number1 + " + " + number2 + " = " + returnValue );
        }
        catch( Exception e ){
            // Exception processing (Here, simply output the stack trace)
            e.printStackTrace();
        }
    }
}

The execution result of the program is as follows:

[RESULT] 205 + 103 = 308

From a Web Service client of the servlet type, implement the processing for invoking Web Services using the service class.

This point describes an implementation example for a Web Service client that invokes a Web Service (Web Service that performs additions) with the configuration described in 5.1 Configuration of development examples (Starting from SEI). The following table describes the classes and methods used for implementing Web Service clients. As and when required, see the contents of service class products described in 5.5.1 Generating a service class.

Table 3-8 Classes and methods used in the implementation example for the Web Service client (When invoked from servlets)

(a) Injecting ports

When a Web Service is invoked from a servlet, specify the javax.xml.ws.WebServiceRef annotation in the port type field, and inject ports.

The following is an example of injecting a port:

...
public class TestClient extends HttpServlet {
 
        // Inject a port in the port(AddNumbersImpl)type field
       @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;
 
    @Override
    public void init() {
        
    }
    ...
}

(b) Executing Web Service operations by invoking a method of the port

Use the port generated as a field of the servlet and invoke a method.

The following is an example of invoking the method:

...
public class TestClient extends HttpServlet {
 
        // Inject a port in the port(AddNumbersImpl)type field
       @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;
    ...
    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
        ...
            int number1 = ...; // Substitute the value acquired from the request object
            int number2 = ...; // Substitute the value acquired from the request object
            // Invoke the method of the port
            int returnValue = port.add(number1, number2);
            ...
    }
}

The following is a complete implementation example for invoking a Web Service from a servlet:

package com.sample.client;
 
import java.io.IOException;
import java.io.PrintWriter;
 
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
 
import com.sample.AddNumbersFault_Exception;
import com.sample.AddNumbersImpl;
import com.sample.AddNumbersImplService;
public class TestClient extends HttpServlet {
 
        // Inject a port in the port(AddNumbersImpl)type field
       @WebServiceRef(AddNumbersImplService.class)
    AddNumbersImpl port;
 
    @Override
    public void init() {
    }
 
    @Override
    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
        PrintWriter out = response.getWriter();
 
        try {
            // Invoke a method of the target web service.
            int number1 = ...; // Substitute the value acquired from the request object
            int number2 = ...; // Substitute the value acquired from the request object
            // Invoke the method of the port
            int returnValue = port.add(number1, number2);
            // Display the results
            out.println("<html><body>");
            out.println("<h1>RESULT</h1>");
            out.println(number1 + " + " + number2 + " = " + returnValue);
            out.println("</body></html>");
        } catch(AddNumbersFault_Exception e) {
            // Exception processing (Here, simply output the detailed message of the exception)
            out.println("<html><body>");
            out.println("<h1>" + e.getMessage() + "</h1>");
            out.println("</body></html>");
        }
    }
}

The following is the execution result of the program. The execution result is displayed when you connect browser to the servlet.

RESULT
205 + 103 = 308

(C) Notes

In an environment where a Web Services client (servlet) and Web Service you want to connect to, both are deployed on the same J2EE server, an exception occurs if you start the J2EE server in the following conditions:

• When generating a service class by acquiring the WSDL from Web Services, if you specify the load-on-startup element in web.xml of the WAR file that has the Web Services client, in methods in which you have specified the init method or the javax.annotation.PostConstruct annotation.
• If you inject a service class or a port by acquiring the WSDL from Web Services by using the javax.xml.ws.WebServiceRef annotation.

The following is a list of actions to be taken if an exception is thrown:

• End the Web application that includes the Web Services client before you stop the J2EE server. After you restart the J2EE server, restart a Web application that includes the Web Services client.
• After you deploy Web Service and a Web Services client on a different J2EE server and start the J2EE server on which Web Service is deployed, start the J2EE server on which the Web Services client is deployed.
• Use the catalog functionality to perform the settings in such a way that you can reference the WSDL document that is locally stored when service classes are generated.
• When generating a service class by using the init method or a method in which the javax.annotation.PostConstruct annotation is specified, specify the local WSDL document in a constructor that uses a URL as a parameter and then generate a service class. Alternatively, do not specify the load-on-startup element in web.xml.
• When using the javax.xml.ws.WebServiceRef annotation, specify the locally stored WSDL document in the wsdlLocation element with a relative path or absolute path.