TIBCO Rendezvous Control and Event Generator User Guide

TIBCO Rendezvous Control

TIBCO^® Rendezvous^{^TM} (a product from TIBCO: www.tibco.com) enables exchange of data across applications running on distributed platforms. TIBCO Rendezvous (TIBCO RV) Control in WebLogic Integration^{^TM} enables seamless connection to, and transfer of data using the Rendezvous daemon. It enables communication via many of the features provided by the TIBCO Rendezvous product, including Certified Message Delivery, Distributed Queue and so on. The sending and receiving applications can be on multiple platforms, as long as the Rendezvous daemon is running on the host machine, or is remotely accessible to the host.

Note: The TIBCO RV control is available in WebLogic Workshop^{^TM} only for licensed users of WebLogic Integration.

Disclaimer

Use of the TIBCO RV control and event generator with BEA WebLogic Integration in no manner confers or grants the right to use TIBCO Rendezvous including "dynamic libraries". In order to use such TIBCO products, the user of the TIBCO RV control and event generator must obtain a valid license from TIBCO. See http://www.tibco.com for information on how to obtain a licensed copy of Rendezvous.

Topics Included in This Section

Overview: Rendezvous Control

Describes the function of the TIBCO RV control within WebLogic Integration.

Creating and Configuring a New Instance of the TIBCO RV Control

Describes how to create and configure a new TIBCO RV control.

Using Subject in a Message

Describes how to set and retrieve the subject descriptor attributes of the message.

Sending and Receiving Messages

Describes the methods used to send and receive messages.

Setting Dynamic Properties

Describes how to modify the TIBCO RV control properties at run time.

Overview: Rendezvous Control

The TIBCO RV control enables WebLogic Integration business processes to send and receive messages in the Rendezvous environment. In this environment, the messages are conveyed using Rendezvous daemon (rvd) and Rendezvous agent (rva) transports.

Using the TIBCO RV control, you can send and receive messages in XML, String and TIBCO proprietary Rendezvous Message (TibrvMsg) formats. You can specify TIBCO RV control properties while configuring Rendezvous control or dynamically at run time. Following are some of the other features of TIBCO RV control:

Sending a request message and waiting for a reply
Sending a reply for a message
Asynchronous callback facility to confirm delivery or failure of certified messages
Registration of anticipated listeners

The TIBCO RV control complements the other controls provided in WebLogic Integration, and can be used with other WebLogic Integration business processes. To learn more, see Using Controls in Business Processes in Using Integration Controls, which is located at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/core/index.html.

The TIBCO RV event generator listens on a subject, and publishes the received messages to the WebLogic Integration message broker channels. For more information, see TIBCO Rendezvous Event Generator.

Creating and Configuring a New Instance of the TIBCO RV Control

You can create and configure a new instance of the TIBCO RV control and add it to your business process. This topic includes the following sections:

To Add a New TIBCO RV Control

Describes how to add a new TIBCO RV control.

To Specify TIBCO RV Control General Settings

Describes how to configure the general settings for the TIBCO RV control such as port id, host name and so on.

To Specify TIBCO RV Control Advanced Settings

Describes how to configure Certified Message settings for the TIBCO RV control.

To Add a New TIBCO RV Control

To add a new TIBCO RV control to WebLogic Integration, perform the following steps:

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, choose View—>Windows—>Data Palette from the menu bar.

Choose Integration Controls to display the list of controls used for integrating applications.

Choose TIBCO RV Control to display the Insert Control - TIBCO RV dialog as shown below.

Figure 1-1 Insert TIBCO RV Control Dialog - Step 1 & 2

Insert TIBCO RV Control Dialog - Step 1 & 2

In Step 1, in the Variable name for this control field, enter the name for your TIBCO RV control.

In Step 2, click the Create a new TIBCO RV control to use radio button.

Note: To use an existing TIBCO RV control, click the Browse button to select the JCX file from your system. When you use an existing TIBCO RV control, the properties that were originally selected for the existing control are populated in the JCX file. You cannot modify the properties using the Insert Control - TIBCO RV Control dialog. However, you can modify the dynamic properties at run time. For more information, see Setting Dynamic Properties.

