Tuesday, March 28, 2017

Asynchronous Web Services with Oracle SOA Suite

The top web services based approaches for asynchronous interactions among enterprise applications are described in the article. The common used during Oracle SOA Suite leveraging method that based on a callback service and the WS-Addressing specification is shown. A number of examples of asynchronous web service creation and client generation using the JDeveloper IDE are considered.


Introduction


Time to time, when we as architects integrate some enterprise applications, asynchronous communication has to be taken into account. Asynchronous communication means a service consumer isn't blocked for a response from a service provider, it just gets an acknowledge and continue doing its work. There are two popular approaches to implementing asynchronous communication among web services:

  • polling refers to actively sampling the status of a being processed request by a service consumer as a synchronous activity.

  • callback refers to a method provided by a service consumer. When the service provider have accomplished the operation processing, it calls the consumer. In this approach, the service consumer simultaneously works like a callback methods service provider as well.

Oracle SOA Suite supports the second approach. An implemented leveraging the suite service, returns a 202 Accepted HTTP response on each request from a consumer. This response means the request is accepted and the service is going to handle it. A new instance of the composite application is created. The instance can be in the Running state during a very long time, it is usual even some human reactions are involved in the process. A callback method provided by the service consumer is invoked at the end of the process.


WS-Addressing


Any callback mechanism is based on two main decisions: how a service provider passes the callback address to the consumer and how to make the correlation between requests and responses, so how the consumer understands which response is a reply to a certain request. The WS-Addressing specification is the answer to both these questions. The specification is a standardised way of including message routing data within SOAP headers. This specifies a SOAP header that contains the endpoint reference to which the response is to be returned. It is the way to decouple the lifetime of the SOAP request/response interaction from the lifetime of the HTTP request/response protocol, thus enabling long-running interactions that can span arbitrary periods of time.

Let's have a look at an asynchronous interchange, which leveraging the WS-Addressing specification, on an example. The following request is being produced by a service consumer:



The was:To header contains the endpoint, the request is sent to. The wsa:Action header is a reference on the action that will be being invoked. Unique message id is passed in the wsa:MessageID header as well as the unique id of the related message, which is the request we are answering to, is contained in the wsa:RelatesTo header. Because the above message is a request, not a response, the wsa:MessageID and wsa:RelatesTo contains the same values.

The address on the callback service is assigned to the wsa:ReplyTo/wsa:Address. This address will be used as the target for a response on the request. Other headers inside wsa:ReplyTo are in use for any other parameters of the related messages transferring.

A service provider replies by the following message:



Here we can see, the value of header wsa:To is equal to the data in request's header wsa:ReplyTo/wsa:Address. In the same time, the value of the wsa:RelatesTo header is the same as the one in header wsa:MessageID. Because the message is a response and it's impossible to send another response on a response, the wsa:ReplyTo/wsa:Address header contains the stub address: http://www.w3.org/2005/08/addressing/anonymous.

Creating an asynchronous web service with Oracle SOA Suite


Let's look how to leverage Oracle SOA Suite for the creation of an asynchronous web service. The business logic of the demo service will be encapsulated to an asynchronous BPEL-process.

Firstly, a SOA application should be created. The according master is available via the New -> Applications -> SOA Application menu.


On the first step of the master is a place to specify the application name and sources folder.


The second step of the master helps to create a project. Project name and a folder for project's sources must be specified. Since an SOA application is being created, technology "SOA" already is under selection.


The third step of the master is used for the specification of the Oracle SOA Suite composite under construction and it's template. For demo purposes, we should create a number of XSDs specifying the service's interface; therefore, firstly the 'empty composite' template should be selected.


If the Finish button is pressed, a new composite will be created. The business logic of the composite is encapsulated in a BPEL-process, however, the interfaces of the web service under construction should be described before. The message structure is the main part of an interface specification. The message structure is specified as an XSD schema, Oracle JDeveloper provides a master for this kind of work.


The name of the XSD file, source folder, target namespace and a prefix for the namespace should be chosen from here.


For example, a web service for communication with Help Desk will be created. The service will be used for the ticket registration and publication of new comments for these claims. Two data types should be put into the composite: tTicket is a complex type describes a claim, and tTicketComment is a complex type describes a comment for a ticket in Help Desk. The structure of these data types is the following:


