Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
Creating Web Service Clients with JAX-RPC
This section shows how to create and run these types of clients:
When you run these client examples, they will access the
MyHelloService
that you deployed in the preceding section.Static Stub Client Example
This example resides in the
<INSTALL>
/jwstutorial13/examples/jaxrpc/staticstub/
directory.
HelloClient
is a stand-alone program that calls thesayHello
method of theMyHelloService
. It makes this call through a stub, a local object which acts as a proxy for the remote service. Because the stub is created before runtime (bywscompile
), it is usually called a static stub.Coding the Static Stub Client
Before it can invoke the remote methods on the stub the client performs these steps:
- Creates a
Stub
object:
(Stub)(new MyHelloService_Impl().getHelloIFPort())
The code in this method is implementation-specific because it relies on a
MyHelloService_Impl
object, which is not defined in the specifications. TheMyHelloService_Impl
class will be generated bywscompile
in the following section.- Sets the endpoint address that the stub uses to access the service:
stub._setProperty
(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]);At runtime, the endpoint address is passed to
HelloClient
inargs[0]
as a command-line parameter, whichant
gets from theendpoint.address
property in thebuild.properties
file.- Casts
stub
to the service endpoint interface,HelloIF
:
HelloIF hello = (HelloIF)stub;
Here is the full source code listing for the
HelloClient.java
file, which is located in the directory<INSTALL>
/jwstutorial13/examples/jaxrpc/staticstub/src/
:package staticstub; import javax.xml.rpc.Stub; public class HelloClient { private String endpointAddress; public static void main(String[] args) { System.out.println("Endpoint address = " + args[0]); try { Stub stub = createProxy(); stub._setProperty (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]); HelloIF hello = (HelloIF)stub; System.out.println(hello.sayHello("Duke!")); } catch (Exception ex) { ex.printStackTrace(); } } private static Stub createProxy() { // Note: MyHelloService_Impl is implementation-specific. return (Stub) (new MyHelloService_Impl().getHelloIFPort()); } }Building the Static Stub Client
Before performing the steps in this section, you must first create and deploy
MyHelloService
as described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/staticstub
/ directory and type the following:The preceding command invokes these
ant
tasks:The
generate-stubs
task runs thewscompile
tool as follows:This
wscompile
command reads the WSDL file that was installed on Tomcat when the service was deployed. Thewscompile
command generates files based on the information in the WSDL file and on the command-line flags. The-gen:client
flag instructswscompile
to generate the stubs, other runtime files such as serializers, and value types. The-d
flag tells the tool to write the output to thebuild
subdirectory. The tool reads the followingconfig-wsdl.xml
file, which specifies the location of the WSDL file:<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> <wsdl location="http://localhost:8080/hello-jaxrpc/ hello?WSDL" packageName="staticstub"/> </configuration>The
compile-client
task compilessrc/HelloClient.java
and writes the class file to thebuild
subdirectory.The
package-client
task packages the files created by the generate-stubs
andcompile-client
tasks into thedist/client.jar
file. Except for theHelloClient.class
, all of the files inclient.jar
were created bywscompile
. Note thatwscompile
generated theHelloIF.class
based on the information it read from the WSDL file.Running the Static Stub Client
To run the
HelloClient
program, type the following:The program should display this line:
The
ant run
target executes this command:The classpath includes the
client.jar
file that you created in the preceding section, as well as several JAR files that belong to the Java WSDP. In order to run the client remotely, all of these JAR files must reside on the remote client's computer.Dynamic Proxy Client Example
This example resides in the
<INSTALL>
/jwstutorial13/examples/jaxrpc/dynamicproxy/
directory.The client in the preceding section used a static stub for the proxy. In contrast, the client example in this section calls a remote procedure through a dynamic proxy, a class that is created during runtime. Although the source code for the static stub client relied on an implementation-specific class, the code for the dynamic proxy client does not have this limitation.
Coding the Dynamic Proxy Client
The
DynamicProxyHello
program constructs the dynamic proxy as follows:
- Creates a
Service
object namedhelloService:
Service helloService =
serviceFactory.createService(helloWsdlUrl,
new QName(nameSpaceUri, serviceName));A
Service
object is a factory for proxies. To create theService
object (helloService
), the program calls thecreateService
method on another type of factory, aServiceFactory
object.The
createService
method has two parameters, the URL of the WSDL file and aQName
object. At runtime, the client gets information about the service by looking up its WSDL. In this example, the URL of the WSDL file points to the WSDL that was deployed withMyHelloService
:
http://localhost:8080/hello-jaxrpc/hello?WSDL
A
QName
object is a tuple that represents an XML qualified name. The tuple is composed of a namespace URI and the local part of the qualified name. In theQName
parameter of thecreateService
invocation, the local part is the service name,MyHelloService
.- The program creates a proxy (
myProxy
) with a type of the service endpoint interface (HelloIF
):d
ynamicproxy.HelloIF myProxy =
(dynamicproxy.HelloIF)helloService.getPort(
new QName(nameSpaceUri, portName),
dynamicproxy.HelloIF.class);The
helloService
object is a factory for dynamic proxies. To createmyProxy
, the program calls thegetPort
method ofhelloService
. This method has two parameters: aQName
object that specifies the port name and ajava.lang.Class
object for the service endpoint interface (HelloIF
). TheHelloIF
class is generated bywscompile
. The port name (HelloIFPort
) is specified by the WSDL file.Here is the listing for the
HelloClient.java
file, located in the<INSTALL>
/jwstutorial13/examples/jaxrpc/dynamicproxy/src/
directory:package dynamicproxy; import java.net.URL; import javax.xml.rpc.Service; import javax.xml.rpc.JAXRPCException; import javax.xml.namespace.QName; import javax.xml.rpc.ServiceFactory; import dynamicproxy.HelloIF; public class HelloClient { public static void main(String[] args) { try { String UrlString = args[0] + "?WSDL"; String nameSpaceUri = "urn:Foo"; String serviceName = "MyHelloService"; String portName = "HelloIFPort"; System.out.println("UrlString = " + UrlString); URL helloWsdlUrl = new URL(UrlString); ServiceFactory serviceFactory = ServiceFactory.newInstance(); Service helloService = serviceFactory.createService(helloWsdlUrl, new QName(nameSpaceUri, serviceName)); dynamicproxy.HelloIF myProxy = (dynamicproxy.HelloIF) helloService.getPort( new QName(nameSpaceUri, portName), dynamicproxy.HelloIF.class); System.out.println(myProxy.sayHello("Buzz")); } catch (Exception ex) { ex.printStackTrace(); } } }Building and Running the Dynamic Proxy Client
Before performing the steps in this section, you must first create and deploy
MyHelloService
as described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<INSTALL>
/jwstutorial13/examples/jaxrpc/dynamicproxy/
directory and type the following:The preceding command runs these tasks:
The
generate-interface
task runswscompile with the -import
option. Thewscompile
command reads theMyHelloService.wsdl
file and generates the service endpoint interface class (HelloIF.class
). Although thiswscompile
invocation also creates stubs, the dynamic proxy client does not use these stubs, which are required only by static stub clients.The c
ompile-client
task compiles thesrc/HelloClient.java
file.The
package-dynamic
task creates thedist/client.jar
file, which containsHelloIF.class
andHelloClient.class
.To run the client, type the following:
The client should display the following line:
Dynamic Invocation Interface (DII) Client Example
This example resides in the
<INSTALL>
/jwstutorial13/examples/jaxrpc/dii/
directory.With the dynamic invocation interface (DII), a client can call a remote procedure even if the signature of the remote procedure or the name of the service are unknown until runtime. In contrast to a static stub or dynamic proxy client, a DII client does not require runtime classes generated by wscompile. However, as you'll see in the following section, the source code for a DII client is more complicated than the code of the other two types of clients.
This example is for advanced users who are familiar with WSDL documents. (See Further Information.)
Coding the DII Client
The
DIIHello
program performs these steps:
- Creates a
Service
object.
Service service =
factory.createService(new QName(qnameService));To get a
Service
object, the program invokes thecreateService
method of aServiceFactory
object. The parameter of thecreateService
method is aQName
object that represents the name of the service,MyHelloService
. The WSDL file specifies this name as follows:
<service name="MyHelloService">
- From the
Service
object, creates aCall
object:
QName port = new QName(qnamePort);
Call call = service.createCall(port);A
Call
object supports the dynamic invocation of the remote procedures of a service. To get aCall
object, the program invokes theService
object'screateCall
method. The parameter ofcreateCall
is aQName
object that represents the service endpoint interface,MyHelloServiceRPC
. In the WSDL file, the name of this interface is designated by theportType
element:
<portType name="HelloIF">
- Sets the service endpoint address on the
Call
object:
call.setTargetEndpointAddress(endpoint);
In the WSDL file, this address is specified by the
<soap:address>
element.- Sets these properties on the
Call
object:
SOAPACTION_USE_PROPERTY
SOAPACTION_URI_PROPERTY
ENCODING_STYLE_PROPERTYTo learn more about these properties, refer to the SOAP and WSDL documents listed in Further Information.
- Specifies the method's return type, name, and parameter:
QName QNAME_TYPE_STRING = new QName(NS_XSD, "string");
call.setReturnType(QNAME_TYPE_STRING);
call.setOperationName(new QName(BODY_NAMESPACE_VALUE,
"sayHello"));
call.addParameter("String_1", QNAME_TYPE_STRING,
ParameterMode.IN);To specify the return type, the program invokes the
setReturnType
method on theCall
object. The parameter ofsetReturnType
is aQName
object that represents an XML string type.The program designates the method name by invoking the
setOperationName
method with aQName
object that representssayHello
.To indicate the method parameter, the program invokes the
addParameter
method on theCall
object. TheaddParameter
method has three arguments: aString
for the parameter name (String_1
), aQName
object for the XML type, and aParameterMode
object to indicate the passing mode of the parameter (IN
).- Invokes the remote method on the
Call
object:
String[] params = { "Murphy" };
String result = (String)call.invoke(params);The program assigns the parameter value (
Murphy
) to aString
array (params
) and then executes theinvoke
method with theString
array as an argument.Here is the listing for the
HelloClient.java
file, located in the<INSTALL>
/jwstutorial13/examples/jaxrpc/dii/src/
directory:package dii; import javax.xml.rpc.Call; import javax.xml.rpc.Service; import javax.xml.rpc.JAXRPCException; import javax.xml.namespace.QName; import javax.xml.rpc.ServiceFactory; import javax.xml.rpc.ParameterMode; public class HelloClient { private static String qnameService = "MyHelloService"; private static String qnamePort = "HelloIF"; private static String BODY_NAMESPACE_VALUE = "urn:Foo"; private static String ENCODING_STYLE_PROPERTY = "javax.xml.rpc.encodingstyle.namespace.uri"; private static String NS_XSD = "http://www.w3.org/2001/XMLSchema"; private static String URI_ENCODING = "http://schemas.xmlsoap.org/soap/encoding/"; public static void main(String[] args) { System.out.println("Endpoint address = " + args[0]); try { ServiceFactory factory = ServiceFactory.newInstance(); Service service = factory.createService( new QName(qnameService)); QName port = new QName(qnamePort); Call call = service.createCall(port); call.setTargetEndpointAddress(args[0]); call.setProperty(Call.SOAPACTION_USE_PROPERTY, new Boolean(true)); call.setProperty(Call.SOAPACTION_URI_PROPERTY ""); call.setProperty(ENCODING_STYLE_PROPERTY, URI_ENCODING); QName QNAME_TYPE_STRING = new QName(NS_XSD, "string"); call.setReturnType(QNAME_TYPE_STRING); call.setOperationName( new QName(BODY_NAMESPACE_VALUE,"sayHello")); call.addParameter("String_1", QNAME_TYPE_STRING, ParameterMode.IN); String[] params = { "Murph!" }; String result = (String)call.invoke(params); System.out.println(result); } catch (Exception ex) { ex.printStackTrace(); } } }Building and Running the DII Client
Before performing the steps in this section, you must first create and deploy
MyHelloService
as described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<INSTALL>
/jwstutorial13/examples/jaxrpc/dii/
directory and type the following:This
build
task compilesHelloClient
and packages it into thedist/client.jar
file. Unlike the previous client examples, the DII client does not require files generated bywscompile
.To run the client, type this command:
The client should display this line:
More JAX-RPC Client Examples
Other chapters in this book also have JAX-RPC client examples:
- Chapter 25 includes a static stub client in the Web tier. See the section, Coffee Break Server.
- Chapter 24 describes a static stub client that demonstrates authentication. See the section, Example: Basic Authentication with JAX-RPC.
- Chapter 19 shows how a JSP page can be a static stub client that accesses a remote Web service. See the section, The Example JSP Pages (page 768).
In this chapter, the section Advanced JAX-RPC Examples describes JAX-RPC clients with features such as SOAP message handlers and WS-I compliance.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.