ways to invoke service

Invoking web services with Java clients

http://www.ibm.com/developerworks/webservices/library/ws-javaclient/index.html

 

Service access

In previous sections, you saw that a JAX-RPC ServiceFactory acts as a factory for JAX-RPC Services. Similarly, a JAX-RPC Service acts as a factory for proxies and stubs. Once you have instantiated a Service, there are three methods for accessing and invoking the web service:

1. Stub
2. Dynamic Proxy
3. Dynamic Invocation Interface (DII).

Stub and dynamic proxy methods use the Service Endpoint Interface (SEI). It is basically the Java representation of the web service operations described in the WSDL port type element. It is a Java interface defining methods used by the Java client to interact with the web service. The SEI is generated by a WSDL to Java mapping tool (such as Apache Axis' Java2WSDL or IBM WSDK's WSDL2Client).

SEI

A Service Endpoint Interface (SEI) is the Java representation of a WSDL port type.

Stub

The stub method uses a platform-specific stub created before runtime during the WSDL to Java mapping stage. Because the stub is created before runtime, it is sometimes called a static stub . It is a Java class implementing the SEI. A WSDL to Java mapping tool generates the client-side artifacts needed; basically, the tool imports the WSDL service definition and creates the corresponding Java code. The artifacts include an SEI, a Stub, and optionally holders, serializers, deserializers, and utility classes. JAX-RPC recommends an instance of a stub to be bound to a specific protocol and transport, such as a SOAP binding stub. For the stub method, the steps to perform are:

1. Get a JAX-RPC Service.
2. Obtain a stub.
3. Invoke the web service's operations on the stub.

Steps 2 and 3 are shown in Listing 4 . Note that it is also possible to use the JAX-RPC Service 's getPort method (described in the next section) to obtain a stub.

Listing 4. Accessing a web service through a stub

Hello myStub = (Hello) service.getHello(); System.out.println(myStub.getGreeting("Jane");

 

The advantage of this method is its simplicity. Basically, only two lines of code are required to access and invoke a web service's operation. However, you need to know the WSDL URL at development-time and run your WSDL to Java mapping tool. Also, these stubs are not portable because they depend on implementation classes and should not be packaged as part of an application. The design of portable stubs is out-of-scope for JAX-RPC 1.0 and 1.1.

Dynamic proxy

From a JAX-RPC Service , you can use a proxy to invoke the web service's operations. The proxy is a Java class implementing the SEI. A proxy is obtained with the JAX-RPC Service 's getPort() method, which takes the name of the port for the web service you want to invoke (found in the WSDL document), as well as the SEI implemented by the proxy. It is called dynamic because the proxy is created at runtime. The steps for dynamic proxy clients are:

1. Get a JAX-RPC Service .
2. Obtain a proxy using the JAX-RPC Service 's getPort() method in order to invoke the web service's operations.

In step 1, for unmanaged clients, a JAX-RPC Service is obtained from the JAX-RPC ServiceFactory by passing the WSDL URL as well as the web service name parameter to the createService() method. For J2EE container-managed clients, you get a JAX-RPC Service from JNDI lookup. Listing 5 shows the dynamic proxy method (step 2) to invoke the "getGreeting" operation on the web service.

Listing 5. Invoking a web Service's operation on a dynamic proxy

String namespace = "http://Hello.com"; String portName = "Hello"; QName portQN = new QName(namespace, portName); Hello myProxy = service.getPort(portQN, Hello.class); System.out.println(myProxy.getGreeting("Jane"));

 

This is all the code you need to write to invoke a web service using the dynamic proxy method. The advantage of using this method is that you write portable, vendor-independent code. However, you need to know the WSDL URL at development-time and you need to run your WSDL to Java mapping tool against the WSDL document before runtime. If you do not have this information, or if the WSDL URL is likely to change, you should use the DII method instead.

Dynamic Invocation Interface (DII)

The JAX-RPC Call interface supports the dynamic invocation of a web services' operations. With this method, you do not need to know the WSDL URL at development-time. Instead of obtaining a proxy from the JAX-RPC Service , the JAX-RPC Service acts as a factory for instantiating JAX-RPC Call s. The steps for this method are:

1. Get a JAX-RPC Service .
2. Instantiate a JAX-RPC Call using JAX-RPC Service 's createCall() method.
3. Configure your Call instance with its setter methods.
4. Invoke the web service's operation using the JAX-RPC Call's invoke method.

In step 1, for unmanaged clients, a JAX-RPC Service is obtained from the JAX-RPC ServiceFactory by passing only the name of the web service (not the WSDL URL) to the createService() method. For J2EE container-managed clients, you get a JAX-RPC Service from JNDI lookup. In step 3, configuration parameters are: name of the operation, port type, address of the target service endpoint, return type. Refer to section 8.2.4.2 of the JAX-RPC specification for the standard set of properties (see Resources ). Steps 2 to 4 are shown in Listing 6 .

Listing 6. Invoking a web service using the DII method

String namespace = "http://Hello.com"; String portName = "Hello"; QName portQN = new QName(namespace, portName); String operationName = "getGreeting"; Call call = service.createCall(); call.setPortTypeName(portQN); call.setOperationName(new QName(namespace, operationName)); call.setProperty(Call.ENCODINGSTYLE_URI_PROPERTY, ""); call.setProperty(Call.OPERATION_STYLE_PROPERTY, "wrapped"); call.addParameter("param1", <xsd:string>,ParameterMode.IN); call.setReturnType(<xsd:string>); Object[] inParams = new Object[] {"Jane"}; String ret = (String) call.invoke(inParams);

 

You can reuse the Call instance to invoke other operations on the web service.

Note: the createCall() and addParameter() methods have other signatures. What was just described is not the only way to invoke them. For example, it is possible to invoke createCall() with port type name and operation name parameters.

Making DII calls through a Call object is programmatically more complex than using a stub or dynamic proxy. However, the advantage of using a DII Call interface is that a client can call a remote procedure without development-time knowledge of the WSDL URI or the web service operations' signatures. This makes the code easy to modify if the web service details change. With DII clients, runtime classes generated by WSDL to Java mapping tools (emitters) are not required like the dynamic proxy or static stub cases. However, if you know the web service you want to invoke is unlikely to change, you should use dynamic proxy because configuring the Call instance can be complex.

---

Back to top

Dynamic Discovery and Invocation (DDI)

Dynamic Discovery and Invocation (DDI) is the ultimate use of web services' flexibility where a web service client can dynamically discover and invoke a web service without any prior knowledge of it. Although DII clients, described in the previous section , do not require development-time knowledge of a web service's details, they do not involve the process of discovering the web service. A DDI client performs three steps:

1. Discovers the web service's details from UDDI: finds the business providing the service and then the URL of the WSDL document describing the service
2. Reads the WSDL document to find information on the web service: namespace, service, ports, and parameters
3. Invokes the service.

In step 1, the UDDI Registry Enquiry API is used to browse the UDDI registry. In step 2, the UDDI4J API is used to parse the WSDL document. Finally, in step 3, the DII method (described in the previous section ) is used. For information on DDI you are encouraged to read the developerWorks article "Dynamic Discovery and Invocation of web services," listed in the Resources section.