Downloads |
 Feedback
|
Table Of Contents
About Subject Names and Event Formats
How Subject Names are Structured
Choosing Subject Names and Namespaces
Using the Lightweight Messaging Service
About Tibco-LWMS Gateway Support
Posting a Message to a Mailbox with LWMS
Polling Mailboxes for New Messages with LWMS
Removing a Message Listener with LWMS
Creating a Mailbox with JMS APIs
Posting a Message to a Mailbox with JMS
Polling Mailboxes for New Messages with JMS
Removing a Message Listener with JMS
LWMS Native API Messaging Methods
Using Event Services Software
Event Services Software (ESS) is an asynchronous messaging service that provides a messaging infrastructure based on a publish-and-subscribe paradigm. It enables distributed, loosely coupled interprocess communications.
ESS is one of two event messaging components supplied with CWCS. The other - the Event Distribution System (EDS) - is a means for sending messages from one process to another in a distributed, networked environment. These two components are disjoint systems and do not work together.
Note
ESS is the preferred messaging service. EDS (see Chapter 21, "Using the Event Distribution System") has been deprecated, and support for it will be withdrawn in a future CWCS release. Cisco urges developers to avoid new development with EDS and begin using ESS as soon as possible.
The following topics explain ESS and how to use it:
•
•
Understanding ESS Subsystems
The two main subsystems of ESS are Tibco's Rendezvous and the Lightweight Messaging Service (LWMS). Both contain implementations of the Java Messaging Service (JMS) API.
For information on using Tibco's Rendezvous, see the "Using Tibco's Rendezvous" section. For information on using LWMS, see the "Using the Lightweight Messaging Service" section .
How Does ESS Work?
Messages are asynchronous requests, reports, or events that contain precisely formatted data that describe specific actions, queries, or declarations. Through the exchange of these messages, applications with distributed processes in a networked environment can coordinate with and track the progress of other applications in the network. Messaging services are synonymous with event services.
Messages are published to subjects. An event bus is the logical channel that carries these messages. These messages are sent with a specified message format:
SubjectTIBCO = TopicJMS = MailboxLWMS
Subjects are essentially logical message addresses that provide a virtual connection between distributed processes. Subscribers register listeners on subjects and receive asynchronous callbacks as messages arrive. Publish/subscribe messaging is considered loosely coupled because publishers and subscribers may be anonymous and the data to be shared between the distributed processes is formatted into messages that provide a type of buffering mechanism.
A publisher simply pushes a message to a subject name and does not generally know or care who or how many subscribers receive its message. Similarly a subscriber generally does not know what process or processes are sending messages on a given subject. This architecture allows a great deal of flexibility for future changes since it makes few assumptions on who, where, when or how another process will use an event.
Developers need to create unique subject names. In order to decide what their project's namespace should be, you need to know the current recommendation which provides a segregation of subject names so you can independently decide the subject names for your applications without colliding with different application subject names. For recommendations and more information on subject names, see Next Generation Foundation Event Services (ESS) Developer's Guide (ENG-112035).
How Is ESS Organized?
The ESS architecture is divided into two main subsystems:
•
•
A gateway between the SEB and CEB transparently and automatically forwards messages between the two event buses.
If you need additional information on these ESS subsystems, see Event Services Software (ESS) Primer and Overview in EDCS (ENG-110601).
Using Tibco's Rendezvous
Application developers must use Tibco's Rendezvous product to communicate between backend processes such as your application's processes and other interested processes. The TibcoRV version 7.1 is used for this release of CiscoWorks Common Services.
For more information, see:
•
•
•
About Subject Names and Event Formats
This section contains the following topics:
•
•
How Subject Names are Structured
This section explains the general structure of Subject names. For specific recommendations, see the "Choosing Subject Names and Namespaces" section.
Each subject name is a dotted string. For example, cisco.mgmt.vms.vhm.alarm.voiceGateway.
The subject namespace forms a hierarchical structure with a prefix portion (the first three dotted elements) that is centrally administered by CANA (Cisco Assigned Numbers Authority). This is mainly to avoid namespace collisions. The remaining part of the subject name is defined by application developers, as shown here:
cisco.mgmt.<systemId>.<subsystemId>...<eventClass>.<topic>cisco.mgmt.<systemId>.<subsystemId>...<eventClass>.<eventSubclass>.<topic><--CANA Registered--> <------------organization defined--------------->The subsystemId element identifies the subsystem within the management server.
The eventClass element can be used to define a general class of events used within an application. For consistency we will track the event class element names used within EMBU and reuse them whenever possible. For more on Event Classes, see.
The eventSubclass element, if present, can be used if there are a large number of events in the event class and further partitioning would be helpful.
The final element topic should be used to identify as clearly as possible the type of events that will be published on the complete subject name.
Choosing Subject Names and Namespaces
Follow the subject namespace guidelines shown in Table 20-1 to decide on a subject name that will not cause your application's subject name to collide with other applications.
These guidelines take into account the fact that events may be used for communication in a variety of environments, including between components or services:
a.
b.
c.
d.
For example, multiple servers on the same subnet, all with ESS-based network management applications installed on them, can pose a problem for situations like that in (a) above, if broadcast is used instead of multicasting. Unless subject names are chosen carefully, events from one product may be passed to another product on a different server unintentionally. One way to prevent this is to include the IP address of the server in the subject name. If this convention is adopted, each product can subscribe to messages from the services on the same server only.
When choosing subject names, be aware of the following:
•
•
•
•
•
Subscribing with Wildcards
Tibco Rendezvous supports two wildcard characters: the asterisk (*) and greater-than symbol (>). The * character matches one single whole element, but not a partial substring of characters, within an element. The > character matches one or more trailing elements to the right. The semantics of listening to wildcard subjects are shown in Table 20-2.
Table 20-2 Wildcard Subject Semantics1
RUN.*
RUN.AWAY
RUN.away
RUN.run.run( extra element)
Run.away (case differs)
RUN (missing element)
Yankees.vs.*
Yankees.vs.Red_Sox
Yankees.vs.Orioles
Giants.vs.Yankees (position)
Yankees.beat.Sox (beat used instead of vs2 )
Yankees.vs (missing element)
*.your.*
Amaze.your.friends
Raise.your.salary
Darn.your.socks
your (missing elements)
pick.up.your.foot (position)
RUN.>
RUN.DMC
RUN.RUN.RUN
RUN.SWIM.BIKE.SKATE
SWIN.RUN (position)
Run.away (case differs)
RUN (missing element)
1 This table is taken from the Tibco/RV Concepts Manual.
2 LWMS also supports subscriptions with wildcard characters with the single limitation that the publisher must be on the SEB Tibco/Rv side of the event bus.
About ESS Event Formats
ESS supports two types of message body content:
•
•
About Reserved Subject Names
The following Subject Names are in use and reserved by NMTG:
•
–
–
•
–
–
–
–
–
–
•
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
–
Support for Map Messages
From Common Services 3.0 Service Pack 1, map messages are supported. Publish and subscribe can happen via map messages. A map message is a message whose body contains a set of name-value pairs where names are Strings and values are Java primitive types. This map message feature is not supported for LWMS and JMS.
Sample code for Map message Publisher:
import com.cisco.nm.cmf.jms.*;import java.io.*;import javax.jms.*;public class EssJtibMapPub{private static String subject = "cisco.mgmt.cw.cmf.jrm";private TopicConnectionFactory Factory;private TopicConnection conxn;private Topic topic;private TopicSession session;private TopicPublisher publisher;private MapMessage msg;public static void main(String args[]){new EssJtibMapPub().start();}private void start(){try{Factory = new TopicConnectionFactoryImp();conxn = Factory.createTopicConnection();session = conxn.createTopicSession(false,javax.jms.Session.AUTO_ACKNOWLEDGE);topic = session.createTopic(subject);publisher = session.createPublisher(topic);msg =session.createMapMessage();msg.setString("map","I am a Tibco MAP message !!!!!.");msg.setJMSReplyTo(new TopicImp("mapreply"));msg.setJMSDestination(topic);msg.setJMSPriority(7);publisher.publish(msg);}catch(Exception ex){ ex.printStackTrace();};}}Sample code for Map message Subscriber:
import java.io.*;public class EssJtibMapSub implements javax.jms.MessageListener {private static String subject = "cisco.mgmt.cw.cmf.jrm";private static boolean isFileBased = true;private javax.jms.TopicConnectionFactory Factory;private javax.jms.TopicConnection conxn;private javax.jms.Topic topic;private javax.jms.TopicSession session;private javax.jms.TopicSubscriber subscriber;public static void main(String args[]){new EssJtibMapSub().start();}private void start(){try{Factory = new com.cisco.nm.cmf.jms.TopicConnectionFactoryImp();conxn = Factory.createTopicConnection();session = conxn.createTopicSession(false,javax.jms.Session.AUTO_ACKNOWLEDGE);topic = session.createTopic(subject);subscriber= session.createSubscriber(topic);subscriber.setMessageListener(this);conxn.start();}catch(Exception ex) { ex.printStackTrace();};}public void onMessage(javax.jms.Message msg){javax.jms.MapMessage mapmsg;try{if (!(msg instanceof javax.jms.MapMessage) ) return;mapmsg = (javax.jms.MapMessage)msg;String map_msg = mapmsg.getString("map");return;}catch( Exception ex ) { ex.printStackTrace(); }}}Using the Lightweight Messaging Service
The Lightweight Messaging Service (LWMS) is a light weight XML-based messaging service used primarily between client desktops and the Common Services server. The client desktops are authenticated before sending messages.
The LWMS service provides:
•
•
•
•
•
–
–
•
•
•
–
–
The following topics describe the Lightweight Messaging Service and how to use it in your applications:
For more information, see:
•
•
•
Understanding LWMS
The following topics describe the components and features of the Lightweight Messaging Service (LWMS):
About the LWMS Components
LWMS consists of two main components:
•
•
Two more components provide additional services:
•
•
Figure 20-1 shows how all of these components work together.
Figure 20-1 LWMS Usage Example
How LWMS Works
LWMS supports three primary operations:
1.
2.
3.
An LWMS mailbox may have one or more senders and one or more receivers; internally, LWMS makes no distinctions between these usage types. A named mailbox simply receives messages sent to it, time stamps and ages them according to the time-to-live (TTL) field in each message, and forwards copies of new messages to each polling client.
Each LwmsClient keeps track of the last message it has seen for a given mailbox. On subsequent polls only messages later than this are forwarded to the client.
About LwmsClient
To provide the client interface for creating mailboxes and sending and receiving messages, the LwmsClient:
•
•
•
•
–
–
–
–
•
–
–
–
–
About LwmsServer
To handle message distribution, the LwmsServer:
•
•
•
About LwmsMailbox
The LwmsMailbox component stores and manages messages and handles message forwarding. An LwmsMailbox:
•
•
•
Each LwmsClient keeps track of the latest time stamp it has seen for a given mailbox. On subsequent polls, only messages later than this time stamp are forwarded to its client.
•
An LwmsMailbox may have one or more senders and one or more receivers.
About LwmsMessage
The LwmsMessage component simplifies and controls the creation of XML messages. The body of an LwmsMessage may be either:
•
•
LwmsMessage supports extensible message header elements via the msg.addHeaderElement( ) class. For example:
msg.addHeaderElement("deviceType", "Cat6000");In this example, the client application could perform filtering operations based on the contents of the message header.
For more information about LWMS message formats, see CMF Lightweight Messaging Service (LWMS) Functional Specification, ENG-58367.
About LWMS Message Queues
LWMS supports two priority levels for sending messages:
•
•
By default there is only one high priority push thread per LWMS client, which preserves the message sending order. If, however, there is more than one thread, high-priority messages may be received out of order. Multiple high priority pusher threads are recommended when higher throughput performance is required (see the "Configuring Client Properties" section).
Note
About JMS API Support
LWMS supports messaging via the Java Messaging Service API, Version 1.0.2. For a list of the subset of JMS services that LWMS supports, see the "JMS to LWMS Mappings" section.
About LWMS Server Logging
The LWMS Server outputs exceptions and important status information to the file lwms.log in the CWCS log directory.
About LWMS Usage Assumptions
LWMS was designed to meet the following usage limits:
•
•
•
About Tibco-LWMS Gateway Support
LWMS implements the Client Event Bus (CEB) in the CWCS event architecture. There is also a Server Event Bus (SEB) which is currently implemented by Tibco's Rendezvous product.
When messages need to transit on both the CEB and the SEB buses, a gateway is required between LWMS and Tibco. The gateway handles message traffic in both directions:
•
LWMS provides control messages on a specified topic that notify the gateway about the topics in the LWMS bus that have active listeners. The gateway forwards messages published on these topics on the Tibco bus to LWMS.
Control messages are sent to the gateway when:
–
–
•
The gateway subscribes to a special topic that will forward all messages published in the LWMS domain. This special topic is designed to prevent messages that were published earlier by the gateway from echoing back to the gateway. This is similar to the JMS NoLocal option.
Configuring LWMS
Two configuration files are loaded at startup to provide operating properties to LWMS. The following topics describe how to modify these files to configure your LWMS implementation:
•
•
Configuring Client Properties
To configure the LWMS client properties, use an ASCII editor to edit the LwmsClientProperties file.
The client properties file uses the tags shown in Table 20-3.
Example 20-1 shows a typical LWMS client configuration file.
Example 20-1 LWMS Client Configuration File
<?xml version="1.0"?><lwmsClientProperties><serverPollInterval VALUE="1500" /> # server mailbox polling interval in ms<normalMsgPushInterval VALUE="1000" /> # push normal messages to server, in ms<numHighPriorityPusherThreads VALUE="1" /> # set to 1 to preserve message order.# Higher values may increase throughput<maxHighPriorityMsgQueueSize VALUE="500" /> # next sender is blocked if queue is full<useGZIPioStreams VALUE="false" /> # compress applet-servlet streams</lwmsClientProperties>
Note
Configuring Server Properties
To configure the LWMS Server properties, use an ASCII editor to edit the LwmsServerProperties file.
The server properties file uses the tags shown in Table 20-4.
Example 20-2 shows a typical LWMS Server configuration file.
Example 20-2 LWMS Server Configuration File
<?xml version="1.0"?><lwmsServerProperties><msgAgeingInterval VALUE="60" /><tempMailboxAgeingInterval VALUE="30" /><maxMsgsPerPoll VALUE="500" /><autoCreateMailboxes><create NAME="cisco.mgmt.ani.event" TTL="0" /><create NAME="JmsTestTopic" TTL="0" /></autoCreateMailboxes></lwmsServerProperties>
Note
Using the LWMS API
The following topics describe how to use the native LWMS API to perform typical messaging tasks:
•
•
•
Creating a Mailbox with LWMS
Use the following code to get a reference to an LwmsClient singleton object and create a mailbox:
import com.cisco.nm.cmf.lwms.*;LwmsClient lc= LwmsClient.getInstance( "http://server:1741",cookie_value,user,is_cli );lc.createMailbox("mbox");Posting a Message to a Mailbox with LWMS
To create a message in LWMS, set the message properties and send the message:
LwmsMessage msg = new LwmsMessage();msg.setToMailbox ("mbox");msg.setMsgBody("Hello Gang");lc.sendMsg(msg);To get a reply, add these lines:
•
lc.createMailbox("Replymbox");•
msg.setReplyTo("Replymbox");•
lc.addMsgListener("Replymbox", this);Polling Mailboxes for New Messages with LWMS
To register a message listener with LWMS:
lc.addMsgListener("mbox", this);where the current object:
•
•
Removing a Message Listener with LWMS
To unregister a message listener with LWMS:
void removeMsgListener(String mailbox, LwmsMsgListener msgListener);Filtering Messages with LWMS
An LWMS message consumer may optionally specify a message filter for each mailbox at listener registration time. This filter has the form of a Boolean expression containing equality, relational, or logical operators. Each message that evaluates to true based on the filter criteria will be returned to the listener. Filters check only the standard and extended headers.
Table 20-5 summarizes the filter operator types LWMS supports.
Base Filter Expression (bfe) Syntax
The base filter expression uses this format:
match_string operator literal_valuewhere:
•
•
–
–
•
–
–
•
For example, a subscriber with
filter = "<foo> = `bar'"would receive messages with an extended header <foo>bar</foo>.
•
For example, a subscriber with
filter = "<foo VALUE= < 7"would receive messages with an extended header of <foo VALUE="5"/> (or any value less than 7).
•
•
•
Filter Strings Syntax
Filter strings supplied to the listener registration call use this syntax:
String filter= "bfe [AND bfe | OR bfe]";where:
•
•
Evaluation Rules
LWMS evaluates filter rules as follows:
•
•
Sample Filters
Here are two separate examples of typical filters:
String filter_1= "<from> = `AniServer'";String filter_2= "<deviceType> = `Cat6000' AND <deviceResets> > 5";Using the JMS API
The following topics describe how to use the JMS APIs to perform typical messaging tasks:
•
•
•
•
Creating a Mailbox with JMS APIs
To start a connection and a session and get a topic publisher using the JMS API:
import com.cisco.nm.cmf.lwms.jms.*;import javax.jms.*;TopicConnectionFactory tcf=new TopicConnectionFactoryImp (protocol, hostName, port);TopicConnection tc= tcf.createTopicConnection();TopicSession sess=tc.createTopicSession (false, DUPS_OK_ACKNOWLEDGE);Topic pubTopic= new lwms.jms.TopicImp ("JmsTestTopic");TopicPublisher publisher= pubSession.createPublisher (pubTopic);tc.start();Posting a Message to a Mailbox with JMS
To post a message to a topic using the JMS API:
javax.jms.TextMessage message= sess.createTextMessage();message.setText ("Hello from LWMS/JMS");message.setJMSDestination (pubTopic);publisher.publish (message);Polling Mailboxes for New Messages with JMS
To subscribe to a topic using the JMS API:
import com.cisco.nm.cmf.lwms.jms.*;import javax.jms.*;TopicConnectionFactory tcf=new TopicConnectionFactoryImp (protocol, hostName, port);TopicConnection tc= tcf.createTopicConnection();TopicSession sess= tc.createTopicSession (false, DUPS_OK_ACKNOWLEDGE);Topic subTopic= new lwms.jms.Topic ("JmsTestTopic");TopicSubscriber subscriber= sess.createSubscriber (subTopic);subscriber.setMessageListener (this);tc.start();Removing a Message Listener with JMS
To unregister a JMS message listener:
TopicSubscriber.setMessageListener(null)Using JMS Message Selectors
LWMS supports JMS message selectors. The JMS message-selector syntax is identical to the LWMS message filter syntax (see the "Filtering Messages with LWMS" section).
LWMS Command Reference
These topics provide reference information about LWMS and JMS API calls:
•
LWMS Native API Messaging Methods
The following tables list the public Java interfaces needed to create a mailbox, send a message, and perform other messaging tasks.
Table 20-8 LwmsMsgListener Interface
Callback method in listener.
JMS to LWMS Mappings
The following tables list significant mappings between the JMS and LWMS APIs and message fields.
For a complete list of JMS to LWMS mappings, see the CMF Lightweight Messaging Service (LWMS) Functional Specification, ENG-58367.
Table 20-10 JMS to LWMS API Mappings
Converts JMS Message to a LWMS Message per the mappings in Table 20-11 and then calls LwmsClient.sendMsg().
If publish() is called with TTL (time-to-live), the TTL should be set to at least two times the client polling interval.
If ttl=0 (in JMS, this means the message never expires), LWMS sets the message's TTL to one hour; this is done because LWMS architecture specifies that messages must expire eventually.
