|
|
JMS ConnectorOverviewThe JMS Connector provides access to a variety of JMS based systems. The current version has been tested with SonicMQ and FioranoMQ and IBM MQ Series. Refer to Specific topics to see what you might need to do to your Metamerge Installation in order to make the JMS Connector work. The Connector enables communication of both native Entry objects and XML text to be passed using a Java Message Server product. The JMS Connector supports JMS message properties. Each message received by the JMS Connector will populate the conn object with properties from the JMS message (see the getProperty() and setProperty() methods of the entry class to access these). conn object properties are prefixed with "jms." followed by the JMS message property name. The property holds the value from the JMS message. When sending a message the user can set properties which will then be passed on to the JMS message sent. The JMS Connector will scan the conn object for properties that starts with "jms." and set the corresponding JMS message property from the conn property.
The conn object is only available in a few hooks: See When is the conn object available under Attribute Mapping for where. JMS MessagesEverything sent and received by the JMS connector is a JMS message. The JMS connector converts the MI Entry object into a JMS message and vice versa. Each JMS message contains pre-defined JMS headers, user defined properties and some kind of body that is either text, a byte array or a serialized Java object. JMS Message TypesThe JMS environment that allows you to send different types of data on the JMS bus. This connector recognize three of those types. The three types are referred to as TextMessage, BytesMessage and ObjectMessage. The most open-minded strategy is to use TextMessage (e.g. jms.usetextmessages=true) so that other applications than Metamerge Integrator can read messages generated by the JMS connector. When you communicate with other MI servers over a JMS bus the BytesMessage provides a very simple way to send an entire Entry object to the recipient. This is also particularly useful when the entry object contains special Java objects that are not easy to represent as text. Most Java objects provide a toString() method that returns the string representation of it but the opposite is very rare. Also, the toString() method does not always return very useful information. For example, the string representation of a byte array is "[B@<memory-address>". TextMessageA text message carries a body of text. The format of the text itself is undefined so it can be virtually anything. When you send/receive messages of this type the connector will do one of two things depending on whether you have specified a parser or not.
var str = work.getString ("message"); task.logmsg ("Received the following text: " + str ); If you expect to receive text messages in various formats (XML, LDIF, CSV ...) you should leave the parser parameter blank and make the guess yourself as to what format the text message is. When you know the format you can use the system.parseObject(parserName, data) to do the parsing for you as in: var str = work.getString ("message"); // code to determine format if ( isLDIF ) e = system.parseObject( "metamerge.LDIF", str ); else if ( isCSV ) e = system.parseObject ( "metamerge.CSV", str ); else e = system.parseObject ( "metamerge.XML", str ); } // Dump parsed entry to logfile task.dumpEntry ( e ); The jms.usetextmessages flag determines whether the connector should use this method when sending a message. Object MessageAn object message is a message containing a serialized Java object. A serialized Java object is a Java object that has been converted into a byte stream in a specific format which makes it possible for the receiver to "resurrect" the object at the other end. Testing shows that this is fine as long as the Java class libraries are available to the JMS server in both ends. Typically, a java.lang.String object will cause no problems but other Java objects might. For this reason, the JMS connector will not generate object messages but is able to receive them. When you receive an object message the connector will return two attributes:
var obj = work.getObject ("java.object"); obj.anyMethodDefinedForTheObject (); You will only receive these messages. Bytes MessageA bytes message is a message carrying an arbitrary array of bytes. The JMS connector will generate this type of message when the jms.usetextmessages flag is false. The connector will take the provided entry and serialize it into a byte array and send the message as a bytes message. When receiving a bytes message, the connector will first attempt to deserialize the byte array into an Entry object. If that fails, the byte array is returned in the message attribute. You should access the byte array using the getObject method in your work/conn entry. var ba = work.getObject ("message"); for ( i = 0; i < ba.length; i++) task.logmsg ( "Next byte: " + ba [ i ] ); This type of message is generated only if jms.usetextmessages is false (not checked). Version 1.13In version 1.13 the JMS connector was enhanced with the following functionality. Iterator ModeA new parameter was added to the configuration where you can specify a Message Filter to filter out specific messages you want returned on a Queue/Topic. A message filter specification is a subset of SQL92 and is defined in the JMS specification. Lookup ModeThe connector now supports Lookup mode (e.g. findEntry) where the user can search for matching messages in a JMS Queue/Topic. The Link Criteria specifies the JMS headers and properties for selecting matching messages on a queue. Important When you specify the link criteria you must not use the 'jms.' prefix. If you search for a property called MyProp you must say "MyProp = 'value'" even thought the connector returns the property as jms.MyProp. A future version will correct this potential confusion. For the advanced link criteria you must conform to the Message Selection specification as described in the JMS specification (http://java.sun.com/products/jms). The JMS connector will in this release reuse the SQL filter specification (JMS message selection is a subset of SQL92) to build the message selection string. Turn on debug mode to view the generated message filter string. There are basically two ways to perform a lookup. The first way is to do a non-destructive search in a Queue (using QueueBrowser) which will return matching messages without removing the messages from the JMS queue. The second mode removes all matching entries from the JMS queue. You decide which to use by setting the jms.lookupConsumesMessages flag in the connector configuration. For Topic connections the jms.lookupConsumesMessages flag does not apply as messages on topics are always removed when a subscriber receives it. However, the Lookup mode will heed the Durable Subscriber flag in which case the JMS server will hold any messages sent on a topic when you are disconnected. The JMS connector works in the same way as other connectors in that you can specify a maximum number of entries to return in your assemblyline settings. Thus, to ensure you only retrieve a single message during lookup you could specify max duplicate entries = 1 in the AssemblyLine settings. By using the Allow Duplicates flag in the connector screen you can influence further the behavior of the Lookup mode. Setting max duplicates to 1 and checking Allow Duplicates allows you to retrieve one matching entry at a time regardless of the number of matching messages in the JMS queue. Since the JMS bus is asynchronous the JMS connector provides parameters to determine when the Lookup should stop looking for messages. There are two parameters that tells the connector how many times it will query the JMS queue and for how long it will wait for new messages during the query. Specifying 10 for the retry count and 1000 for the timeout will cause the connector to query the JMS queue ten times each waiting 1 second for new messages. If no messages are received during this interval the connector returns. If during a query the connector receives a message, it will continue to check for additional messages (this time without any timeout) until the queue returns no more messages or until the received message count reaches the Max Duplicate Entries limit defined by the AssemblyLine. The effect of this is that a lookup operation only retrieves those messages that are available at the moment. JMS Headers & PropertiesA JMS messages consists of headers, properties and the body. Headers are accessed differently than properties and was not available in previous versions. In this version you can specify how to deal with headers and properties. JMS HeadersJMS headers are pre-defined named values that is present in all messages (although the value might be null). The following is a list of JMS header names this connector supports:
These headers are all set by the provider and may or may not be acted upon by the JMS driver for outgoing messages. In the configuration screen you can specify that you want all headers returned as attributes or specify a list of those of interest. All headers are named using a prefix of 'jms.'. Also note that JMS header names always start with the string JMS. This means that you should never use property names starting with jms.JMS as they would be intepreted as headers. JMS PropertiesIn previous versions of this connector all JMS properties were copied between the Entry object and the JMS Message. In this release you can refine this behavior by telling the connector to return all user defined properties as attributes or specify a list of properties of interest. All properties are prefixed with 'jms.' to separate them from other attributes. If you leave the list of properties blank and uncheck the jms.propertiesAsAttributes flag you will get the same behavior as for previous versions. As opposed to JMS headers, JMS properties can be set by the user. If you use the backwards compatible mode you must set the entry properties in the Before Add hook as in: conn.setProperty ( "jms.MyProperty", "Some Value" ); If you either check the jms.propertiesAsAttributes flag or specify a list of
properties, you should provide the JMS properties as attributes. ConfigurationThe Connector needs the following parameters:
ExampleDemo package containing a ready to run configuration for the JMS Connector is included here. In addition you need a SonicMQ JMS server. Specific TopicsHere are some files that you need to add to the Metamerge jars directory (or to the classpath)
Download(You must replace your existing .jar-files with the ones provided in the .zip file.)
|
|
|