In the New JCX name field, enter the name of the new file.

To make this a control factory select the Make this a control factory that can create multiple instances at runtime check box, otherwise clear the check box. For more information about control factories, see Control Factories: Managing Collections of Controls.

For details on Step 3, see To Specify TIBCO RV Control General Settings and To Specify TIBCO RV Control Advanced Settings.

Click Create.

To Specify TIBCO RV Control General Settings

To specify connection settings for the TIBCO RV control, perform the following tasks in Step 3 of the Insert Control - TIBCO RV dialog; the General Settings tab, as shown below:

Figure 1-2 Insert TIBCO RV Control Dialog - Step 3: General Settings

Insert TIBCO RV Control Dialog - Step 3: General Settings

In the Service field, enter the service name which the TIBCO RV daemon will use to convey the message.

In the Network field, enter the name of the network with which the TIBCO RV daemon will communicate. If no network is specified, the default network interface will be used.

In the Daemon field, enter the location where the TIBCO RV daemon is running to establish communication. If the TIBCO RV daemon is running on a different network, specify the remote_host:port_id details in the Daemon field. For example, beaserv1:1589 where beaserv1 is the remote host name and 1589 is the port id.

Click CM to select the Certified Messaging option.

To Specify TIBCO RV Control Advanced Settings

To specify certified messaging settings for the TIBCO RV control, perform the following tasks in Step 3 of the Insert Control - TIBCO RV dialog; the Advanced Settings tab, as shown below:

Figure 1-3 Insert TIBCO RV Control Dialog - Step 3: Advanced Settings

Insert TIBCO RV Control Dialog - Step 3: Advanced Settings

Click the Advanced tab, to display the advanced options for Certified Messaging. This tab is applicable only if you have selected the CM radio button in the General tab.

In the CM Name field, provide the CM transport name. The name identifies the CM transport to other CM transports, and is par of the CM label that identifies outbound messages from the CM transport.

In the Ledger Name field, provide the ledger name with its location. Each CM transport keeps a ledger, in which it records information about every unresolved outbound certified message, every subject for which this CM transport receives (inbound) certified messages, and other cooperating CM transports.

Click Retain Unacknowledged Messages radio button to store any unacknowledged messages as part of its decentralized architecture.

Click Synchronize Ledger radio button to perform a synchronized update of the ledger file. Each time the ledger is updated, the call does not return until data is safely written to the storage medium.

The JCX Files for a TIBCO RV Control

When you create a new instance of the TIBCO RV control, you create a new JCX file in your project. The contents of the TIBCO RV control's JCX file depends on the selections made in the Insert Control - TIBCO RV dialog.

The two examples in this section depict JCX files created for a certified message and a non-certified message.

Sample JCX File for a TIBCO RV Control Using Certified Messaging

package processes; 
import com.bea.control.*; 
import com.bea.xml.XmlCursor; 
import com.bea.control.tibrv.*; 
import javax.resource.ResourceException; 
import com.bea.xml.XmlObject; 
	/* 
	* A custom Tibrv control. 
	*/ 
	/** 
	* @jc:Transport service="7500" //<service name used by the TIBCO daemon for conveying messages> 
		network="beaserv1" //<network with which the TIBCO daemon will communicate> 
		deamon="beasever1:7500 " //<location where the TIBCO daemon is running> 
	* @jc:UseCM  usecm="true" //<indicates certified messaging enabled> 
	* @jc:CMTransport cmname="cmname.new" //<the certified message name> 
		ledgername="C:\TIBCO\TIBRV\Ledger.txt" //<name and location of the ledger file> 
		requestold="true" //<indicates any unacknowledged messages will be stored> 
		syncledger="true"//<performs synchronized update of the ledger file> 
	*/ 
public interface sendReq extends TibcoRV, com.bea.control.ControlExtension 
{ 
	/* 
	* A version number for this JCX. This will be incremented in new versions of 
	* this control to ensure that conversations for instances of earlier 
	* versions were invalid. 
	*/ 
	static final long serialVersionUID = 1L; 
	public void addListenerForCM(String cmName, String subject);
}

Sample JCX File for a TIBCO RV Control Without Certified Messaging

