4 Introduction to Developing Asynchronous Web Services

An introduction of asynchronous web service concepts and a description of how to develop and configure asynchronous web services is detailed in this chapter.

It includes the following topics:

4.1 Understanding Asynchronous Web Services

A client can continue its processing, without interruption by calling a web service asynchronously.

When you invoke a web service synchronously, the invoking client application waits for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the web service might be adequate. However, because request processing can be delayed, it is often useful for the client application to continue its work and handle the response later on. By calling a web service asynchronously, the client can continue its processing, without interrupt, and will be notified when the asynchronous response is returned.

The following sections step through several asynchronous message flow diagrams, provide the perspective from the client-side, and explain how asynchronous messages are correlated:

4.1.1 Understanding the Flow of an Asynchronous Web Service Using a Single Request Queue

In an asynchronous web service using a single request queue there is a single message-driven bean (MDB) associated with the request queue that handles both the request and response processing.

Note:

Although the single request queue scenario may provide better performance, it is less reliable than the request and response queue scenario. Oracle recommends that you use the request and response queue scenario, described in Understanding the Flow of an Asynchronous Web Service Using a Request and a Response Queue, and not the single request queue scenario.

The following diagram illustrates the flow of an asynchronous web service using a single request queue. In this scenario, there is a single message-driven bean (MDB) associated with the request queue that handles both the request and response processing.

Figure 4-1 Asynchronous Web Service Using a Single Request Queue

Description of Figure 4-1 follows
Description of "Figure 4-1 Asynchronous Web Service Using a Single Request Queue"

The following steps describe the flow shown in the previous figure:

  1. The client calls an asynchronous method.

  2. The asynchronous web services receives the request and stores it in the request queue.

  3. The asynchronous web service sends a receipt confirmation to the client.

  4. The MDB listener on the request queue receives the message and initiates processing of the request.

  5. The request MDB calls the required method in the web service implementation.

  6. The web service implementation returns the response.

  7. The request MDB, acting as a callback client, returns the response to the callback service.

  8. The callback service returns a receipt confirmation message.

  9. The request MDB returns a confirmation message to the request queue to terminate the process.

In this scenario, if there is a problem connecting to the callback service (in Step 7), then the response will not be sent. If the request is retried later, the flow resumes from Step 4 and the web service implementation will be called again (in Step 5). This may not be desirable depending on your application logic or transactional control processing. In the next scenario, the response is stored in a separate response queue, eliminating the need to recall the web service implementation in the event that the callback service is not available initially.

4.1.2 Understanding the Flow of an Asynchronous Web Service Using a Request and a Response Queue

Use of two MDBs provide improved error recovery over the single queue model.

The following diagram illustrates the flow of an asynchronous method call using a single request queue. In this scenario, there are two MDBs, one to handle the request processing and one to handle the response processing. By separating the execution of business logic from the response return, this scenario provides improved error recovery over the single queue model described in Understanding the Flow of an Asynchronous Web Service Using a Single Request Queue.

Figure 4-2 Asynchronous Web Service Using a Request and Response Queue

Description of Figure 4-2 follows
Description of "Figure 4-2 Asynchronous Web Service Using a Request and Response Queue"

The following steps describe the flow shown in the previous figure:

  1. The client calls an asynchronous method.

  2. The asynchronous web services receives the request and stores it in the request queue.

  3. The asynchronous web service sends a receipt confirmation to the client.

  4. The MDB listener on the request queue receives the message and initiates processing of the request.

  5. The request MDB calls the required method in the web service implementation.

  6. The web service implementation returns the response.

  7. The request MDB saves the response to the response queue.

  8. The request MDB sends a confirmation to the request queue to terminate the process.

  9. The onMessage listener on the response queue initiates processing of the response.

  10. The response MDB, acting as the callback client, returns the response to the callback service.

  11. The callback service returns a receipt confirmation message.

  12. The response MDB returns a confirmation message to the response queue to terminate the sequence.

