Message Broker Subscription Control

Two Message Broker controls are available from your business processes: Publish and Subscription. Your business process uses a Subscription control to dynamically subscribe to channels and receive messages. You bind the channel and optionally, an XQuery expression for filtering messages, when you create an instance of the control for your business process. The bindings cannot be overridden dynamically.

The Subscription control interface includes methods that allow your business process to subscribe to and unsubscribe from the bound Message Broker channel.

Subscribe operations are part of the larger XA transaction, as with other business process operations. This allows subscribe operations to be rolled back if the business process operation fails. Because a subscription is in a transaction, you have to commit the transaction to make it durable. If you're doing non-transactional work, that is, if a subscribe operation must be committed before performing an action that might trigger a return message, use <transaction/> blocks in the flow to commit the current business process state, including the subscription.

For information on how to add control instances to business processes, see Using Controls in Business Processes.

The following topics provide information about creating and using Message Broker Subscription controls:

To Create an Instance of a Message Broker Subscription Control

Click Add on the Controls tab to display a list of controls that represent the resources with which your business process can interact.

Note: If the Controls tab is not visible in WebLogic Workshop, click View —> Windows —> Data Palette from the menu bar.

Choose Integration Controls to display the list of controls used for integrating applications.
Choose MB Subscription. The Insert Control dialog box is displayed.
In the Insert Control dialog box (Step 1), enter a name for the instance of this control. The name you enter must be a valid Java identifier.
In the Insert Control dialog box (Step 2), select one of the following options:

Use a MB Subscription control already defined by a JCX file

Enter a filename for the MB control in the JCX file field, or click Browse to find the JCX file in your file system.

Create a new MB Subscription control to use

Enter a filename in the New JCX name field.

In the Insert Control dialog box (Step 3), specify the channel name as follows:

channel-name—Select a channel to which you want your business process to subscribe.

Note: If no options are available in the channel-name field, you must create a channel file, which defines the channels to which your business process can publish and subscribe. To learn how to create this file, see How Do I: Create Message Broker Channels?.

message type—This read-only field displays the type of data received from the specified channel: String, XmlObject, RawData.
metadata type—This read-only field displays the metadata type value if qualifiedMetadataType is set in the channel definition.

Select the This subscription will be filtered check box if you want to subscribe using filter values.
Click Create to close the Insert Control dialog box.

An instance of a MB Subscription control is created in your project and displayed in the Controls tab. The following figure shows an example instance of a MB Subscription control displayed in the Controls tab:

The control declaration is written to your JPD source file.

/**
  * @common:control
  */
  private processes.mbSubscribe mbSubscribe;

JCX File for Your MB Subscription Control

When you create a new MB Subscription control, you create a new JCX file in your project. The following example JCX file is automatically created by the control wizard:

import com.bea.control.SubscriptionControl;  
import com.bea.data.RawData; 
import com.bea.xml.XmlObject;

/** 
 * Defines a new Subscription control. 
 * 
 * @jc:mb-subscription-control channel-name="/controls/channel1" 
 */

public interface mbSubscribe extends SubscriptionControl,
 com.bea.control.ControlExtension
{ 
    /** 
     * @jc:mb-subscription-method filter-value-match="{value}" 
     */

    void subscribeWithFilterValue(String value);

    interface Callback extends SubscriptionControl.Callback { 
        /** 
         * @jc:mb-subscription-callback message-body="{message}" 
         */

       void onMessage(XmlObject message); 
    } 
}

You must select the This subscription will be filtered check box to ensure that the subscribeWithFilterValue() method in included in the JCX file. The onMethod method on the Calback interface uses the message type defined in the channel file.

Using Methods of the MB Subscription Interface

This section describes the MB Subscription control interface.The methods you can use to subscribe to Message Broker channels are available from within your application.

Class Interface

package com.bea.control;

import weblogic.jws.control.Control;

/**
 * Message Broker Subscription control base interface 
 */

public interface SubscriptionControl extends Control
{

/**
     * Subscribes the control to the message broker. If the subscription
     * uses a filter expression, then the default filter value will be
     * used. If no default filter value is defined in the annotations,
     * then a <tt>null</tt> filter value will be used, meaning that any
     * filter result will trigger a callback.
     */

    void subscribe();

    /**
     * Unsubscribes the control from the message broker, stopping
     * further events (messages) from being delivered to the control.
     */

    void unsubscribe();
    
    interface Callback {
        /**

         * Internal callback method used to implement user-defined callbacks.
         * JPDs cannot and should not attempt to implement this callback method.
         *
         * @param msg  the message that triggered the subscription
         * @throws Exception
         *
        void _internalCallback(Object msg) throws Exception;
         */
    }
}

Note: If the subscription uses a filter, you must define custom subscription methods to specify the filter value to be matched at run time.

The Subscription control does not define callback methods for you. You must define a custom callback to specify how the business process expects to receive the event messages. (Event messages can be XML, raw data, or string.)

To learn more about the methods available on the MB Subscription control, see the SubscriptionControl Interface Javadoc.

Method Attributes

This section describes the class and method attributes supported for the Subscription control.

Class attributes include:

channel-name

The name of the Message Broker channel to which the control subscribes. This is a required class-level annotation that cannot be overridden.

xquery

The XQuery expression that is evaluated for each message published to a subscribed channel. Messages that do not satisfy this expression are not dispatched to a subscribing business process. This is an optional class-level annotation that cannot be overridden.

Method attributes include:

filter-value-match

The filter-value that the XQuery expression results must match for the message to be dispatched to a subscribing business process. This is an optional method-level annotation. Valid values for the filter-value-match annotation include a string constant that is compared directly to the XQuery results, or a method parameter in curly braces. For example: {parameter1}

Callback method attributes include:

message-metadata

The name of a parameter in the callback method that receives the metadata from the message that triggered the subscription. This parameter must be of type XmlObject (or a typed XML Bean class).

message-body

The name of a parameter in the callback method that receives the body from the message that triggered the subscription. This parameter must be of type XmlObject (or a typed XML Bean class), String, RawData, or a non-XML MFL class (a subclass of MflObject).

Example Code for MB Subscription Control

MB Subscription controls must be extended. The following is an example of how to code a MB Subscription control in your JPD file.

/*
 * @jc:mb-subscription-control 
 *         channel-name="/controls/stocks" 
 *         xquery="$message/StockSymbol/text()"
 */
interface MySubscriptionControl extends SubscriptionControl, ControlExtension {
    /**
     * @jc:mb-subscription-method
     *      filter-value-match="BEA"
     */
    void subscribeToBEA();
    /**
     * @jc:mb-subscription-method
     *      filter-value-match="{symbol}"
     */
    void subscribeToSymbol(String symbol);
    interface Callback {
        /**
         * @jc:mb-subscription-callback message-body="{myMsgReceived}"
         */
        onXMLMessage(XmlObject myMsgReceived);
   }
}
.
.
.
/*
 * @common:control
 */
 MySubscriptionControl subCtrl;
// subscribe to a message

void subscribeIt() {
      subCtrl.subscribeToBEA();
}
// receive a message after subscribing
subCtrl_onXMLMessage(XmlObject myMsgReceived)
{
}

Note About Static and Dynamic Subscriptions to Message Broker Channels

In addition to the dynamic subscriptions you design at Control nodes in your business process, you can design static subscriptions at Start nodes to receive messages from Message Broker channels.

To learn how to design static subscriptions to Message Broker channels at business process Start nodes, see Designing Start Nodes.