Programming the JWS File to Enable MakeConnection

Invoking Web Services Asynchronously 3-21

3.6.1.2 Programming the JWS File to Enable MakeConnection

This section describes how to enable MakeConnection on the Web service using a pre-packaged or custom MakeConnection WS-Policy file. For information about creating a custom policy file, see Section 3.6.1.1, Creating the Web Service MakeConnection WS-Policy File Optional . Use the Policy annotation in your JWS file to specify that the Web service has a WS-Policy file attached to it that contains MakeConnection assertions. WebLogic Server delivers a set of pre-packaged WS-Policy files, as described in Appendix A, Pre-packaged WS-Policy Files for Web Services Reliable Messaging and MakeConnection . Refer to the following guidelines when using the Policy annotation for Web service reliable messaging: ■ You can attach the MakeConnection policy at the class level only; you cannot attach the MakeConnection policy at the method level. ■ Use the uri attribute to specify the build-time location of the policy file, as follows: – If you have created your own WS-Policy file, specify its location relative to the JWS file. For example: Policyuri=McPolicy.xml, attachToWsdl=true In this example, the McPolicy.xml file is located in the same directory as the JWS file. – To specify one of the pre-packaged WS-Policy files or a WS-Policy file that is packaged in a shared Java EE library, use the policy: prefix along with the name and path of the policy file. This syntax tells the jwsc Ant task at build-time not to look for an actual file on the file system, but rather, that the Web service will retrieve the WS-Policy file from WebLogic Server at the time the service is deployed. – To specify that the policy file is published on the Web, use the http: prefix along with the URL, as shown in the following example: Policyuri=http:someSite.compoliciesmypolicy.xml attachToWsdl=true ■ Set the attachToWsdl attribute of the Policy annotation to specify whether the policy file should be attached to the WSDL file that describes the public contract of the Web service. Typically, you want to publicly publish the policy so that client applications know the reliable messaging capabilities of the Web service. For this reason, the default value of this attribute is true. Note: Shared Java EE libraries are useful when you want to share a WS-Policy file with multiple Web services that are packaged in different Enterprise applications. As long as the WS-Policy file is located in the META-INFpolicies or WEB-INFpolicies directory of the shared Java EE library, you can specify the policy file in the same way as if it were packaged in the same archive at the Web service. See Creating Shared Java EE Libraries and Optional Packages in Developing Applications for Oracle WebLogic Server for information about creating libraries and setting up your environment so the Web service can locate the policy files. 3-22 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server For more information about the Policy annotation, see weblogic.jws.Policy in WebLogic Web Services Reference for Oracle WebLogic Server. The following example shows a simple JWS file that enables MakeConnection; see the explanation after the example for coding guidelines that correspond to the Java code in bold . package examples.webservices.async import javax.jws.WebMethod; import javax.jws.WebService; import weblogic.jws.Policy; Simple reliable Web Service. WebServicename=HelloWorldPortType, serviceName=HelloWorldService Policyuri=McPolicy.xml, attachToWsdl=true public class HelloWorldImpl { private static String onewaySavedInput = null; A one-way helloWorld method that saves the given string for later concatenation to the end of the message passed into helloWorldReturn. WebMethod public void helloWorldString input { System.out.println Hello World + input; onewaySavedInput = input; } This echo method concatenates the saved message from helloWorld onto the end of the provided message, and returns it. WebMethod public String echoString input2 { System.out.println Hello World + input2 + onewaySavedInput; return input + onewaySavedInput; } } As shown in the previous example, the custom McPolicy.xml policy file is attached to the Web service at the class level, which means that the policy file is applied to all public operations of the Web service. You can attach a MakeConnection policy at the class level only; you cannot attach a MakeConnection policy at the method level. The policy file is attached to the WSDL file. For information about the pre-packaged policies available and creating a custom policy, see Section 3.6.1.1, Creating the Web Service MakeConnection WS-Policy File Optional . The echo method has been marked with the WebMethod JWS annotation, which means it is a public operation called echo. Because of the Policy annotation, the operation using MakeConnection transport protocol. Invoking Web Services Asynchronously 3-23 3.6.2 Enabling and Configuring MakeConnection on a Web Service Client To enable MakeConnection on a Web service client, pass an instance of the weblogic.wsee.mc.api.McFeature as a parameter when creating the Web service proxy or dispatch. A simple example of how to enable MakeConnection is shown below. package examples.webservices.myservice.client; import weblogic.wsee.mc.api.McFeature; ... ListWebServiceFeature features = new ArrayListWebServiceFeature; ... McFeature mcFeature = new McFeature; features.addmcFeature; ... ... Implement asynchronous handler interface as described in Section 3.5.2, Developing the Asynchronous Handler Interface. .... AsyncClientHandlerFeature handlerFeature = new AsyncClientHandlerFeaturehandler; features.addhandlerFeature; _features = features.toArraynew WebServiceFeature[features.size]; BackendService port = _service.getBackendServicePort_features; ... Make the invocation. Our asynchronous handler implementation set into the AsyncClientHandlerFeature above receives the response. String request = Dance and sing; System.out.printlnInvoking DoSomething asynchronously with request: + request; anotherPort.doSomethingAsyncrequest; .. } } To configure specific features of MakeConnection on the Web service client, as described in the following sections. ■ Section 3.6.2.1, Configuring the Expiration Time for Sending MakeConnection Messages Note: The MakeConnection and asynchronous client transport features are mutually exclusive. If you attempt to enable both features on the same Web service client, an error is returned. For more information about asynchronous client transport, see Section 3.5, Developing Scalable Asynchronous JAX-WS Clients Asynchronous Client Transport . It is recommended that you use the asynchronous handler feature, AsyncClientHandlerFeature when using the asynchronous callback handler programming model. For more information, see Section 3.5.2, Developing the Asynchronous Handler Interface . Note: This example will use synchronous transport for synchronous methods. To configure MakeConnection as the transport for synchronous methods, see Section 3.6.2.4, Configuring MakeConnection as the Transport for Synchronous Methods. 3-24 Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server ■ Section 3.6.2.2, Configuring the Polling Interval ■ Section 3.6.2.3, Configuring the Exponential Backoff ■ Section 3.6.2.4, Configuring MakeConnection as the Transport for Synchronous Methods

3.6.2.1 Configuring the Expiration Time for Sending MakeConnection Messages