Building the Client Artifacts for Asynchronous Web Service Invocation

Invoking Web Services Asynchronously 3-7

3.4 Building the Client Artifacts for Asynchronous Web Service Invocation

Using the WebLogic Server client-side tooling for example, clientgen, you can generate automatically the client artifacts required for asynchronous Web service invocation. Specifically, the following artifacts are generated: ■ Service endpoint interfaces for invoking the Web service asynchronously with or without a per-request asynchronous callback handler. For example, if the Web service defined the following method: public int addNumbersint opA, int opB throws MyException Then the following methods will be generated: public Future? addNumbersAsyncint opA, int opB, AsyncHandlerAddNumbersResponse public ResponseAddNumbersResponse addNumbersAsyncint opA, int opB ■ Asynchronous handler interface for implementing a handler and setting it on the port using AsyncClientHandlerFeature. The asynchronous handler interface is named as follows: portInterfaceNameAsyncHandler, where portInterfaceName specifies the name of the port interface. For example, for a Web service with a port type name AddNumbersPortType, an asynchronous handler interface named AddNumbersPortTypeAsyncHandler is generated with the following method: public void onAddNumbersResponseResponseAddNumbersResponse The AsyncClientHandlerFeature is described later, in Section 3.5.2, Developing the Asynchronous Handler Interface . To generate asynchronous client artifacts in the service endpoint interface when the WSDL is compiled, enable the jaxws:enableAsyncMapping binding declaration in the WSDL file. Alternatively, you can create an external binding declarations file that contains all binding declarations for a specific WSDL or XML Schema document. Then, pass the binding declarations file to the binding child element of the wsdlc, jwsc, or clientgen Ant task. For more information, see Creating an External Binding Declarations File Using JAX-WS Binding Declarations in Getting Started With JAX-WS Web Services for Oracle WebLogic Server. The following provides an example of a binding declarations file jaxws-binding.xml that enables the jaxws:enableAsyncMapping binding declaration: Message buffering When a buffered operation is invoked by a client, the request is stored in a JMS queue and WebLogic Server processes it asynchronously. If WebLogic Server goes down while the request is still in the queue, it will be processed as soon as WebLogic Server is restarted. Message buffering is configured on the server hosting the Web service. For configuration information, see Chapter 7, Configuring Message Buffering for Web Services . Note : Message buffering is enabled automatically on the Web service client. Table 3–4 Cont. Configuration for Asynchronous Web Service Invocation Feature Description 3-8 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server bindings xmlns:xsd=http:www.w3.org2001XMLSchema xmlns:wsdl=http:schemas.xmlsoap.orgwsdl wsdlLocation=AddNumbers.wsdl xmlns=http:java.sun.comxmlnsjaxws bindings node=wsdl:definitions package name=examples.webservices.async enableAsyncMappingtrueenableAsyncMapping bindings bindings Then, to update the build.xml file to generate client artifacts necessary to invoke a Web service operation asynchronously: 1. Use the taskdef Ant task to define the full classname of the clientgen Ant tasks. 2. Add a target that includes a reference to the external binding declarations file containing the asynchronous binding declaration, as defined above. In this case, the clientgen Ant task generates both synchronous and asynchronous flavors of the Web service operations in the JAX-WS stubs. For example: taskdef name=clientgen classname=weblogic.wsee.tools.anttasks.ClientGenTask target name=build_client clientgen type=JAXWS wsdl=AddNumbers.wsdl destDir={clientclasses.dir} packageName=examples.webservices.async.client binding file=jaxws-binding.xml clientgen javac srcdir={clientclass-dir} destdir={clientclass-dir} includes=.java javac srcdir=src destdir={clientclass-dir} includes=exampleswebservicesasyncclient.java target

3.5 Developing Scalable Asynchronous JAX-WS Clients Asynchronous Client Transport