4.1.3 Understanding the Client Perspective of an Asynchronous Web Service Call

Before initiating the asynchronous call, the client must deploy a callback service to listen for the response from the asynchronous web service.

The following diagram illustrates the flow, from the client perspective, of the asynchronous method call consisting of two one-way message exchanges.

Figure 4-3 Asynchronous Web Service Client Flow

Description of Figure 4-3 follows
Description of "Figure 4-3 Asynchronous Web Service Client Flow"

As shown in the previous figure, before initiating the asynchronous call, the client must deploy a callback service to listen for the response from the asynchronous web service.

The following steps describe the message flow shown in the previous figure:

  1. The client calls an asynchronous method.

  2. The asynchronous web services receives the request, sends a confirmation message to the initiating client, and starts process the request.

  3. Once processing of the request is complete, the asynchronous web service acts as a client to send the response back to the callback service.

  4. The callback service sends a confirmation message to the asynchronous web service.

4.1.4 Understanding How Asynchronous Messages Are Correlated

When the callback service receives a response, it needs a way to correlate the response back to the original request. This is achieved using WS-Addressing and is handled automatically by the runtime.

Note:

Message correlation is handled automatically by the runtime. This section is for informational purposes only.

The client sets the following two fields in the WS-Addressing part of the SOAP header:

  • ReplyTo address—Address of the callback service.

  • MessageID—Unique ID that identifies the request. For example, a UUID.

The callback client sends the MessageId corresponding to the initial request in the relatesToId field in the WS-Addressing header. If additional data is required by the callback service to process the response, clients can perform one of the following tasks:

  • Clients can send the data as a reference parameter in the ReplyTo field. Asynchronous web services return all reference parameters with the response, so the callback service will be able to access the information.

  • If sending the data as part of the asynchronous request message is not practical, then the client can save the MessageID and data required to the local data store.

4.2 About Using JDeveloper to Develop and Deploy Asynchronous Web Services

You can develop and deploy asynchronous web service methods for an ADF Business Component quickly and easily by using JDeveloper.

For complete details of development and deployment of asynchronous web service methods, see "How to Generate Asynchronous Web Service Methods" in Developer's Guide for Oracle Application Development Framework.

The following sections describe in more detail how an asynchronous web service is implemented. In some cases, the information is provided for informational purposes only.

4.3 Annotation to Develop an Asynchronous Web Service

You can use annotations to develop an asynchronous web service.

A JAX-WS web service can be declared an asynchronous web service using the following annotation: oracle.webservices.annotations.async.AsyncWebService.

The following provides a very simple POJO example of an asynchronous web service:

import oracle.webservices.annotations.PortableWebService
import oracle.webservices.annotations.async.AsyncWebService

@PortableWebService
@AsyncWebService
public class HelloService {
    public String hello(String name) {
        return "Hi " + name;
    }
}

The generated WSDL for the asynchronous web service contains two one-way operations defined as two portTypes: one for the asynchronous operation and one for the callback operation.

For example:

<wsdl:portType name="HelloService">
    <wsdl:operation name="hello">
        <wsdl:input message="tns:helloInput" 
               xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
               ns1:Action=""/>
    </wsdl:operation>
</wsdl:portType>
<wsdl:portType name="HelloServiceResponse">
    <wsdl:operation name="helloResponse">
        <wsdl:input message="tns:helloOutput" 
               xmlns:ns1="http://www.w3.org/2006/05/addressing/wsdl"
               ns1:Action=""/>
    </wsdl:operation>
</wsdl:portType>

Optionally, you can define a system user to secure access to the asynchronous web service using the systemUser argument. If not specified, this value defaults to OracleSystemUser.

For example:

