jms
Product: xTier™/LWC 2.3 Whitepaper: n/a	support@fitechlabs.com  Download  Buy
Depends: log  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
'jms' implements many well-known and often practiced JMS usage patterns. Note that the goal of this service is not to replace JMS API but to provide a complementary implementation for some frequently used JMS design patterns. Main features of the 'jms' service include but not limited to:

• Smart connections - provides support for self-recoverable JMS connections.
• Message to object conversion - automatic conversion between user objects and JMS messages.
• Object senders and receivers - add support for user object sending and receiving as well as waiting for and sending replies in thread-safe manner.
• Thread safety - all classes provided by xTier™ jms service are safe to be used by multiple threads.

 Top

Configuration
'jms' service is configured via pre-defined xtier_jms.xml configuration file. This file follows standard xTier™ service configuration pattern that can be demonstrated by the following complete example of jms configuration:

1		<region name="examples">
2		<!--
3		Defaults for multi senders and receivers.
4
5		Note that all parameters are optional and if
6		ommited JMS specification defaults will be used.
7		It is sufficient to specify message defaults as
8		empty element (<msg-defaults/>) if user does not
9		need to override default values.
10		-->
11		<msg-defaults priority="4" ttl="0"
12		delivery-mode="non-persistent"
13		disable-msg-id="true"
14		disable-msg-timestamp="false">
15		<!--
16		Optional object converter definition.
17		If ommitted, then instance of 'JmsDefaultConverter'
18		will be used by default.
19		-->
20		<obj-converter>
21		<ioc policy="singleton">
22		<java class="com.fitechlabs.xtier.services.
23		jms.converters.JmsDefaultConverter"/>
24		</ioc>
25		</obj-converter>
26		</msg-defaults>
27
28		<!--
29		Example connection factory.
30		-->
31		<conn-factory name="conn-factory">
32		<ioc-factory>
33		<ioc policy="singleton">
34		<!--
35		CHANGE CLASS NAME ACCORDING TO YOUR JMS
36		PROVIDER SPECIFICATION.
37		-->
38		<java class="QueueConnectionFactory"/>
39		</ioc>
40		</ioc-factory>
41
42		<!--
43		Use default settings for smart connections.
44		-->
45		</conn-factory>
46
47		<!--
48		Example XA connection factory.
49		-->
50		<xa-conn-factory name="xa-conn-factory">
51		<ioc-factory>
52		<ioc policy="singleton">
53		<!--
54		CHANGE CLASS NAME ACCORDING TO YOUR JMS
55		PROVIDER SPECIFICATION.
56		-->
57		<java class="XAQueueConnectionFactory"/>
58		</ioc>
59		</ioc-factory>
60
61		<!--
62		Override default settings.
63		-->
64		<smart-conn retries="3" retry-timeout="4000"/>
65		</xa-conn-factory>
66
67		<!--
68		Example JNDI connection factory.
69		-->
70		<conn-factory name="jndi-factory">
71		<jndi-factory name="jndi-conn-factory-name"/>
72		</conn-factory>
73		</region>

Formal sepcification for this service configuration can be found in xtier_jms.dtd file in ${XTIER_ROOT}/config/dtd folder. Following is detailed description of jms configuration parameters.

msg-defaults	This element specified default parameters for object sending and receiving via JmsObjectSender and JmsObjectReceiver. Following are default values if user omits to specify them explicitely in XML: delivery-mode - DEFAULT_DELIVERY_MODE priority - Message#DEFAULT_PRIORITY ttl - Message#DEFAULT_TIME_TO_LIVE is-disable-msg-id - false is-disable-msg-timestamp - false
conn-factory	This element specifies JMS connection factory. There are 2 ways to specify JMS connection factory: as IoC object or through JNDI lookup. Following are explanations of IoC and JNDI definitions. ioc-factory - contains IoC definition. For information how to use IoC refer to IocService documentation. jndi-factory - Instance of connection factory will be looked up from JNDI tree using 'name' attribute as a name.
xa-conn-factory	This element specifies JMS XA connection factory. XA connection factory configuration is identical to regular connection factory configuration.

 Top

Examples
Usage of 'jms' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'jms' service. Once the service instance is obtained the service API can be used.

Following code snippet is taken out from jms service example:

1		// Get connection factory configured in jms XML
2		// configuration file. Note that connection factory
3		// is lazily initialized on first access.
4		assert jms.getConnFactory("conn-factory") != null;
5
6		// Get XA connection from XA connection factory
7		// configured in jms XML configuration file.
8		XAConnection xaConn = jms.getXaConn("xa-conn-factory");
9
10		// Close XA connection ignoring all potential exceptions.
11		jms.close(xaConn);
12
13		// Get smart connection from connection factory.
14		// Smart connections add self-recoverable features to
15		// JMS connections.
16		JmsSmartConnection smartConn =
17		jms.getSmartConn("conn-factory");
18
19		// Make sure that smart connection is active.
20		assert smartConn.isOnline() == true;
21
22		// Add error listener to smart connection.
23		smartConn.addExceptionListener(new ExceptionListener() {
24		public void onException(JMSException error) {
25		System.out.println("Error in smart connection.");
26
27		error.printStackTrace();
28		}
29		});
30
31		// Get underlying connection from smart connection. Note
32		// that if underlying connection had previously failed,
33		// smart connection will make the best attempt to re-create
34		// it based on pre-configured number of retries.
35		assert smartConn.getConn() != null;
36
37		// Reset smart connection by closing existing JMS connection
38		// and opening a new one. This operation should be rarely used,
39		// since 'getConn()' method should be sufficient in most cases.
40		smartConn.reset();
41
42		// Close smart connection.
43		smartConn.close();

 Top