package processes; 
import com.bea.control.*; 
import com.bea.xml.XmlCursor; 
import com.bea.control.tibrv.*; 
import javax.resource.ResourceException; 
import com.bea.xml.XmlObject; 
	/* 
	* A custom Tibrv control. 
	*/ 
	/** 
	* @jc:Transport service="7500" //<service name used by the TIBCO daemon for conveying messages> 
		network="beaserv1" //<network with which the TIBCO daemon will communicate> 
		deamon="beasever1:7500 " //<location where the TIBCO daemon is running> 
	* @jc:UseCM  usecm="false" //<indicates certified messaging disabled> 
	* @jc:CMTransport cmname="" 
		ledgername="" 
		requestold="false" 
		syncledger="false" 
	*/ 
public interface sendReq extends TibcoRV, com.bea.control.ControlExtension 
{ 
	/* 
	* A version number for this JCX. This will be incremented in new versions of 
	* this control to ensure that conversations for instances of earlier 
	* versions were invalid. 
	*/ 
	static final long serialVersionUID = 1L; 
}

Using Subject in a Message

This section provides details on construction of a subject name. Each message in the TIBCO Rendezvous environment contains a subject name. An application creates a message and sends it with a subject through the Rendezvous environment. Applications at the other end accept the message by listening on the subject.

Subject Name Syntax

Subject name definitions have basic restrictions, for example, its length, structure and usage of special characters. System designers and developers can set the conventions for subject names keeping in mind the following:

Structure — A subject is a string of characters that is divided into elements by the dot (.) character.
Length — The maximum allocated length of a subject (including dot separators) is 255 characters, some of which is reserved for internal use by Rendezvous.
Special Characters —

Avoid underscore (_) character at the beginning of the subject name, except if the first element name is _INBOX or _LOCAL.
Avoid the dot (.) character as part of an element as it is the reserved delimiter.
Greater-than (>) and Asterisk (*) characters are reservoir wildcard characters.

Caution: The restrictions and conventions are implemented by TIBCO Rendezvous and information in this section is indicative only. Refer TIBCO Rendezvous product documentation for more up-to-date information on restrictions, guidelines and examples.

http://www.tibco.com

Sending and Receiving Messages

You can send and receive messages with TIBCO RV control using any one of sendMessage, sendReply or sendRequest functions, and the TIBCO Event Generator, respectively. Messages can be in the form of Rendezvous proprietary data format, string and XML.

Sending Messages

This section provides information on the various functions available for sending messages. To send a message, select a function based on the data type of the message that you want to send. All these functions can send reliable and certified messages, as defined while creating the control. Certified message functions will return sequence numbers while reliable message functions will return zero.

The sendRequest function creates a listener that keeps listening for messages to the reply subject and hence, it does not require explicit creation of listeners. The function returns an instance of the TibrvMsg, which can be used for sending replies.

The sendRequest and sendReply functions are often used together as pairs. An example of such an implementation is:

replymsg = sendRequest(msg, "send.Subject","reply.Subject",5.0);
sendReply( replyMsg, newMsg);

sendMessage ()

Used to send a message via RVDTransport, or a labelled message via CMTransport.

public long sendMessage(TibrvMsg msg , String subject, double timeout)

msg: the message that needs to be sent

subject: subject of the message

timeout: time limit for delivery of the message

sendMessageAsString ()

Used to send a string message via RVDTransport, or a labelled string message via CMTransport.

public long sendMessageAsString(String  msg , String fieldName ,String subject, double timeout)

msg: the string message that needs to be sent

fieldName: name of the TibRV field used to send the payload

subject: subject of the message

timeout: time limit for delivery of the message

sendMessageAsXML ()

Used to send an XML message via RVDTransport, or a labelled XML message via CMTransport.

public long sendMessageAsXML(XmlObject  msg ,String fieldName ,String subject, double timeout)

msg: the XML message that needs to be sent

fieldName: name of the TibRV field used to send the payload

subject: subject of the message

timeout: time limit for delivery of the message

sendRequest ()

Used to send a request message via RVDTransport, or a labelled request message via CMTransport and wait for a reply.