The messages based upon the above structure will be put in another XSD file. The web service will leverage these messages to communicate with other citizens of the enterprise.


This XSD consists of the following four data types as well as four elements: register a new claim request, add a new comment request, and the responses on these requests. The structure of the TicketService.xsd file is the following:


Once the messages have been defined, the web service may be taken under construction. Let's begin from the development of operation CreateTicket. Operation logic will be encapsulated within the CreateTicketBPELProcess BPEL-process. To create a new process, the BPEL service component has to be moved from the Component palette to the Composite area.


The BPEL process creation master will be here. A version of the WS-BPEL specification has to be chosen: 1.1 or 2.0, and a name for the process should be specified as well as a target namespace and a process type: synchronous, asynchronous, or one-way (fire and forget). A very important detail is the input and (if it's needed) output messages' formats.


Once the OK button has been pressed, the created BPEL-process is put into the Composite area. Because the Expose as a SOAP service checkbox was checked, a WebService component is created simultaneously. This web service is an entry point into the composite.


The service design is the following: when a request from a consumer arrived at the entry point, the service puts it into a JMS queue. A receiver consumes the request from the queue, handles it, shapes a response and puts this one into a JMS response queue. The BPEL-process consumes the response from the response queue and sends it to the callback service provided by a service consumer.

There is the JMS adapter in Oracle SOA Suite. The purpose of the adapter is to allow BPEL-processes to interact with JMS queues. To add a JMS adapter to the composite, the adapter component has to be moved from the Component palette to the Composite area. There is a master for configuration the adapter. The first step of the master is for information purposes only and would not be of interest to us. The name of the JMS adapter has to be specified on the second step of the master.


On the third step of the master, a JMS provider type that will be used has to be chosen, e.g. Oracle WebLogic JMS.


On the fourth step of the master, a defined connection to the application server should be specified.


On the fifth step of the master, the adapter interface has to be imported from an existing WSDL file or be defined from operation and schema.


On the sixth step of the master, a pattern for JMS interaction should be specified. The adapter can be a subscriber to a queue, produce JMS messages to a queue, or request for incoming messages from a JMS destination and replies by putting messages to a JMS destination either synchronously or asynchronously.


On the seventh step of the master, the parameters for the Request operation (destination name, message parameters, JNDI name for the JMS Connection) have to be specified.


On the eighth step of the master, the parameters (the same as above) for the Reply operation have to be specified as well.


On the second last step of the master, the schema that defines the message payload of the JMS destination should be specified (schema file location and schema element).


The last step of the master just contains the WSDL-file name created into the project directory.


Once the Finish button has been pressed, the defined above JMS adapter is put into the Composite area. The adapter should be connected to the BPEL-process.


The process logic is the following:


An error handling block is here. The block sends some notifications about errors occurring in the service. Without these notifications, a service consumer will forever wait for a response.

The most interesting part is the last activity, before callback sending, in the BPEL process. Since Oracle SOA Suite is a stateful solution, all persisted before parameters are useful during the callback activity. The state of a process instance is persisted in a database, so even if the server was be restarted between the arrival of a request and the sending of a callback, the process state would not be lost.


Ok, the composite application is ready for deploy. To deploy a project, please use the Deploy... item of the composite's context menu.


1. Select the destination: an application server or file.


2. Specify the application version and SOA configuration plan


3. Select the application server from the list to which to deploy the SOA composite application.


4. Select the partition in that to deploy this archive. If the server contains no partitions, you cannot deploy this archive. Also, if the server is not in a running state, you cannot deploy this archive. By default, a partition named default is automatically included with Oracle SOA Suite. You create partitions in the Manage Partitions page of Oracle Enterprise Manager Fusion Middleware Control.


5. Review the deployment details on the Summary page.


Once the Finish button has been pressed, the composite deployment process is started. The Deployment Finished record in the Deployment - Log window notices about the completion of the deployment process.


Once the web service has been deployed, the WSDL definition of the service is available. Since the web service is generated by a BPEL-process, the WSDL definition contains the partner link types which link together asynchronous request and response.



N.B! The partner links must be included within the WSDL definition. If there were no partner links, Oracle JDeveloper wouldn't generate a client for this service (a little bit more precisely, a client would be generated, but a callback web service wouldn't).

The WSDL definition contains two port types, the first port type encapsulates the links on the defined above request messages while the second one encapsulates the links response messages. The noted above partner types make an association between the port types.



