Chapter 10. Create low-level SOAP web services
10.4. Use Dispatch API to create a dynamic web service client
Prev Chapter 10. Create low-level SOAP web services. Next
10.4. Use Dispatch API to create a dynamic web service client.
XML w eb services use XML messages for communicat ion bet w een services and service client s. T he higher level JAX-W S APIs are designed t o hide t he det ails of convert ing bet w een Java met hod invocat ions and t he corresponding XML messages, but in some cases operat ing at t he XML message level is desirable. T he javax.xml.ws.Dispatch int erface provides support for t his mode of int eract ion.
Dispatch support s t w o usage modes, ident ified by t he const ant s javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respect ively:
javax.xml.ws.Service.Mode.MESSAGE: In t his mode, client applicat ions w ork direct ly w it h prot ocol-specific message st ruct ures. E.g., w hen used w it h a SOA P prot ocol binding, a client applicat ion w ould w ork direct ly w it h a SOAP message.
javax.xml.ws.Service.Mode.PAYLOAD: In t his mode, client applicat ions w ork w it h t he payload of messages rat her t han t he messages t hemselves. E.g., w hen used w it h a SOAP prot ocol binding, a client applicat ion w ould w ork w it h t he cont ent s of t he SOAP Body rat her t han t he SOAP message as a w hole.
Dispatch is a low level A PI t hat requires client s t o const ruct messages or message payloads as XML and requires an int imat e know ledge of t he desired message or payload st ruct ure. Dispatch is a generic int erface t hat support s input and out put of messages or message payloads of any t ype. Implement at ions are required t o support t he follow ing t ypes of object :
javax.xml.transform.Source
Use of Source object s allow s client s t o use XML generat ing and consuming APIs direct ly. Source object s may be used w it h any prot ocol binding in eit her message or message payload mode. W hen used w it h t he HTT P binding in payload mode, t he HTT P request and response ent it y bodies must cont ain XML direct ly or a MIME w rapper w it h an XML root part . A null value for Source is allow ed t o make it possible t o invoke an HTT P GET met hod in t he HTT P Binding case. A
WebServiceException MUST be t hrow n w hen a Dispatch<Source> is invoked and t he Service ret urns a MIME message. W hen used in message mode, if t he message is not an XML message a WebServiceException MUST be t hrow n.
JAXB Object s
Use of JAXB allow s client s t o use JAXB object s generat ed from an XML Schema t o creat e and manipulat e XML represent at ions and t o use t hese object s w it h JAX-W S w it hout requiring an int ermediat e XML serializat ion. JAXB object s may be used w it h any prot ocol binding in eit her message or message payload mode. W hen used w it h t he HTT P binding in payload mode, t he HTT P request and response ent it y bodies must cont ain XML direct ly or a MIME w rapper w it h an XML root part . W hen used in mssage mode, if t he message is not an XML message a WebServiceException MUST be t hrow n.
Service provides a createDispatch fact ory met hod for creat ing Dispatch inst ances t hat cont ain an embedded JAXBContext. T he context paramet er cont ains t he JAXBContext inst ance t hat t he creat ed Dispatch inst ance w ill use t o marshall and unmarshall messages or message payloads.
javax.xml.soap.SOAPMessage
Use of SOAPMessage object s allow s client s t o w ork w it h SOAP messages using t he convenience feat ures provided by t he java.xml.soap package. SOAPMessage object s may only be used w it h Dispat ch inst ances t hat use t he SOAP binding in message mode.
javax.activation.DataSource
Use of DataSource object s allow s client s t o w ork w it h MIME-t yped messages. DataSource object s may only be used w it h Dispatch inst ances t hat use t he HTT P binding in message mode.
Dispatch inst ances are obt ained using t he createDispatch fact ory met hods of a Service inst ance. T he mode paramet er of createDispatch cont rols w het her t he new Dispatch inst ance is message or message payload orient ed. T he type paramet er cont rols t he t ype of object used for messages or message payloads. Dispatch inst ances are not t hread safe.
Dispatch inst ances are not required t o be dynamically configurable for different prot ocol bindings; t he W SDL binding from w hich t he Dispatch inst ance is generat ed cont ains st at ic informat ion including t he prot ocol binding and service endpoint address. How ever, a Dispatch inst ance may support configurat ion of cert ain aspect s of it s operat ion and provides met hods (inherit ed from BindingProvider) t o dynamically query and change t he values of propert ies in it s request and response cont ext s.
A Dispatch inst ance support s t hree invocat ion modes:
Synchronous request response (invoke met hods)
T he met hod blocks unt il t he remot e operat ion complet es and t he result s are ret urned.
Asynchronous request response (invokeAsync met hods)
T he met hod ret urns immediat ely, any result s are provided eit her t hrough a callback or via a polling object . One-w ay (invokeOneWay met hods)
T he met hod is logically non-blocking, subject t o t he capabilit ies of t he underlying prot ocol, no result s are ret urned.
Dispatch support s t w o forms of asynchronous invocat ion:
Polling
T he invokeAsync met hod ret urns a Response t hat may be polled using t he met hods inherit ed from Future<T> t o det ermine w hen t he operat ion has complet ed and t o ret rieve t he result s.
Callback
T he client supplies an AsyncHandler and t he runt ime calls t he handleResponse met hod w hen t he result s of t he operat ion are available. T he invokeAsync met hod ret urns a w ildcard Future (Future<?>) t hat may be polled t o det ermine w hen t he operat ion has complet ed. T he object ret urned from Future<?>.get() has no st andard t ype. Client code should not at t empt t o cast t he object t o any part icular t ype as t his w ill result in non-port able behavior.
T he follow ing int erfaces are used t o obt ain t he result s of an operat ion invocat ion:
javax.xml.ws.Response
A generic int erface t hat is used t o group t he result s of an invocat ion w it h t he response cont ext . Response ext ends java.util.concurrent.Future<T> t o provide asynchronous result polling capabilit ies.
javax.xml.ws.AsyncHandler
A generic int erface t hat client s implement t o receive result s in an asynchronous callback. It defines a single handleResponse met hod t hat has a Response object as it s argument .
T he follow ing examples demonst rat e use of Dispatch met hods in t he synchronous, asynchronous polling, and asynchronous callback modes:
Synchronous, Payload-Orient ed:
Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
Source resMsg = disp.invoke(reqMsg);
Synchronous, Message-Orient ed:
SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
SOAPMessage soapResMsg = disp.invoke(soapReqMsg);
Synchronous, Payload-Orient ed W it h JAXB Object s:
JAXBContext jc = JAXBContext.newInstance("primer.po");
Unmarshaller u = jc.createUnmarshaller();
PurchaseOrder po = (PurchaseOrder)u.unmarshal(new FileInputStream("po.xml"));
Service service = ...;
Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD);
OrderConfirmation conf = (OrderConfirmation)disp.invoke(po);
In t he above example PurchaseOrder and OrderConfirmation are int erfaces pre-generat ed by JAXB from t he schema document 'primer.po'.
Asynchronous, Polling, Message-Orient ed:
SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName, SOAPMessage.class, MESSAGE);
Response<SOAPMessage> res = disp.invokeAsync(soapReqMsg);
while (!res.isDone()) {
// do something while we wait }
SOAPMessage soapResMsg = res.get();
Asynchronous, Callback, Payload-Orient ed:
class MyHandler implements AsyncHandler<Source> { ...
public void handleResponse(Response<Source> res) { Source resMsg = res.get();
// do something with the results }
}
Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName, Source.class, PAYLOAD);
MyHandler handler = new MyHandler();
disp.invokeAsync(reqMsg, handler);
Configuring t he client BindingProviders
Bot h proxy-based client s and dispat ch-based client s share a common configurat ion model. T he configurat ion is performed programmat ically in t he cont ext of t he Java w eb service client code. By using t his configurat ion, you can specify an explicit endpoint locat ion, HTT P prot ocol session behavior, HTT P aut hent icat ion credent ials, and more.
T he act ual programmat ic configurat ion is performed on t he javax.xml.ws.BindingProvider client -side object . T he dynamic proxies t hat are generat ed by t he JAX-W S run t ime implement t he javax.xml.ws.BindingProvider int erface, w here t he Dispatch int erface ext ends it . T herefore, dispat ch object s produced by t he JAX-W S Service class, by cont ract , also implement t he BindingProvider behavior.
To configure t he client BindingProvider, you add informat ion t o t he request cont ext , w hich is an ordinary java.util.Map<String, Object> t hat cont ains t he act ual configurat ion. T he keys are st rings and t he values are object s. T he map is available by using t he BindingProvider.getRequestContext() met hod.
JAX-W S 2.1 specifies t he follow ing st andard propert ies t hat can be used t o configure t he request cont ext : javax.xml.ws.service.endpoint.adress (value t ype: String)
Specifies t he w eb service endpoint address.
javax.xml.ws.security.auth.username (value t ype: String)
Specifies t he user name in a set of HTT P basic aut hent icat ion credent ials.
javax.xml.ws.security.auth.password (value t ype: String) Specifies t he passw ord in a set of HTT P basic aut hent icat ion credent ials.
javax.xml.ws.session.maintain (value t ype: Boolean, default : false) Specifies w het her t he client is w illing t o part icipat e in a server-init iat ed session.
Example below show s how t o allow t he w eb service client t o part icipat e in w eb service endpoint init iat ed sessions:
import java.util.Map;
import by.boot.java.HelloMessenger;
import by.boot.java.HelloMessengerService;
import javax.xml.ws.BindingProvider;
public class HelloClientHttpSession {
public static void main(String... args) throws Exception { // Obtain the dynamic stub from the Service
HelloMessengerService service = new HelloMessengerService();
HelloMessenger proxy = service.getHelloMessengerPort();
// Cast the proxy to a BindingProvider
BindingProvider bindingProvider = (BindingProvider) proxy;
// Get the request context
Map<String, Object> requestContext = bindingProvider.getRequestContext();
// Configure session preference
requestContext.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);
// Perform Web service method invocation and print the result String message = proxy.sayHello("Mikalai");
System.out.println(message);
} }
Prev Up Next
10.3. Use Provider API to create a web service. Home Chapter 11. Use MTOM and MIME in a SOAP web service.
Host ing provided by PerfoHost: KVM VPS provider. See PefoHost 's KVM VPS vs OpenVZ/Virt uozzo vs XEN VPS comparat ive chart . CRM-export er: Vehicle Dat abase Script 1999-2011