@AsyncWebService(systemUser="ABCIncSystemUser')

By default, all operations associated with the web service are asynchronous. To mark a specific method as synchronous, use the @CalbackMethod annotation, as described in Annotation to Configure the Callback Service. If you want to be able to call a method both synchronously and asynchronously, you will have to create two methods and annotate them accordingly.

For more information about that @AsyncWebService and @PortableWebService annotation, see Java API Reference for Oracle Infrastructure Web Services.

For more information about securing the request and response queues used by asynchronous web services, Securing the Request and Response Queues.

4.4 Creating the Request and Response Queues

You must create and secure the queues used to store the request and response before you deploy your asynchronous web services.

The process of creating and securing the queues is described in the following sections:

4.4.1 Using the Default WebLogic JMS Queues

The process for using the default WebLogic JMS queues varies, based on whether you are using a clustered or non-clustered domain.

This section includes the following topics:

4.4.1.1 Default WebLogic JMS Queues in Clustered Domains

For clustered domains, you must create two JMS Uniform Distributed Destinations (UDDs) per cluster. An offline WLST script is provided to assist you in adding the default queues to your clustered environment.

The script is available at the following location:

<MW_HOME>/oracle_common/webservices/bin/jrfws-async-createUDDs.py

The following provides an example of how you might execute this script:

java -classpath <some_path>/weblogic.jar weblogic.WLST ./jrfws-async-createUDDs.py --domain_home <domain> --cluster <cluster>

4.4.1.2 Default WebLogic JMS Queues in Non-clustered Domains

For non-clustered domains, a pair of default WebLogic JMS queues are provided as part of the following WebLogic domain extension template: oracle.jrf.ws.async_template_11.1.1.jar. The default JMS queues included in the extension template include:

  • Request queue: oracle.j2ee.ws.server.async.DefaultRequestQueue

  • Response queue: oracle.j2ee.ws.server.async.DefaultResponseQueue

The default JMS connection factory, weblogic.jms.XAConnectionFactory, provided as part of the base domain, is used by default.

To create the required default queues, when creating or extending your domain using the Fusion Middleware Configuration Wizard, select Oracle JRF Web Services Asynchronous services. For more information, see Creating a WebLogic Domain in the Graphical ModeCreating WebLogic Domains Using the Configuration Wizard.

Note:

When using this domain extension template, ensure that you explicitly target the JMS module (JRFWSAsyncJmsModule) to non-clustered one or more servers in your domain, as required.

4.4.1.3 Tuning the Default JMS Delivery Failure Parameters

The following default values are configured for the JMS delivery failure parameters. It is recommended that you review the settings and modify them, as appropriate, for your environment. Configuration related to JMS delivery failure parameters can be modified using the WebLogic Server Administration Console, as described in Main Steps for Configuring Basic JMS System Resources in Administering JMS Resources for Oracle WebLogic Server.

  • Set the Redelivery Delay Override value to 900000 milliseconds. That is, wait 15 minutes before rolled back or recovered messages are redelivered, regardless of the redelivery delay specified by the message consumer or the connection factory.

  • Set the Redelivery Limit value to 100. This value specifies the number of redelivery attempts allowed before a message is moved to the Error Destination defined for the queues.

  • Set the Expiration Policy value to Redirect. This moves expired messages from their current location to the Error Destination defined for the queues. If enabled, verify that the corresponding Error Destination has been configured.

4.4.2 Creating Custom Request and Response Queues

You have to customize the request and response queues, if the default WebLogic JMS queues do not meet your requirements. Follow these steps to customize your request and response queues:

  1. Create the request and response queues manually, as described in Create a JMS Queue or Topic.
  2. Add them to your application code using the following annotations:

    • Request queue: oracle.webservices.annotations.async.AsyncWebServiceQueue

      For example:

      @AsyncWebServiceQueue (
    connectionFactory = "weblogic.jms.XAConnectionFactory",
    queue = "oracle.j2ee.ws.server.async.NonDefaultRequestQueue",
    enableTransaction = true
    transactionTimeout=3600
)

      For more information about the @AsyncWebServiceQueue, see Java API Reference for Oracle Infrastructure Web Services.

    • Response queue: oracle.webservices.annotations.async.AsycnWebServiceResponseQueue

      For example:

      @AsyncWebServiceResponseQueue (
    connectionFactory = "weblogic.jms.XAConnectionFactory",
    queue = "oracle.j2ee.ws.server.async.NonDefaultResponseQueue",
    enableTransaction = true
)

      For more information about @AsyncWebServiceResponseQueue, see Java API Reference for Oracle Infrastructure Web Services.

4.4.3 About Custom Request and Response Queues

You have to customize the request and response queues, if the default WebLogic JMS queues do not meet your requirements.

Asynchronous requests are initially saved in the request JMS queue for asynchronous execution. A Message-driven Bean (MDB) accesses the requests from the queue and executes the business logic.

To process many requests simultaneously, application servers create a pool of MDB instances, which can be configured based on the requirements of the application. The more MDB instances in a pool, the better the throughput. However, more resources, such as threads and database connections, will be used. The exact resource requirements are dependent on the type of persistence store used for saving the asynchronous request messages.

By default WebLogic Server initializes the pool with only one MDB instance and continues to increase the pool size, up to 16, as more requests are queued for execution. Once the maximum pool size is reached, no additional MDB instances are added, and the server waits for the existing MDB instances to complete the currently executing requests.

Users can configure the initial pool size and maximum pool size based on the application requirements. It is recommended that you use the default values, and adjust them based on the resource load observed. If the pool consumes too many resources, the maximum pool size can be reduced. If there are ample resources in the system and too many requests that are waiting in the queue, the maximum pool size can be increased.

4.4.4 Best Practices for Creating the Custom Request and Response Queues

A Message-driven Bean (MDB) accesses the requests from JMS queue for the execution of Asynchronous requests.

The following list provides the best practices for creating the custom request and response queues (Step 1 in "Creating Custom Request and Response Queues"):

  • Configure queues in a cluster for high availability and failover.

  • Configure a single JMS Server and WebLogic persistence store for each WebLogic Server and target them to the server's default migratable target.

  • For the JMS Server, configure quotas, as required.

    To prevent out-of-memory errors, it is recommended that you configure the maximum messages quota for each JMS Server. As a guide, each message header consumes approximately 512 bytes. Therefore, a maximum quota of 500,000 message will require approximately 250MB of memory. Consider the memory resources available in your environment and set this quota accordingly.

  • Configure a single JMS system module and target it to a cluster.

  • For the JMS system module, configure the following:

    • Single subdeployment and populate it with each JMS Server.

    • Required uniform distributed destination(s) and define targets using advanced subdeployment targeting (defined above).

    • Custom connection factory. If transactions are enabled, the connection factory must support transactions, if enabled. By default, WebLogic JMS provides the weblogic.jms.XAConnectionFactory connection factory to support transactions.

4.4.5 Modify Request and Response Queues at Runtime

You can modify the request and response queues at runtime using Fusion Middleware Control.

For complete details, see "Configuring Asynchronous Web Services" in Administering Web Services.

4.4.6 Securing the Request and Response Queues

Oracle recommends that you secure the JMS request and response queues with a user- or role-based security policy to secure access to these resources.

Note:

This section applies to ADF web services only. It does not apply to SOA web services.

The steps to secure the JMS request and response queues include:

  1. Optionally, configure the JMS System User, as described in About Configuring a Custom JMS System User (Optional).

    By default, the JMS System User that is authorized to access the JMS queues is set as OracleSystemUser. In most cases, the default user is sufficient.

  2. Run the WLST script to secure the request and response queues, as described in About the WLST Script for Securing the Request and Response Queues.

4.4.6.1 About Configuring a Custom JMS System User (Optional)

By default, the JMS System User that is authorized to access the JMS queues is set as OracleSystemUser. In most cases, this default value is sufficient. However, if you need to change this value to a custom user in your security realm, you can specify a custom system user using the systemUser attribute of the @AsyncWebService annotation.

For example:

@AsyncWebService(systemUser = "ABCIncSystemUser")

In order for this change to take effect, you need to regenerate the application EAR file using JDeveloper or the ojdeploy command line utility. For more information about that @AsyncWebService annotation, see Java API Reference for Oracle Infrastructure Web Services.

After your application has been deployed, you can change the JMS System User in Fusion Middleware Control and in the WebLogic Server Administration Console as described in "Changing the JMS System User for Asynchronous Web Services" in Administering Web Services.

4.4.6.2 About the WLST Script for Securing the Request and Response Queues

An online WLST script is provided to assist you in securing the request and response queues. You pass the JMS system module name that you want to secure and the security role to be assigned, in addition to the Administration Server connection details (URL, username, and password).

The script is available at the following location:

<MW_HOME>/oracle_common/webservices/bin/secure_jms_system_resource.py

The following provides an example of how you might execute this script:

java -classpath <some_path>/weblogic.jar weblogic.WLST ./secure_jms_system_resource.py 
 --username <AdminUserName> --password <AdminPassword> --url <AdminServer_t3_url>
 --jmsSystemResource <JMSSystemResourceName> --role <SecurityRoleToUse>

4.4.7 Confirming the Request and Response Queue Configuration

You have to configure the requests and response queues to meet the requirements.

To confirm that the request and response queues have been configured as required, perform one of the following tasks:

  1. Invoke the Administration Console, as described in “Invoking the Administration Console" in Understanding WebLogic Web Services for Oracle WebLogic Server.

  2. Verify that the following JMS resources are defined and available under Services > Messaging:

    • JMS server named JRFWSAsyncJmsServer.

      Ensure that the JMS module is targeted to one or more servers, as required, for a non-clustered domain (standard queues) or to the cluster for clustered domains (UDDs). The JMS Server is targeted appropriately when configuring the domain using the Configuration Wizard or WLST. See also Using the Default WebLogic JMS Queues.

    • JMS module named JRFWSAsyncJmsModule.

    • Request queue with JDNI name oracle.j2ee.ws.server.async.DefaultRequestQueue and a corresponding error queue.

    • Response queue with JDNI name oracle.j2ee.ws.server.async.DefaultResponseQueue and a corresponding error queue.

  3. Ensure that the asynchronous web service is deployed and verify that the system message-driven beans (MDBs) are connected to the JMS destination(s), as required, as follows:

    1. Click Deployments.

    2. Expand the application in the Deployments table.

    3. Under EJBs, verify that there are two system MDBs per web service to support the asynchronous web service runtime. For example, <asyncwebservicename>_AsyncRequestProcessorMDB and <asyncwebservicename>_AsyncResponseProcessorMDB.

    4. Verify that each MDB displayed is connected to the JMS destination.

    5. Select the EJB and click the Monitoring tab and then the Running tab.

    6. Verify that the Connection Status field is Connected.

    7. If the queues were not created correctly, perform one of the following:

      Create and configure the required JMS queues manually. For more information, see "Messaging" in .

      or

      Remove the JMS server, JMS module, and the default queues that were created for asynchronous web service and recreate them using the steps provided for clustered and non-clustered domains, as described in Using the Default WebLogic JMS Queues.

      Note:

      JMS resources are stored in the config.xml file for the domain.

4.5 Annotation to Configure the Callback Service

You can use the annotations defined in the following table to customize characteristics for the callback service (portType). The annotations are included in the oracle.webservices.annotations.async package.

Table 4-1 Annotations Used to Configure the Callback Service'

Annotation Description

@CallbackMethod

Customize the names of the WSDL entities for the corresponding operation in the callback portType and set whether a method is synchronous or asynchronous.

For example:

@CallbackMethod(exclude=true)

@CallbackProperties

Specify a set of properties that are required in the message context when calling the callback service.

For example:

@CallbackProperties( 
   {
   @Property(
       key = SecurityConstants.ClientConstants.WSS_CSF_KEY,
        value = "basic.credentials")
   }
)

@Property

Specify a property that is required in the message context when calling the callback service.

For example:

@CallbackProperties( 
   {
   @Property(
       key = SecurityConstants.ClientConstants.WSS_CSF_KEY,
        value = "basic.credentials")
   }
)

@ResponseWebService

Customize the response web service port information.

@Retry

Specify whether the asynchronous method is idempotent, or retriable, in the event that its execution is terminated abnormally (for example, due to system failure).

By default, all asynchronous methods are idempotent; this implies that there are no side effects of calling the asynchronous method more than once. If an asynchronous method is not idempotent, you should explicitly set this annotation with the enable attribute set to false.

4.6 Configuring SSL for Asynchronous Web Services

There are several tasks that you must perform to configure SSL for asynchronous web services.

The tasks required to be performed are as follows:

  1. Create the identity and trust keystores using the keytool.

    See "Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities" in Administering Security for Oracle WebLogic Server 12c (12.2.1).

  2. Configure the keystore, keystore type, and password for the identity and trust keystores using Oracle WebLogic Server Administration Console.

    See "Configure Keystores" in Oracle WebLogic Server Administration Console Online Help.

  3. Configure the password for the identity and trust keystores in the OWSM Credential store provider using Fusion Middleware Control.

    See "Configuring the Credential Store" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

    Ensure that the map with the name oracle.ws.async.ssl.security exists. If it does not exist, you must create it.

    Then, create the three key entries as listed below:

    • trust-keystore-password with user name async and password <trust_store_password>

    • identity-keystore-password with user name async and password <identity_store_password>

    • key-password with user name async and password <key_password>

4.7 Defining Asynchronous Web Service Clients

Two types of clients which can call asynchronous web services are SOA/BPEL clients and WebLogic Java EE JAX-WS Clients.

  • SOA/BPEL clients—The process is identical to that of calling other asynchronous BPEL clients. For more information, see "Invoking an Asynchronous Web Service form a BPEL Process" in Developing SOA Applications with Oracle SOA Suite.

  • WebLogic Java EE JAX-WS Clients—Using the Create Web Service Proxy wizard in JDeveloper, select the Generate As Async option to generate an asynchronous proxy. For more information about creating web service clients using the wizard, see "Creating Web Service Clients" in the Developing Applications with Oracle JDeveloper.

The following sections step through an example asynchronous client and callback service that is generated and describes the updates that need to be implemented.

Note:

The steps described in the following sections are applicable for WebLogic Java EE JAX-WS clients, and not SOA/BPEL clients.

4.7.1 Asynchronous Client Code

You can use a client code to support asynchronous web services.

The following example provides a sample of the client code that is generated to support asynchronous web services. As shown in bold, the client code must set two fields in the outbound header to correlate the asynchronous messages:

  • ReplyTo address—Address of the callback service.

  • MessageID—Unique ID that identifies the request. For example, a UUID.

The client code that is generated provides a UUID for the message ID that is sufficient in most cases, though you may wish to update it. You need to update the ReplyTo address to point to the callback service.

package async.jrf;
 
import com.sun.xml.ws.api.addressing.AddressingVersion;
import com.sun.xml.ws.api.addressing.WSEndpointReference;
import com.sun.xml.ws.developer.WSBindingProvider;
import com.sun.xml.ws.message.StringHeader;
import java.util.UUID;
 
// !THE CHANGES MADE TO THIS FILE WILL BE DESTROYED IF REGENERATED!
// This source file is generated by Oracle tools
// Contents may be subject to change
 
// For reporting problems, use the following
// Version = Oracle WebServices (11.1.1.0.0, build 090303.0200.48673)
 
public class HelloServicePortClient
{
  private static HelloServiceService helloServiceService;
  private static final AddressingVersion WS_ADDR_VER = AddressingVersion.W3C;

  public static void main(String [] args)
  {
    helloServiceService = new HelloServiceService();
    HelloService helloService = helloServiceService.getHelloServicePort();
    // Get the request context to set the outgoing addressing properties
    WSBindingProvider wsbp = (WSBindingProvider)helloService;
    WSEndpointReference repl
         new WSEndpointReference(
             "http://<replace with the URL of the callback service>",
               WS_ADDR_VER);
    String uuid = "uuid:" + UUID.randomUUID();
   wsbp.setOutboundHeaders(
               new StringHeader(WS_ADDR_VER.messageIDTag, uuid), 
               replyTo.createHeader(WS_ADDR_VER.replyToTag));
    // Add your code to call the desired methods.
  }
}

4.7.2 Callback Service Code

You can use callback service as a web service by using the callback service code.

The following provides a sample of the callback service code. The code shown in bold illustrates how to extract the relatesToID from the message header, which is sent by the client as the MessageID.

You need to implement the code to process the response and deploy the callback service as a web service. Once deployed, add the URL of the callback service to the client code as the replyTo field.

package async.jrf;
 
import com.sun.xml.ws.api.addressing.AddressingVersion;
import com.sun.xml.ws.api.message.Header;
import com.sun.xml.ws.api.message.HeaderList;
import com.sun.xml.ws.developer.JAXWSProperties;
import javax.annotation.Resource;
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
import javax.xml.bind.annotation.XmlSeeAlso;
import javax.xml.ws.Action;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.WebServiceContext;
import javax.xml.ws.soap.Addressing;
// !THE CHANGES MADE TO THIS FILE WILL BE DESTROYED IF REGENERATED!
// This source file is generated by Oracle tools
// Contents may be subject to change
// For reporting problems, use the following
// Version = Oracle WebServices (11.1.1.0.0, build 090303.0200.48673)
 
@WebService(targetNamespace="http://jrf.async/", name="HelloServiceResponse")
@XmlSeeAlso(
  { async.jrf.ObjectFactory.class })
@SOAPBinding(style=Style.DOCUMENT)
@Addressing(enabled=true, required=true)
public class HelloServiceResponseImpl
{
  @Resource
  private WebServiceContext wsContext;
  private static final AddressingVersion WS_ADDR_VER = AddressingVersion.W3C;
  @WebMethod
  @Action(input="")
  @RequestWrapper(localName="helloResponse",targetNamespace="http://jrf.async/",
    className="async.jrf.HelloResponse")
  @Oneway
  public void helloResponse(@WebParam(targetNamespace="", name="return")
    String _return)
  {
    // Use the sample code to extract the relatesTo id for correlation and then add your rest of the logic
    System.out.println("Received the asynchronous reply");
    // get the messageId to correlate this reply with the original request
    HeaderList headerList = (HeaderList)wsContext.getMessageContext().get(JAXWSProperties.INBOUND_HEADER_LIST_PROPERTY);
    Header realtesToheader = headerList.get(WS_ADDR_VER.relatesToTag, true);
    String relatesToMessageId = realtesToheader.getStringContent();
    System.out.println("RelatesTo message id: " + relatesToMessageId);
    // Add your implementation here.
  }
}

4.8 Attaching Policies to Asynchronous Web Services and Clients

The asynchronous web service and client policies must comply with one another. Similarly, the asynchronous callback client and callback service policies must comply with one another.

Note:

Web services reliable messaging (WS-ReliableMessaging) is not supported for Oracle Infrastructure asynchronous web services. That is, you cannot attach a reliable messaging policy at design time, using the @ReliabilityPolicy annotation, or runtime, using Fusion Middleware Control or WLST, to the asynchronous web service or the callback client.

You can use one of the following methods to attach policies to the components:

  • Using annotations at design time.

  • Using Fusion Middleware Control or WLST at runtime.

Each method is described in detail in the following sections.

Note:

You do not need to attach the oracle/wsaddr_policy again to your asynchronous web service or client. By default, the oracle/wsaddr_policy policy is attached to all asynchronous web services and clients and advertised in the WSDL, as it is required by asynchronous web service processing. However, Fusion Middleware Control does not reflect that the policy is attached and it is available for selection in the Available Policies list when attaching polices, as described in "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

You can attach policies to the following asynchronous components:

4.8.1 About Attaching Policies to Asynchronous Web Service Clients

Various policies are attached to Asynchronous Web Service Clients.

At design time, you can use the following methods to attach policies:

  • For SOA/BPEL clients, you can use the SOA Composite Editor to attach policies, as described in "Managing Policies" in Developing SOA Applications with Oracle SOA Suite.

  • For WebLogic Java EE JAX-WS Clients, you can use the Create Web Service Proxy wizard in JDeveloper to attach policies. For more information about creating web service clients using the wizard, see "Creating Web Service Clients" in the Developing Applications with Oracle JDeveloper.

At runtime, you can use the Fusion Middleware Control to attach policies to each type of client, as described in "Attaching Policies to Web Services and Clients Using Fusion Middleware Control" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

4.8.2 Policies to Attach for Asynchronous Callback Services

You can use certain annotations to attach policies while sending the asynchronous response to the client's callback service.

At design time, to attach policies while sending the asynchronous response to the client's callback service, you can use one of the annotations defined in Table 4-2.

Table 4-2 Annotations for Attaching Policies to Web Services and Callback Services

Annotation Description

@CallbackManagementPolicy

The oracle.webservices.annotations.async.CallbackManagementPolicy annotation attaches a management policy when sending the asynchronous response to the client callback service. For more information, see "@CallbackManagementPolicy" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note: This annotation has been deprecated. Oracle recommends that you use the oracle.wsm.metadata.annotation.CallbackPolicySet annotation, as described in "@CallbackPolicySet" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

@CallbackMtomPolicy

The oracle.webservices.annotations.async.CallbackMtomPolicy annotation attaches an MTOM policy when sending the asynchronous response to the client callback service. For more information, see "@CallbackMtomPolicy" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note: This annotation has been deprecated. Oracle recommends that you use the oracle.wsm.metadata.annotation.CallbackPolicySet annotation, as described in "@CallbackPolicySet" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

@CallbackPolicySet

The oracle.wsm.metadata.annotation.CallbackPolicySet annotation attaches one or more policy sets to the callback client of the asynchronous web service that will connect to the callback service. By default, no policies are attached. For more information, see "@CallbackPolicySet" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

@CallbackSecurityPolicy

The oracle.webservices.annotations.async.CallbackSecurityPolicy annotation attaches a security policy to the callback web service. For more information, see "@CallbackSecurityPolicy" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note: This annotation has been deprecated. Oracle recommends that you use the oracle.wsm.metadata.annotation.CallbackPolicySet annotation, as described in "@CallbackPolicySet" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

@FastInfosetCallbackClient

The com.oracle.webservices.api.FastInfosetCallbackClient annotation enables and configures Fast Infoset on the callback client of the asynchronous web service that will connect to the callback service. For more information, see "@FastInfosetCallbackClient" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

At runtime, you can use the Fusion Middleware Control to attach policies to asynchronous callback services, as described in "Attaching Policies" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Use the following guidelines when attaching message protection policies to asynchronous callback services:

  • If you want to enforce a message protection policy on the callback service, you must also enforce a message protection policy on the asynchronous request. Otherwise, an error message will be returned at runtime indicating that the asynchronous client public encryption certificate is not found.

    You can enforce a message protection policy on the asynchronous request without enforcing that same policy on the callback service.

  • If you enforce a message protection policy on the asynchronous web service, then you must configure the client public encryption certificate in the client keystore.

4.8.3 About Attaching Policies to Callback Clients

You can use Fusion Middleware Control at runtime, to attach policies to asynchronous callback clients.

For more information, see "Attaching Policies to Asynchronous Web Service Callback Clients" in Securing Web Services and Managing Policies with Oracle Web Services Manager.

Note:

The policies that you attach to the callback client are advertised in the asynchronous web service WSDL.