4 Developing Asynchronous Web Services

This chapter introduces asynchronous Web service concepts and describes how to develop and configure asynchronous Web services.

This chapter includes the following topics:

Overview of Asynchronous Web Services

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:

Asynchronous Web Service Using a Single Request Queue

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 Asynchronous Web Service Using a Request and a Response Queue, and not the single request queue scenario.

In this scenario, there is a single message-driven bean (MDB) associated with the request queue that handles both the request and response processing.

The following figure shows the flow of an asynchronous method call using a single request queue.

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 describes 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.

Asynchronous Web Service Using a Request and a Response 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 Asynchronous Web Service Using a Single Request Queue.

The following figure shows the flow of an asynchronous method call 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 describes 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.

Client Perspective of Asynchronous Web Service Call

From the client perspective, the asynchronous method call consists of two one-way message exchanges, as shown in the following figure.

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 message flow is as follows:

  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.

How Asynchronous Messages Are Correlated

Note:

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

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 SOA runtime.

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.

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. For complete details, 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.

Developing 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')

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

Creating the Request and Response Queues

Before you deploy your asynchronous Web services, you must create and secure the queues used to store the request and response, as described in the following sections:

Using the Default WebLogic JMS Queues

The process varies based on whether you are using a clustered or non-clustered domain, as described in the following sections.

Using the 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>

Using the 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 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.

Tuning the Default JMS Delivery Failure Parameters

The following default values are configured by default 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 Configuring and Managing JMS 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.

Creating Custom Request and Response Queues

If the default WebLogic JMS queues do not meet your requirements, you can perform the following steps:

  1. Create the request and response queues manually, as described in Programming JMS for Oracle WebLogic Server.

  2. Add them to your application code using the following annotations:

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.

The following provides a list of best practices for creating the custom request and response queues (in Step 1):

  • 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.

Administering Request and Response Queues at Runtime

Using Oracle Enterprise Manager, you can modify the request and response queues at runtime. You will need to stop and restart the server in order for the updates to take effect. For complete details, see "Configuring Asynchronous Web Services" in Security and Administrator's Guide for Web Services.

Securing the Request and Response Queues

Note:

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

It is recommended that you secure the JMS request and response queues with a user- or role-based security policy to secure access to these resources. The steps to secure the JMS request and response queues include:

  1. Optionally, configure the JMS System User, as described in Configuring a 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 Running the WLST Script to Secure the Request and Response Queues.

Configuring a 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 @AsyncWebService Annotation.

After your application has been deployed, you can change the JMS System User in Oracle Enterprise Manager Fusion Middleware Control and in the WebLogic Server Administration Console as described in "Changing the JMS System User for Asynchronous Web Services" in Security and Administrator's Guide for Web Services.

Running the WLST Script to Secure 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>

Confirming the Request and Response Queue Configuration

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

  1. Invoke the Administration Console, as described in "Invoking the Administration Console" in Getting Started With JAX-WS 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 steps:

      • Create and configure the required JMS queues manually. For more information, see "Messaging" in Information Roadmap for Oracle WebLogic Server .

      • 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.

Configuring 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.

@CallbackProperties

Specify a set of properties that are required in the message context when calling the callback service. For more information, see @CallbackProperties Annotation.

@ResponseWebService

Customize the response Web service port information. For more information, see @ResponseWebService Annotation.

@Retry

Specifies whether the asynchronous method is idempotent, or retriable, in the event that its execution is terminated abnormally (for example, due to system failure). For more information, see @Retry Annotation.

Configuring SSL for Asynchronous Web Services