public TibrvMsg sendRequest(TibrvMsg msg, String sendSubject, double timeout)

msg: the request message that needs to be sent

sendSubject: the send subject of the message

timeout: amount of time to wait for the reply

sendRequestAsString ()

Used to send a request string message via RVDTransport, or a labelled request string message via CMTransport and wait for a reply.

public TibrvMsg sendRequestAsString(String msg, String fieldName, String sendSubject, double timeout)

msg: the request string message that needs to be sent

fieldName: name of the TibRV field used to send the payload

sendSubject: subject of the message

timeout: amount of time to wait for the reply

sendRequestAsXML ()

Used to send a request XML message via RVDTransport, or a labelled request message via CMTransport and wait for a reply.

public TibrvMsg sendRequestAsXML(XmlObject msg, String fieldName,String sendSubject, double timeout)

msg: the request XML message that needs to be sent

fieldName: name of the TibRV field used to send the payload

sendSubject: subject of the message

timeout: amount of time to wait for the reply

sendReply ()

Used to send a reply via RVDTransport, or a labelled reply via CMTransport.

public long sendReply(TibrvMsg replyMsg, TibrvMsg sendMsg, double timeout)

replyMsg: the reply message

sendMsg: the request message

timeout: time limit for delivery of the message

sendReplyAsString ()

Used to send a string type reply via RVDTransport, or a labelled string type reply via CMTransport.

public long sendReplyAsString(TibrvMsg replyMsg, String sendMsg, String fieldName, double timeout)

replyMsg: the reply string message

sendMsg: the request string message

fieldName: the name of the TibRV field used to send the payload

timeout: time limit for delivery of the message

sendReplyAsXML ()

Used to send an XML type reply via RVDTransport, or a labelled XML type reply via CMTransport.

public long sendReplyAsXML(TibrvMsg replyMsg, XmlObject sendMsg, String fieldName, double timeout)

replyMsg: the reply XML message

sendMsg: the request XML message

fieldName: the name of the TibRV field used to send the payload

timeout: time limit for delivery of the message

setStringEncoding ()

Used to set the character encoding for converting between Java Unicode strings and wire format strings.

void setStringEncoding(java.lang.String encoding) throws java.io.UnsupportedEncodingException;

encoding: determines encoding

Additional Functions for Certified Messaging

You can include the following two functions when using the CMTransport.

onCMMessageReceipt ()

Used to define a callback method to receive confirmation for message sent. It can only be used with sendMessage or sendReply functions. TIBCO RV control subscribes to two confirmation advisories: _RV.INFO.RVCM.DELIVERY.COMPLETE.> and _RV.ERROR.RVCM.DELIVERY.FAILED.>.

Note: A TIBCO RV control with certified messaging enabled must have an onCMReceipt() method implemented in the process definition. Without this, a runtime exception will be thrown.

public void onCMMessageReceipt(byte[] data);

data: message data

addListenerForCM ()

Used to pre-register an anticipated listener. When a sending application pre-registers listeners, Rendezvous will store all outbound messages in the sender's ledger. So, when the listener requests certified delivery, it receives the backlogged messages. This function is the same as the addListener method in Rendezvous. Refer TIBCO Rendezvous product documentation for more details.

void addListenerForCM(String cmName, String subject);

cmName: the certified message name

subject: subject of the message

Using the sendMessage Function In a Business Process

The following procedure in an example that describes how to add any TIBCO RV control sendMessage function to a business process.

Open the Client Request node, as shown in the following figure.

Figure 1-4 Defining a Method for SendMessage Function

Defining a Method for SendMessage Function

In the General Settings tab, enter a name for the new method.

Click Add, and select the Java check box in the pop-up dialog.

Select String from the Java Types list and enter a name for the variable in the Name field.

Click OK to add your selection to the Client Request node. This represents the message for the sendMessage function.

Repeat steps 3 to 5 above to add two more variables to the list. The new variables represent the field name and the subject name of the sendMessage function.

In the Receive Data tab, create a new variable for each parameter that you created in the General Settings tab of the Client Request node. You must provide variable names for all the parameters. The variable type is pre-defined, based on the parameters to which you are assigning the variable.

Close the Client Request node.

