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 Oracle 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. Oracle 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, Oracle WebLogic Integration supports event generators, which can publish external events to message broker channels. Oracle 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. To learn about creating and managing event generators using the Oracle WebLogic Integration Administration Console, see Event Generators in Using the Oracle WebLogic Integration Administration Console.
To learn more about channels, see:
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.
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:
Note: | If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Window > Show View > Data Palette from the menu bar. |
The Insert Control: MB Publish dialog box appears (see Figure 10-1).
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. |
qualifiedMetadataType
is set in the channel definition. An instance of a MB Publish control is created in your project and displayed in the Data Palette.
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();
}
This section describes the MB Publish control interface. Use the methods from within your application to publish to Message Broker channels.
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.
The following method attributes determine the behavior of the MB Publish control.
channel-name
message-metadata
message-metadata
{
parameter1
}
.
message-body
{
parameter2
}
.
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>
MB Publish controls must be extended. The following is an example of how to code a MB Publish control in your business process.
/*
* @com.bea.control.PublishControl.ClassPublish channel-name="/controls/potopic"
*/
public interface MBPublish extends com.bea.control.PublishControl{
/**
* @com.bea.control.PublishControl.MethodPublish
* message-metadata="<custom-header>ACME Corp</custom-header>"
* message-body="{myMsgToSend}"
*/
void publishPO(XmlObject myMsgToSend);
}
/*
* org.apache.beehive.controls.api.bean.Control
*/
private MyPublishControl pubCtrl;
// publish a message
void sendIt(XmlObject myMsgToSend) {
pubCtrl.publishPO(myMsgToSend);
}
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:
Note: | If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Window > Show View > Data Palette from the menu bar. |
The Insert Control:MB Subscription dialog box appears.
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. |
qualifiedMetadataType
is set in the channel definition. Note: | If you choose the option "this subscription" will be filtered, it’s mandatory to provide the filter value in SubscriptionControl annotation |
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.
/**
* org.apache.beehive.controls.api.bean.Control
*/
private processes.mbSubscribe mbSubscribe;
Note: | If a JPD has any in-line XQueries, while upgrading the JPD, either the XQueries are upgraded, or the JPD is marked with @XQuery.Version=2002. If the JPD does not have any XQueries, the version is not set to xquery=2004. If this JPD refers to a subscription control that has XQuery set, the upgraded JPD version is xquery=2004, and the upgraded subscription control version is xquery=2002. The XQuery prolog of the JPD is appended to any XQueries in subscription controls used in the JPD while generating the compiled artifacts (wli-subscriptions.xml ). The version incompatibility makes the generated XQuery invalid, as the XQuery is XQ2002 and its prolog is XQ2004. |
Note: | The only solution is to ascertain that all xqueries in an upgraded application are either version XQ2002 or XQ2004. The XQuery functions and namespaces declared in an XQuery prolog in the JPD are not accessible to the XQueries in subscription control. This is an unsupported case when mixing two different XQuery versions in the same application. |
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.
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.
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.
This section describes the class and method attributes supported for the Subscription control.
{
parameter1
}
Callback method attributes include:
XmlObject
(or a typed XML Bean class).
XmlObject
(or a typed XML Bean class), String
, RawData
, or a non-XML MFL class (a subclass of MflObject
).
MB Subscription controls must be extended. The following is an example of a MB Subscription control file.
package requestquote;
import org.apache.beehive.controls.api.bean.ControlExtension;
import org.apache.beehive.controls.api.events.EventSet;
import org.apache.xmlbeans.XmlObject;
/*
* A custom Subscribe control.
*/
@ControlExtension
@SubscriptionControl.ClassSubscription(channelName = "/deadletter/xml")
public interface SubscriptionControl extends
com.bea.control.SubscriptionControl {
@SubscriptionControl.MethodSubscription(filterValueMatch = "{value}")
void subscribeWithFilterValue(String value);
@EventSet
interface Callback {
@SubscriptionControl.SubscriptionCallback(body = "{message}", metadata = "{metadata}")
void onMessage(XmlObject message, XmlObject metadata);
}
static final long serialVersionUID = 1L;
public SubscriptionControl create();
}
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.
Event generators publish messages to Message Broker channels. Oracle WebLogic Integration supports the following event generators: