Using Integration Controls

Message Broker Controls

Note:

The Message Broker controls are available in BEA Workshop for WebLogic Platform only if you are licensed to use WebLogic Integration.

Messaging systems are often used in enterprise applications to communicate with legacy systems, or for communication between software components. A client of a messaging system can send messages to, and receive messages from, any other client.

The Message Broker resource provides a publish and subscribe message-based communication model for WebLogic Integration business processes, and includes a powerful message filtering capability.

The Message Broker provides typed channels, to which messages can be published, and to which services can subscribe to receive messages. You can design a business process to subscribe to specific channels, using XML Beans for type-safe methods.

Subscribers to Message Broker channels can filter messages on the channels using XQuery filters. WebLogic Integration supports a powerful mapping tool that allows you to create XQuery filters for channels. Business processes can filter documents on channels, based on document type or document content. For example, you can design a filter that filters on stock symbol documents, or one that filters on a specific purchase order number.

In addition to business processes that can publish messages to Message Broker channels, WebLogic Integration supports event generators, which can publish external events to message broker channels. WebLogic Integration provides native event generators, including Email, File, HTTP, JMS, MQ, and Timer event generators. These event generators allow you to start or continue a business process based on events, such as the receipt of email or a new file appearing in a directory. WebLogic Integration also works with Application View event generators, which work with J2EE-CA connectors. To learn about creating and managing event generators using the WebLogic Integration Administration Console, see Event Generators in Managing WebLogic Integration Solutions at the following URL:
http://download.oracle.com/docs/cd/E13214_01/wli/docs92/adminhelp/evntgen.html

To learn more about defining channels, publishing or subscribing to channels, and creating subscription filters, see:

Publishing and Subscribing to Channels
"Note About Static and Dynamic Subscriptions" in @com.bea.wli.control.broker.MessageBroker.StaticSubscription

You can customize Message Broker controls in several ways. You may modify the properties of the control. These modifications is described in more detail in the sections that follow.

You can use the Interface ControlContext for access to a control's properties at run time and for handling control events. Property values set by a developer who is using the control are stored as annotations on the control's declaration in a JWS, JSP, or JPD file, or as annotations on its interface, callback, or method declarations in a control file.

Topics Included in This Section

Message Broker Publish Control

Two Message Broker controls are available from your business processes: Publish and Subscription. Your business process uses a Publish control to publish messages to Message Broker channels. You bind the Message Broker channel to the Publish control when you declare the control, but it can be overridden dynamically. You can add additional methods to your extension (subclass) of the Message Broker Publish control.

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 Publish controls:

To Create an Instance of a Message Broker Publish Control

In the Package Explorer pane, double-click the business process to which you want to add the MB Publish control. The business process is displayed in the Design View.
Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.

Note:

If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click Window

Show View

Data Palette from the menu bar.

Select MB Publish.

The Insert Control: MB Publish dialog box appears.

In the Insert Control: MB Publish dialog box enter the following details:

In the Field Name, type the variable name used to access the new MB Publish control instance from your business process. The name you enter must be a valid Java identifier.
In the Insertion point: from the drop-down list select the the point where you want the field name to be inserted in the process file.
Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
Click Next.

The Create Control wizard appears.

In the Create Control dialog box enter the following details:

In the Name field, type the name of your new control extension file.
Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
Click Next.
The Insert control- MB Publish dialog-box appears.

In the Insert control- MB Publish dialog-box, enter one of the following details:

Channel name—Select a channel to which you want your business process to publish.

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 published to the specified channel.
Metadata type—This read-only field displays the metadata type value if qualifiedMetadataType is set in the channel definition.

Click Finish.

An instance of a MB Publish control is created in your project and displayed in the Controls tab.

Java File for Your MB Publish Control

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

package requestquote;

import org.apache.beehive.controls.api.bean.ControlExtension;

/*

 * A custom Publish control.

*/

@ControlExtension

@com.bea.control.PublishControl.ClassPublish(channelName = "/deadletter/rawData")

public interface MBPublish extends com.bea.control.PublishControl {

	@com.bea.control.PublishControl.MethodPublish(body = "{value}")

	void publish(com.bea.data.RawData value);

	@com.bea.control.PublishControl.MethodPublish(metadata = "{metadata}", body = "{value}")

	void publishWithMetadata(org.apache.xmlbeans.XmlObject metadata,

			com.bea.data.RawData value);

	static final long serialVersionUID = 1L;

	public MBPublish create();

Using Methods of the MB Publish Interface

This section describes the MB Publish control interface. Use the methods from within your application to publish to Message Broker channels.

MB Publish Control Interface

package com.bea.control;

import com.bea.wli.control.dynamicProperties.PublishControlPropertiesDocument;
import org.w3c.dom.Element;
import weblogic.jws.control.Control;

/**
 * Message Broker Publish control base interface 
 */

public interface PublishControl extends Control {

    /**
     * Temporarily sets the message headers to use in the next publish operation
     * @param headers headers to set
     */

    void setOutputHeaders(Element[] headers);

    /**
     * Sets the dynamic properties for the control
     * @param props the dynamic properties for the control
     */