Drag and drop the Perform node from the Process Nodes Palette and convert the message data from String to TibrvMsg format. See sample code below:

// Generating a Tibrv message from the string data format 
public void perform() throws Exception 
{ 
   com.tibco.tibrv.TibrvMsg tibrvMsg = new com.tibco.tibrv.TibrvMsg(); 
   tibrvMsg.update(TibcoField,TibcoMessage); 
}

Drag and drop the sendMessage function from the Controls tab in the Data Palette into your business process, just below the Client Request node.

Open the Send Data tab of the sendMessage function node. From the Select variables to assign drop-down list, assign the variables that you created in the Receive Data tab of the Client Request node, to the corresponding parameter of the sendMessage function listed in the Control Expects column.

Open the Receive Data tab of the sendMessage function note. From the Select variables to assign drop-down list, create a new variable in which to store the sequence number provided by the sendMessage function.

You can use similar steps to send messages using the sendMessageAsString or the sendMessageAsXML functions. Ignore step 9 above as these functions do not require conversion to TibrvMsg format.

Receiving Messages

To receive messages, use the TIBCO RV Event Generator utility. For details, refer TIBCO Rendezvous Event Generator.

Setting Dynamic Properties

You can change the TIBCO RV control properties dynamically at runtime. The TIBCO RV control properties that you can modify are specified in the TibRVDynamicPropertiesDocument type document. This document conforms to the TIBCO RV Control Dynamic Properties schema, which is available in the TibRVSchemas.jar file.

The following is an example on how to change properties dynamically.

Open the Client Request node, as shown in the following figure.

Figure 1-5 Defining a Method Using Dynamic Properties

Defining a Method Using Dynamic Properties

In the General Settings tab, add a variable of type TibRVDynamicPropertiesDocument.

In the Receive Data tab, create a new variable for the parameter that you previously created in the General Settings tab by entering a name for the variable. The variable type is already pre-defined based on the parameter to which you are assigning the variable.

Drag and drop the setXMLProperties function from the Controls tab of the Data Palette, into your business process.

Open the Send Data tab of the setXMLProperties function node. From the Select variables to assign drop-down list, assign the variable that you created in the Receive Data tab of the Client Request node to the corresponding parameter of the setXMLProperties function listed in the Control Expects column. All TIBCO RV Control send message operations (following the setXMLProperties function in the business process) using the properties you specified in the TibRVControlDynamicPropertiesDocument.

While executing your business process at runtime, provide the TibRVControlDynamicPropertiesDocument as input.

Schema of TIBCO RV Control Dynamic Properties

<?xml version="1.0"?>
<xs:schema
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns="http://www.bea.com/wli/control/TibRVControlDynamicProperties.xsd"
targetNamespace="http://www.bea.com/wli/control/TibRVControlDynamicProperties.xsd"
   elementFormDefault="qualified"
   attributeFormDefault="unqualified">
   <xs:element name="TibRVDynamicProperties">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="service" type="xs:string" minOccurs="0" maxOccurs="1"/>
            <xs:element name="network" type="xs:string" minOccurs="0" maxOccurs="1"/>
            <xs:element name="daemon" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="useCM" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <xs:element name="cmName" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="ledgerName" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="requestOld" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
      <xs:element name="syncLedger" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample TIBCO RV Control Dynamic Properties Document

The following is a sample TIBCO RV Control document. You must provide this document at runtime when you execute your business process:

<tib:TibRVDynamicProperties>
   <!--Optional:-->
   <tib:service>7500</tib:service>
   <!--Optional:-->
   <tib:network>beaserv1</tib:network>
   <!--Optional:-->
   <tib:daemon>beaserv1:7500</tib:daemon>
   <!--Optional:-->
   <tib:useCM>true</tib:useCM>
   <!--Optional:-->
   <tib:cmName>cmname.runtime</tib:cmName>
   <!--Optional:-->
   <tib:ledgerName>c:/file.txt</tib:ledgerName>
   <!--Optional:-->
   <tib:requestOld>false</tib:requestOld>
   <!--Optional:-->
   <tib:syncLedger>false</tib:syncLedger>
   </tib:TibRVDynamicProperties>