|
|
The WLI JMS control is available in BEA WorkSpace Studio only if you are licensed to use WebLogic Integration.
JMS (Java Message Service) is a Java API for communicating with messaging systems. Messaging systems are often packaged as products known as Message-Oriented Middleware (MOMs). WebLogic Server includes built in messaging capabilities via WebLogic JMS, but can also work with third-party MOMs. Messaging systems are often used in enterprise applications to communicate with legacy systems, or for communication between business components running in different environments or on different hosts.
The WLI JMS control enables BEA WorkSpace Studio business processes to easily interact with messaging systems that provide a JMS implementation. A specific WLI JMS control is associated with particular facilities of the messaging system. Once a WLI JMS control is defined, business processes may use it like any other WebLogic Workshop control.
The WLI JMS control provides additional features such as RawData message type support, dynamic property configuration, and the ability to control whether to start a new transaction or remain within the calling transaction. You can use the JMS Event Generator to poll for and consume messages produced by the WLI JMS control.
For information on how to add control instances to business processes, see Using Controls in Business Processes.
This topic describes the characteristics of messaging systems that are accessible via JMS (Java Message Service), and therefore via the WLI JMS control.
To learn about the WLI JMS control, see WLI JMS Control.
To learn about specific messaging scenarios that are supported by the WLI JMS control, see Messaging Scenarios Supported by the WLI JMS Control.
Messaging systems provide communication between software components. A client of a messaging system can send messages to, and receive messages from, any other client. Each client connects to a messaging server that provides facilities for sending and receiving messages. WebLogic JMS, which is a component of WebLogic Server is an example of a messaging server. WebLogic Server also supports third party messaging systems.
Messaging systems provide distributed communication that is asynchronous. A component sends a message to a destination. A message recipient can retrieve messages from a destination. The sender and receiver do not communicate directly. The sender only knows that a destination exists to which it can send messages, and the receiver also knows there is a destination from which it can receive messages. As long as they agree what message format and what destination to use, the messaging system will manage the actual message delivery.
Messaging systems also may provide reliability. The specific level of reliability is typically configurable on a per-destination or per-client basis, but messaging systems are capable of guaranteeing that a message will be delivered, and that it will be delivered to each intended recipient exactly once.
JMS supports two basic styles of message-based communications: point-to-point and publish and subscribe.
Point-to-point messaging is accomplished with JMS queues. A queue is a specific named resource that is configured in a JMS server.
A JMS client, of which the WLI JMS control is an example, may send messages to a queue or receive messages from a queue. Point-to-point messages have a single consumer. Multiple receivers may listen for messages on the same queue, but once any receiver retrieves a particular message from the queue that message is consumed and is no longer available to other potential consumers.
A message consumer acknowledges receipt of every message it receives.
The messaging system will continue attempting to resend a particular message until a predetermined number of retries have been attempted.
Publish and subscribe messaging is accomplished with JMS topics. A topic is a specific named resource that is configured in a JMS server.
A JMS client, of which the WLI JMS control is an example, may publish messages to a topic or subscribe to a topic. Published messages have multiple potential subscribers. All current subscribers to a topic receive all messages published to that topic after the subscription becomes active.
Before a JMS client can send or receive messages to a queue or topic, it must obtain a connection to the messaging system. This is accomplished via a connection factory. A connection factory is a resource that is configured by the message server administrator. The names of connection factories are stored in a JNDI directory for lookup by clients wishing to make a connection.
There is a default connection factory pre-configured in WebLogic Workshop, named cgConnectionFactory. This connection factory is used for all WLI JMS controls that do not explicitly override it. If you use a connection factory other than the default connection factory, the factory must have the following setting:
userTransactionsEnabled="true"
The components of a JMS message are as follows: a set of standard header fields, a set of application-specific properties, and a message body. Every JMS message contains a standard set of header fields that is included by default and available to message consumers. Some fields can be set by the message producers. The property fields of a message contain header fields added by the sending application. The properties are standard Java name/value pairs. A message body contains the content being delivered from producer to consumer. You can manipulate the content of these components using the following annotations:
This topic describes specific messaging scenarios that are supported by the WLI JMS control.
To learn more about JMS, the Java Message Service, see Overview: Messaging Systems and JMS.
To learn more about the WLI JMS control, see WLI JMS Control.
The JMS specification supports a wide variety of messaging scenarios. Some scenarios that are possible in standalone applications are not possible in the BEA WorkSpace Studio environment due to the nature of web services.
The messaging scenarios in the following sections are supported by the WLI JMS control. For descriptions of messaging scenarios that are not supported by the WLI JMS control, see Messaging Scenarios Not Supported by the WLI JMS Control.
A business process, via a WLI JMS control, may send messages to a JMS queue. The business process will not receive a reply. The queue must exist and be registered in the JNDI registry. The administrator who configures the target JMS queue determines the delivery guarantee policies.
To implement this example scenario:
send-jndi-name attribute of the WLI JMS control's @com.bea.control.JMSControl.JMS annotation. Also, specify the sendtype attribute as queue. To learn how to create a WLI JMS control, see
Creating a WLI JMS Control.A business process, via a WLI JMS control, may send messages to one queue and receive reply messages on another queue. A single WLI JMS control may have both send and receive queues configured, and business processes may then send and receive via the same control.
| Note: | Two-way messaging requires correlation of every received messages with the instance of the business process that sent the original outgoing message. The WLI JMS control ensures that the conversation ID of the sender is sent on the send_correlation_property of the outgoing message. To learn more about message correlation, see the explanation of the send-correlation-property and receive-correlation-property attributes in
JMSControl.JMS Annotation. |
To implement this example scenario:
send-jndi-name attribute of the JMS control's @ annotation. Also, specify the send-type attribute as queue. receive-jndi-name attribute of the WLI JMS control's @com.bea.control.JMSControl.JMS annotations. Also, specify the receivetype attribute as queue.receiveTextMessage, receiveBytesMessage, receiveObjectMessage or receiveRawMessage depending on the message type selected when the control was created); or a custom callback you have defined for the WLI JMS control.A business process, via a WLI JMS control, may publish messages to a JMS topic. The business process will not receive a reply. The topic must exist and be registered in the JNDI registry.
To implement this example scenario:
send-jndi-name attribute of the WLI JMS control's @com.bea.control.JMSControl.JMS annotation. Also, specify the sendtype attribute as topic. sendTextMessage, sendBytesMessage, sendObjectMessage or sendRawMessage depending on the message type selected when the control was created); or a custom method you have defined for the WLI JMS control.A business process, via a WLI JMS control, may subscribe to messages on a JMS topic. The topic must exist and be registered in the JNDI registry. Only messages sent after the business process has subscribed to the topic will be received.
To implement this example scenario:
receivejndiname attribute of the WLI JMS control's @com.bea.control.JMSControl.JMS annotation. Also, specify the receivetype attribute as topic.receiveTextMessage, receiveBytesMessage, receiveObjectMessage or receiveRawMessage depending on the message type selected when the control was created); or a custom callback you have defined for the WLI JMS control.
This topic describes specific messaging scenarios that are not supported by the WLI JMS control.
To learn more about the WLI JMS control, see WLI JMS Control.
The JMS specification supports a wide variety of messaging scenarios. Some scenarios that are possible in standalone applications are not possible in the BEA WorkSpace Studio environment due to the nature of web services.
The messaging scenarios in the following section are not supported by the WLI JMS control. For descriptions of messaging scenarios that are supported by the WLI JMS control, see Messaging Scenarios Supported by the WLI JMS Control.
A business process may not, via a WLI JMS control, specify a receive queue and subsequently receive unsolicited messages from that queue.
A business process must be performing work on behalf of a specific client and, in asynchronous situations, as part of a specific conversation. When an unsolicited messages is received from a queue, it is not possible for the WLI JMS control to determine the appropriate conversation or client with which to correlate unsolicited incoming messages.
| Note: | You may receive unsolicited messages in a business process via the JMS Event Generator and the Message Broker capabilities. To learn how to use the Message Broker controls and the JMS Event Generator, see Message Broker Controls. |
This topic describes how to create a new WLI JMS control.
To learn about WLI JMS controls, see WLI JMS Control.
You can create a new WLI JMS control and add it to your business process. To define a new WLI JMS control:
" id="wp1103119"/> 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 WorkSpace Studio, click Window > Show View > Data Palette from the menu bar. |
The Insert control: WLI JMS dialog box appears (see Figure 16-1).
The Insert control- JMS dialog-box appears (see Figure 16-2).
To learn about the methods available on the WLI JMS control, see the Interface WliJMSControl.
When you create a new WLI JMS control, you create a new Java file in your project. The following is an example Java file:
package requestquote;
@org.apache.beehive.controls.api.bean.ControlExtension
@com.bea.control.JMSControl.JMS(sendtype = com.bea.control.JMSControl.Type.queue, sendjndiname = "l", receivetype = com.bea.control.JMSControl.Type.queue, receivejndiname = "l", connectionfactoryjndiname = "o")
public interface WLIJMSCntrl extends com.bea.control.WliJMSControl {/**
* this method will send a javax.jms.TextMessage to sendJndiName
*/
public void sendTextMessage(String payload);
/**
* If your control specifies receiveJndiName, that is your JWS expects to receive
* messages from this control, you will need to implement callback handlers.
*/
@org.apache.beehive.controls.api.events.EventSet(unicast = true)
interface Callback extends com.bea.control.WliJMSControl.Callback {/**
* Define only 1 callback method here.
*
* This method defines a callback that can handle text messages from receiveJndiName
*/
public void receiveTextMessage(String payload);
}
static final long serialVersionUID = 1L;
public WLIJMSCntrl create();
}
The Java file contains the declaration of a Java interface with the name specified in the dialog. The interface extends the control base interface. Invoking any method in the Java interface, other than the callback, results in a JMS message being sent to the specified queue or topic.
The contents of the WLI JMS control's Java file depend on the selections made in the Insert WLI JMS dialog. The example above was generated in response to selection of Text/XML Bean as the Message type drop-down list.
Most aspects of a WLI JMS control can be configured from the JPD Configuration pane in Design view. These properties are encoded in the JMS control's Java file as attributes of the @com.bea.control.JMSControl.JMS annotations. To retrieve current parameter settings, use the getControlProperties() method (this is a different method from the getProperties() method on the base JMS control which is used to get the JMS properties of the last message received.)
For more information about the JMSControl:JMS annotation and its attributes, see
JMSControl:JMS Annotation.
Two queues are configured when BEA WorkSpace Studio is installed, in order to support WLI JMS control samples. These are named SimpleJmsQ and CustomJmsCtlQ. The connection factory that provides connections to these queues has the JNDI name weblogic.jws.jms.QueueConnectionFactory. These resources may be used for experimentation.
| Note: | Every WLI JMS control deployed on a server should listen on a unique queue. If multiple WLI JMS controls on the same server are simultaneously listening on the same queue, the results may be unpredictable, for more information see WLI JMS Control Caveats. |
Within a WLI JMS control, you may define multiple methods and one callback. All methods will send or publish to the queue or topic named by send-jndi-name, if present.
JMS defines several message types that may be sent and or published. The WLI JMS control can send the JMS message types TextMessage, ObjectMessage, BytesMessage, and JMSMessage. The WLI JMS control dynamically determines which type of message to send based on the configuration of the WLI JMS control method that was called. XML Object and XML typed variables use the text/XMLBean message type.
| Note: | You can send or receive any message type through send and receive methods that take a javax.jms.Message argument. (All message types extend javax.jms.Message.) To send an ObjectMessage, for example, call myControl.getSession() to get the JMS session, then call session.createObjectMessage(), and then send the message. |
If the WLI JMS control method takes a single String or XMLObject argument, a javax.jms.TextMessage is sent.
If the WLI JMS control method takes a single argument of type java.lang.Object, a javax.jms.ObjectMessage is sent.
If the WLI JMS control method takes a single argument of type javax.jms.BytesMessage, a javax.jms.BytesMessage is sent.
If the WLI JMS control method takes a single argument of type javax.jms.Message, a JMS Message object is sent directly.
To edit the parameter list controlling the message headers and message properties, display the control in the Design view, select a method, and edit the parameters using the JPD Configuration pane. You can set parameters programatically using the setProperties() method. To display current parameter settings, use the getControlProperties() method.
You can send additional properties using key-values pairs, using the annotation @com.bea.control.JMSControl.JMS -property for each pair. You can also edit the parameters directly in the Source view.
The JNDI names specified for send-jndi-name, receive-jndi-name and connection-factory may refer to remote JMS resources. The fully specified form of a JMS resource names is:
jms:{provider-host}/{factory-resource}/
{dest-resource}?{provider-parameters}jms://host:7001/cg.jms.QueueConnectionFactory/
jws.MyQueue?URI=/drt/Bank.jws
jms://host:7001/MyProviderConnFactory/
MyQueue?SECURITY_PRINCIPAL=foo&SECURITY_CREDENTIALS=bar
Bear in mind the following caveats when you work with WLI JMS controls:
receive-jndi-name for a queue, you must use the receive-selector attribute such that the web services partition all received messages into disjoint sets. If this is not handled properly, messages for a particular conversation may be sent to a control instance that does not participate in that conversation. Note that if you rename a web service that uses a JMS control without undeploying the initial version, the initial version and the new version will be using an identically configured WLI JMS control and will violate this caveat.receiveTextMessage, receiveBytesMessage, receiveObjectMessage or receiveJMSMesage, or a developer-defined callback). getControlProperties() method used to get WLI JMS control properties and the getProperties() method on the base JMS control which is used to get the JMS properties of the last message received.JMSControl.onMessage method. This will cause the current transaction to be rolled back. The behavior after that depends on how the administrator set up the JMS destination. Ideally, it should be set up to have a small retry count and an error destination.| Note: | If the destination is configured with a large (or no) retry count and no error destination, the WLI JMS control infrastructure will continue attempting to process the the message (unsuccessfully) forever. For information on setting the redelivery limit, see “ Programming WebLogic JMS”. |
|