     void setProperties(PublishControlPropertiesDocument props);
    /**
     * Sets the dynamic properties for the control
     * @return the current properties for the control
     */

     PublishControlPropertiesDocument getProperties();
}

The PublishControlPropertiesDocument XML Bean is defined in DynamicProperties.xsd which is located in the Schemas folder of each process application.

To learn more about the methods available on the MB Publish control, see the Interface PublishControl Javadoc.

Method Attributes

The following method attributes determine the behavior of the MB Publish control.

Class attributes include:

`channel-name`

The name of the Message Broker channel to which the MB Publish control publishes messages.

`message-metadata`

By default, this XML header is included in messages published with this control. Valid values include a string containing XML.

Method attributes include:

`message-metadata`

XML header to include in messages published with the control method to which it is associated. Valid values include a string containing XML, or a method parameter in curly braces. For example: {parameter1}.

`message-body`

Valid values include a string containing text that is used as the message body in the published message, or a method parameter in curly braces. For example: {parameter2}.

Example Code for MB Publish Control

The Publish control allows you to override class-level annotations with dynamic properties. To do so, use an XML variable that conforms to the control's dynamic property schema.

The following is an example of an XML variable you can use to specify the dynamic properties:

<PublishControlProperties>
    <channel-name>potopic</channel-name>
    <message-metadata>
        <custom-header>ACME Corp</custom-header>
    <message-metadata>
</PublishControlProperties>

The XML Schema for the MB Publish control dynamic properties is shown in the following listing. You can obtain this schema by adding the WLI Schemas project template to you application. You can get and set these properties using the getProperties and setProperties methods.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.bea.com/wli/control/dynamicProperties"
xmlns="http://www.bea.com/wli/control/dynamicProperties"
elementFormDefault="qualified">
    <xs:element name="PublishControlProperties">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="channel-name" type="xs:string" 
                            minOccurs="0" maxOccurs="1" />
                <xs:element name="message-metadata" type="header" 
                            minOccurs="0" maxOccurs="1" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>

<!-- The following complex-type represents any arbitrary sequence of XML content -->

    <xs:complexType name="header">
        <xs:sequence>
            <xs:any namespace="##other" minOccurs="0" 
                    maxOccurs="unbounded" processContents="lax" />
        </xs:sequence>
    </xs:complexType>
</xs:schema>

Example Code

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

/*
 * @jc:mb-publish-control channel-name="/controls/potopic" 
 */

interface MyPublishControl extends PublishControl,com.bea.control.ControlExtension {
    /**
     * @jc:mb-publish-method
     *      message-metadata="<custom-header>ACME Corp</custom-header>"
     *      message-body="{myMsgToSend}"
     */

    void publishPO(XmlObject myMsgToSend);
}

/*
 * @common:control 
 */
private MyPublishControl pubCtrl;

// publish a message 
void sendIt(XmlObject myMsgToSend) {
    pubCtrl.publishPO(myMsgToSend);
}

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

In the Package Explorer pane, double-click the business process to which you want to add the MB Subscription control. The business process is displayed in the Design View.
Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.

Note:

If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click Window

Show View

Data Palette from the menu bar.

Select MB Subscription.

The Insert Control:MB Subscription dialog box appears.

In the Insert Control:MB Subscription dialog box enter the following details:

In the Field Name, type the variable name used to access the new MB Subscription control instance from your business process. The name you enter must be a valid Java identifier.
In the Insertion point: from the drop-down list select the the point where you want the field name to be inserted in the process file.
Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
Click Next.

The Create Control dialog-box appears.

In the Create Control dialog box enter the following details:

In the Name field, type the name of your new control extension file.
Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
Click Next.

The Insert control- JMS dialog-box appears.

In the Insert Control:MB Subscription dialog box enter the following details:

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

Note:

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.

Note:

If you choose the option "this subscription" will be filtered, it's mandatory to provide the filter value in SubscriptionControl annotation

Click Finish.

An instance of a MB Subscription control is created in your project and displayed in the Controls tab.

The control declaration is written to your Process.java file.

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

Java File for Your MB Subscription Control

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

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

package requestquote;

import com.bea.control.SubscriptionControl;

import org.apache.beehive.controls.api.bean.ControlExtension;

import org.apache.beehive.controls.api.events.EventSet;

/*

 * A custom Subscribe control.

*/

@ControlExtension

@SubscriptionControl.ClassSubscription(channelName = "/deadletter/string")

public interface MBSubscription extends com.bea.control.SubscriptionControl {

	@EventSet

	interface Callback {

		@SubscriptionControl.SubscriptionCallback(body = "{message}")

		void onMessage(String message);

	static final long serialVersionUID = 1L;

	public MBSubscription create();

You must select the This subscription will be filtered check box to ensure that the subscribeWithFilterValue() method in included in the Control java 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 Interface SubscriptionControl 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.

Using Event Generators to Publish to Message Broker Channels

Event generators publish messages to Message Broker channels. WebLogic Integration supports the following event generators:

Email event generators
File event generators
HTTP event generators
JMS event generators
MQSeries event generators
Timer event generators