Message Plugin
Messaging within or between applications is a powerful way to communicate and to keep all components of your enterprise in sync with one another. For example you may wish to alert all areas of your application that some data has changed so if they are holding any caches they can flush or renew it. Another example could be to broadcast certain business logic states. For example when someone logs in, another process sends out a welcome email. That process may exist in the same OpenBD application or in another separate instance.
By building such functionality as a messaging system, you break away from the sequential processing and the need for every component to explicitly know about each other. It is the perfect way to build and maintain truly scalable systems in a service orientated manner without worrying where everything physically resides.
This plugin allows hooks the CFML world into this very powerful platform, by utilising the popular Java Messaging Service (JMS) as its hooks. This plugin contains a full ActiveMQ installation, permitting OpenBD to either act as a JMS server or to easily hook into an existing external one. Even if you use this in a complete standalone fashion, this provides a fast and easy way to manage the popular Design Pattern of listeners and callbacks.
Messaging is built around the notion of topics. You create a topic with a messaging server that is used to manage messages. Messages can then be delivered to a topic and any person listening to that topic will receive that message, in as quick a time as possible. Topic's live within a server's domain and it is the servers security model that determines which clients can listen to them.
This plugin wraps up all the complexity associated with interacting with message queues using a small set of functions:
- MessageServerRegister()
- MessageServerStop()
- MessageSendTopic()
- MessageTopicListener()
- MessageRemoveTopicListener()
Creating a Server Source
Talking with a JMS Server is performed through a MessageServerSource and can be thought of in much the same way as you use a datasource to talk to databases. You create a new source by simply calling the function: MessageServerRegister( "symbolicname" [,"jms connection url"] ).
This will then create a new MessageSource that you can use with the other messaging functions. If you do not specify a connection string, then a local internal JMS server will be created that can be used. It uses a standard JMS/ActiveMQ connection string format. If you have already created this server, then an exception will be thrown.
Once completed, you can shutdown the server using the function: MessageServerStop( "messagesource" ). If the server is local, then it will be shutdown. If the server is a remote one, then the data source will be de-registered and any existing listeners on the OpenBD will be cancelled.
This plugin will manage the reconnect procedure automatically for you if a remote server drops out for a period of time due.
Sending a message to a topic
Once you have a messagesource, you can easily send messages to any topic. A topic does not need to be pre-registered. If it doesn't already exist on the server then it will be created on the fly.
There are basically two types of message you can send to a topic; a simple text based one, or a Map, which is a key/data value. Any other type you want to broadcast, then encode it to XML or JSON before hand and send it as a text string.
You use the function: MessageSendTopic( "messagesource", "topic", userdata ) that will send the message to the server immediately. If the server is not available then an exception will be thrown. If userdata is a simple type (boolean, date, string, number) then it will be sent as a text message. If the userdata is a structure then it will be sent as a Map; everything else will throw an error.
Receiving messages from a topic
Receiving message from a topic is done using a CFC with the onMessage( message, header ) method defined. For each message that comes in, this CFC is created and the method is called. The message will contain the message that was sent, and the header is a structure with a number of keys (id, topic, timestamp, expiration, delivery, replyto) that describes the metadata for the message.
You can setup a message receiver using the function MessageTopicListener( "messagesource", "topic", cfc ). You can define the CFC as either a live object, or a string describing the location of where to load the CFC.
Once registered you do not have to worry about server disconnects. The plugin will automatically reconnect and deliver messages to your CFC as and when they come.
To stop receiving messages you can call: MessageRemoveTopicListener( "messagesource", "topic", cfc ) and no more messages will be received.
Log files
All activity on the JMS message bus is logged to a file within the working directory of OpenBD. The file /cflog/plugin-message.log will rotate at 25MB and contains all notes of any messages coming in and if they were processed by a CFC and the time it took. Any errors that are produced are automatically logged to the standard OpenBD error folder.