TIBCO Rendezvous Control

TIBCO^® Rendezvous^™ (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^™ 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.

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

Creating and Configuring a New Instance of the TIBCO RV Control

Using Subject in a Message

Sending and Receiving Messages

Setting Dynamic Properties

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:

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.

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 the 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

To Specify TIBCO RV Control General Settings

To Specify TIBCO RV Control Advanced Settings

To Add a New TIBCO RV Control

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

In the Package Explorer pane, double-click the business process (Process.java file) to which you want to add the Tibco 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 Tibco.

The Insert control: Tibco dialog box appears.

In the Insert control: Tibco dialog box enter the following details:

In the Field Name, type the variable name used to access the new Tibco 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 insertion node, you want to add the control.
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.
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- Tibco RV dialog-box appears.

In the Insert control- Tibco RV dialog box enter the following details:

To Specify TIBCO RV Control 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, (see Figure 14-1) below:

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 Java Files for a TIBCO RV Control

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

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

Sample control 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 control. 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 control 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 control. 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.

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:

sendMessage ()

sendMessageAsString ()

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

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.

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.

sendRequestAsString ()

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

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.

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 ()

sendReplyAsString ()

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

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.

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.

Additional Functions for Certified Messaging

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.>.

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.

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.
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

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.

Open the Client Request node.
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>