Currently, we are ready to test the application. The composite page should be opened in Oracle Enterprise Manager. There is the Test button. Once the button has been pressed, here is the form which allows assigning the input parameters of the web service.


The Test Web Service button sends the shaped test request to the web service endpoint. But, since the web service is asynchronous, the response demonstration page won't be shown, only a page which contains the Request successfully received status will be here instead.


A new composite instance is instantiated, this instance will be marked as Running until a corresponding message from an external application has been put into the response queue.


Let's check the request queue (jms/request). There is a message created by the web service during the invocation.


Let's emulate an answer from an external application. We will manually create a corresponding message and put it into the jms/response queue. N.B! The field Correlation ID of the message must match the value of the Message ID field from the request message.


The running composite instance consumes a new message from the response queue and completes its work. But a callback message won't be sent since the WS-Addressing fields contain no values.


Generating a consumer to an asynchronous web service using Oracle JDeveloper


Oracle provides an integrated developer environment - JDeveloper - containing a complete toolset for generating web service consumers including consumers to asynchronous web services. Let's continue the above example - develop a consumer for the created web service. The code of the consumer will be placed to a Generic project.


The master should be used to define the project name and set of project technologies. More generally, the set of project technologies can be empty.


The created project will be added to the Application Navigation tree of JDeveloper.


The next step is the stub generation. JDeveloper calls this stub as Web Service Proxy and the menu for the stub generation is located in the Business Tier/Web Services list of the Categories tree.


The Create Web Service Proxy master proposes one of the two most widely used specification: JAX-RPC or JAX-WS. Let's select the last one.


A WSDL definition of the web service should be selected. The URL can be copied just from the corresponding page of Oracle Enterprise Manager.


Default mappings from WSDL namespaces to Java packages have to be provided. Because there is a partner link type connecting a port type for requests with a port type for responses in the WSDL, the Generate As Async checkbox is available. If the checkbox is checked, the callback service stub will be generated as well.


The web service endpoint should be specified on the Port Endpoints page.


The Asynchronous Methods page allows us to choose the asynchronous methods to be added. Three options are there: Don't generate any asynchronous methods, Generate asynchronous methods where specified by the JAX-WS binding, or Generate asynchronous methods for all operations.


If required, a number of managed by Oracle Web Service Manager (OWSM) policies for the web service client should be configured. The WSDL definition of the web service contains only one policy (WS-Addressing). The oracle/wsaddr_policy value of the Addressing field is associated to this policy.


The Defined Handlers page allows us to specify any handler classes which will deal with the web service message if required.


The last page of the master informs about which service endpoint interfaces and methods will be generated.


Once the Finish button has been pressed, the all required classes: data type mappings, web service consumer stubs, a console client for demonstration, and a callback web service are generated.


The callback handler code is the following:


The business logic should be located after the Add your implementation here. comment. The trivial implementation can just print the values of the message elements.

The callback web service can be started by the Run context menu item.


The web service is deployed to the IntegratedWebLogicServer domain (the default WebLogic domain integrated into JDeveloper). After successfull deployment and starting, the web service is available by the Target URL.


The message http:// replace with URL of the callback service from the generated consumer code has to be replaced by this address. In this way, the correct set of WS-Addressing headers pointing out to the callback web service. The code of the consumer logic has to be located after the Add your code to call the desired methods. comment.


The client launching in the same way as the callback web service: using the Run context menu item. The console window which contains the result of the service invocation will be enabled after the launch.


A new Running instance of the composite will be displayed on the corresponding page in Oracle Enterprise Manager.


A response from an external application has to be emulated in the same way as we did it during the asynchronous web service test above. After the composite instance lifecycle has been successful accomplished, a response is shaped and sent to the callback web service. The message parameters will be logged.


The asynchronous web service works as designed along with the client.

Adding a new web service operation. Mediator


When we were designing the asynchronous web service, we noticed the service is consists of two operations: 'create a new claim' and 'add a comment'. The 'create a new claim' operation is based upon the BPEL component. Now let's define the 'add a new comment' operation. There are two approaches for this task: the operation may be defined in the same BPEL process together with the 'create a new claim' one, or another BPEL-process may be created. The second way is a bit more preferable to me because the business logic of each operation is encapsulated in a different BPEL process. In the future, a new operation may be defined just by adding a new BPEL-process into the composite.