To configure SSL for asynchronous Web services, you must perform the following tasks:

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

    See "Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities" in Securing Oracle WebLogic Server.

  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 Help.

  3. Configure the password for the identity and trust keystores in the Oracle WSM Credential store provider using Fusion Middleware Control Enterprise Manager.

    See "Configuring the Credential Store" in Security and Administrator's Guide for Web Services.

    Ensure that the map with the name oracle.ws.async.ssl.security exists. If it does not exist, you must create it, as described in "Configuring the Credential Store" in Security and Administrator's Guide for Web Services.

    Then, create the three key entries defined in the following table.

    Table 4-2 Configure Identity and Trust Keystores

    Key User Name Password

    trust-keystore-password

    async

    <trust_store_password>

    identity-keystore-password

    async

    <identity_store_password>

    key-password

    async

    <key_password>

Defining Asynchronous Web Service Clients

The following two types of clients can call asynchronous Web services:

  • 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 Oracle Fusion Middleware Developer's Guide for 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 Proxies" in the JDeveloper Online Help.

The following sections step through an example an asynchronous client and callback service that is generated and describe 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.

Updating the Asynchronous Client Code

The following 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.

Example 4-1 Updating the Asynchronous Client Code

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;
import javax.xml.ws.WebServiceRef;
 
// !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
{
  @WebServiceRef
  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.
  }
}

Updating 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.
  }
}

Attaching Policies to Asynchronous Web Services and Clients

You can attach policies to the following asynchronous components:

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.

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

  • Using annotations at design time.

  • Using Enterprise Manager 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, Enterprise Manager 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 to Web Services" in Security and Administrator's Guide for Web Services.

Attaching Policies 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 Oracle Fusion Middleware Developer's Guide for 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 Proxies" in the JDeveloper Online Help.

At runtime, you can use the Enterprise Manager to attach policies to each type of client, as described in "Attaching Policies to Web Service Clients" in Security and Administrator's Guide for Web Services.

Attaching Policies to Asynchronous Web Services and Callback Services

At design time, to attach policies to an asynchronous Web services and callback services, you can use one of the annotations defined in Table 4-3. The annotations are included in the oracle.webservices.annotations package.

Table 4-3 Annotations for Attaching Policies to Web Services

Annotation Description

@AddressingPolicy

Attaches a WS-Addressing policy to the Web service. For more information, see @AddressingPolicy Annotation.

@ManagementPolicy

Attaches a management policy to the Web service. For more information, see @ManagementPolicy Annotation.

@MtomPolicy

Attaches an MTOM policy to the Web service. For more information, see @MtomPolicy Annotation.

@SecurityPolicies

Specifies an array of @SecurityPolicy annotations. Use this annotation if you want to attach more than one WS-Policy files to a class. For more information, see @SecurityPolicies Annotation.

@SecurityPolicy

Attaches a security policy to the Web service. For more information, see @SecurityPolicy Annotation.

At runtime, you can use the Enterprise Manager to attach policies to asynchronous Web services and callback services, as described in "Attaching Policies to Web Services" in Security and Administrator's Guide for Web Services.

Use the following guidelines when attaching message protection policies to asynchronous Web services and 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.

Attaching Policies to Callback Clients

Note:

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

At design time, to attach policies to an asynchronous callback client, you can use one of the annotations defined in Table 4-4. The annotations are included in the oracle.webservices.annotations.async package.

Table 4-4 Annotations for Attaching Policies to Callback Clients

Annotation Description

@CallbackManagementPolicy

Attaches a Management policy to the callback client of the asynchronous Web service that will connect to the callback service. By default, no Management policy is attached. For more information, see @CallbackManagementPolicy Annotation.

@CallbackMtomPolicy

Attaches an MTOM policy to the callback client of the asynchronous Web service that will connect to the callback service. By default, no MTOM policy is attached. For more information, see @CallbackMtomPolicy Annotation.

@CallbackSecurityPolicy

Attaches one or more security policies to the callback client of the asynchronous Web service that will connect to the callback service. By default, no security policies are attached. For more information, see @CallbackSecurityPolicy Annotation.

At runtime, you can use the Enterprise Manager to attach policies to asynchronous callback clients, as described in"Attaching Policies to Asynchronous Web Service Callback Clients" in Security and Administrator's Guide for Web Services.