To connect the BPEL-process with the exposed service endpoint, the Mediator service component will be used. Mediator is a service component that provides mediation capabilities such as selective routing, transformation, and validation capabilities. Some time ago, Oracle provided a self-developed enterprise service bus (Oracle Enterprise Service Bus), but now, after its acquisition of BEA Systems, Oracle has had two service buses: Oracle Enterprise Service Bus and BEA AquaLogic Service Bus. Since Oracle SOA Suite 11g, pure Oracle's service bus has been rebranded to Mediator and ready to use within a composite application.

To create a Mediator, the Mediator component has to be moved from the Component palette to the Composite area. The Create Mediator dialogue appears. The dialogue contains the fields to specify the mediator name and select the required template of interaction. The Asynchronous Interface has to be selected if an asynchronous web service is taken into account.



The created Mediator appears on the Components swim lane of the Composite editor window. Also on the Exposed services swim lane will be created an entry point (TicketServiceMediator_ep), which contains the defined by default operations: execute and callback.


The Mediator configuration file - the WSDL definition of the TicketServiceMediator_ep service - has to be manually modified: to define both developed operations and their callbacks.


As opposed to BPEL, Mediator doesn't care about the Partner link conception. Therefore, to allow generating a consumer to the asynchronous web service, the partner link types have to be manually defined within the WSDL definition. The partner link type wires port type TicketService_ptt to the TicketServiceCallback_ptt one.


Since the name of the port type defined within the TicketServiceMediator_ep service WSDL definition is changed, these modifications have to be reflected in the composite.xml file. The source of the file is modified on the Source tab in the Composite editor. New titles of the port types should be put there for the service name="TicketServiceMediator_ep" component.


And... the constructed Mediator has to be removed from the composite. The Mediator was used to get the WSDL-file template. It's not allowed to modify an interface for a Mediator which wired to another component. The entry point may be removed also.


Currently, a new Mediator may be put into a composite application. An entry point for the mediator, the TicketServiceMediator_ep service, already exists, so the Define Interface Later template is selected.


The Mediator has to be wired to the entry point and BPEL-process. The Mediator operation to be wired to BPEL has to be chosen.


In order to implement the AddComment operation, a new asynchronous BPEL-process, which encapsulates the same business logic as the CreateTicketBPELProcess one does, has to be created. The BPEL-process should be wired to the Mediator as well. The following composite application is constructed.


The last action for the configuration is the definition of the input to output messages transformation. The Transform Using action is taken into account (please, have a look at the crosswise pictured button).


An existing, as well as a new mapper, file can be used.


An XSLT-transformation is used for mapping a request message to message for the BPEL-process. Oracle JDeveloper provides a usable XSLT transformation visual editor. Since the transformation is trivial: both messages are defined by the same type, the CreateTicket element on the left side of the editor has to be connected to the same element on the right side. The details of both elements will be connected together automatically.


But if required, the transformation logic can be manually modified.


The result if the following:


The callback transformation is defined in the same way. Unfortunately, Mediator isn't allowed to define a number of callbacks for an operation. This capability would be very useful in case of error handling.


Since some partner link types were added to the WSDL definition of the TicketServiceMediator_ep service, JDeveloper is able to generate a consumer to the asynchronous web service as well as the callback.



The rest of the consumer development process is similar to the above described (see Generating a consumer to an asynchronous web service using Oracle JDeveloper>).

The Mediator can be traced by Oracle Enterprise Manager. The request message is transformed by the XSLT mapping and arrives to the process operation of BPEL. The callback request is sent by BPEL and then transformed to an output message. The cycle has closed.


Conclusions


Asynchronous messaging gets more popular in the enterprise application integration world. However, years ago JMS was only one available approach for asynchronous messaging and asynchronous web services used to be considered only as an extreme way to solve this task. Today the situation is significant different since a number of WS-* specifications, e.g. WS-Addressing, have been taken into account. Modern enterprise application integration platforms such as Oracle SOA Suite provide the infrastructure for developing asynchronous web services as well as their clients, and this fact enables to eliminate the legacy proprietary EAI solutions and replace them with the standardised modern integration approach - web services, including asynchronous ones. Therefore, the costs of connecting these new applications to the information landscape of an enterprise will be significant reduced.

Would you like to give a 'Like'? Please follow me on Twitter!