public interface Messaging
This functionality is currently supported for deployment on Java server platforms only, and
requires a Power license or better as well as purchase of the Real-Time Messaging
module. See http://smartclient.com/product for details, and see
LoadingOptionalModules for instructions on setting up the
Messaging works in terms of channels. A channel is an abitrary identifier for a destination for a message. When messages are sent to a channel, anyone subscribed to that channel receives the message.
The same concept appears in JMS (Java Message Service), where the equivalent term to channel is "topic" (for JMS, queues are supported as well).
Messages can be sent to a channel from either the client-side ( Messaging.send()) or server-side (ISCMessageDispatcher.send(), or equivalent JMS APIs to send a message to a Topic).
You can subscribe to a channel from either the client-side ( Messaging.subscribe()) or server-side (ISCMessageDispatcher.register() and ISCMessageDispatcher.subscribe(), or equivalent JMS APIs to subscribe to a Topic).
Channels can be used in any way the application needs. For example, a chat application similar to IRC would typically create a new channel every time 2 or more people want to talk to one another.
Server-side RTM interfaces are provided by the following classes in com.isomorphic.messaging:
Simple concrete implementation of ISubscriber. send() adds message to a queue and nextMessage() retrieves them.
WebSockets is preferred as the non-websockets implementation requires a persistent connection to the server, and browsers are mandated by the HTTP protocol spec to limit connections to a single host to 6. This becomes significant if an application with Messaging connections is opened in multiple browser windows or tabs. The application can be significantly slowed down as as connections are used up by messaging, meaning the app's non-messaging operations will start slowing down and blocking as fewer connections are available for parallel operations.
Both client and server are configured to use WebSockets by default if supported. If the server does not respond correctly to WebSocket requests, the framework will automatically detect this and silently back off to using Comet. The Messaging APIs are not impacted in any way by the protocol being used, so this process is invisible to end users and to application code.
Some cases that may cause WebSockets to be unavailable include:
The Smart GWT message dispatcher can operate in simple mode or enterprise mode:
# Use com.isomorphic.messaging.JMSMessageDispatcher for JMS-backed messaging messaging.dispatcherImplementer: com.isomorphic.messaging.JMSMessageDispatcher
There are two styles of configuring JNDI and configuring Smart GWT Messaging to find a JMS Topic or Queue Connection Factory:
1. Configure JNDI in your servlet engine
In this case, you would set JNDI properties (java.naming.* properties) via your application's jndi.properties file.
2. Configure JNDI via server.properties
If you set
messaging.jms.context to a string such as "mySettings", it tells
Smart GWT to refer to several other properties in the
prefixed with "jndi" + the value of
messaging.jms.context. For example:
messaging.jms.context: mySettings jndi.mySettings.java.naming.factory.initial: org.jboss.naming.remote.client.InitialContextFactory jndi.mySettings.java.naming.provider.url: remote://localhost:4447 jndi.mySettings.java.naming.factory.url.pkgs: org.jboss.naming:org.jnp.interfaces jndi.mySettings.java.naming.security.authentication: simple jndi.mySettings.java.naming.security.principal: admin jndi.mySettings.java.naming.security.credentials: adminThe configuration above means that, when the Messaging system uses JNDI to look up ConnectionFactory instances, the Hashtable of environment information passed to
new InitialContext()will contain entries such as
java.naming.provider.url = remote://localhost:4447and the various other
java.naming.*JNDI properties shown above.
This is an alternative to using
jndi.properties or other means provided by your
servlet engine for JNDI setup. If you use this mechanism, the JNDI properties shown above
will be used only when Messaging looks up JMS resources, and not for any other JNDI lookups.
When using JNDI "lookup()" calls to find your JMS ConnectionFactory instances, Smart GWT using the following properties from server.properties (shown below with their default values):
messaging.jms.jndiPrefix: jms messaging.jms.topicConnectionFactory: TopicConnectionFactory messaging.jms.queueConnectionFactory: QueueConnectionFactorySmart GWT will first call the JNDI API
jndiPrefixproperty shown above, then with either the
queueConnectionFactoryproperty depending on whether a topic or queue is being looked up.
Note that there is horrible confusion and inconsistency across servlet engines as to how JNDI paths are handled when looking up JMS resources:
messaging.jms.jndiPrefixproperty, or it may be considered implicit
messaging.jms.jndiPrefix: java:comp/env messaging.jms.topicConnectionFactory: jms/MyFactory
messaging.jms.jndiPrefix: messaging.jms.topicConnectionFactory: jms/MyFactory
messaging.jms.jndiPrefix: messaging.jms.topicConnectionFactory: MyFactory
messaging.jms.jndiPrefix: java:comp/env messaging.jms.topicConnectionFactory: MyFactoryExample configurations for various popular JMS engines (ActiveMQ, JBoss, etc) can be found on the Isomorphic Public Wiki. Try searching for "messaging" or "jms" or the name of the engine you are trying to configure.
The following properties that control Messaging can also be set via server.properties. Generally, do not adjust these properties unless you are extremely familiar with how web-based streaming works and with the specific details of your network topology.
# how often do we send keepalives to the client (ms) messaging.keepaliveInterval: 3000 # how long the client waits after the keepaliveInterval before re-establishing # the connection (ms) messaging.keepaliveReestablishDelay: 1000 # how long the client waits for the connect handshake to complete before # retrying (ms) messaging.connectTimeout: 4000 # connection time to live - the maximum amount of time a persistent connection # is allowed to stay open before being re-established (ms). Connections are re-created # every 2 minutes by default because intervening firewalls or web proxies will often sever # connections that have been open too long, as will the browser itself. messaging.connectionTTL: 120000 # total response size to pad out to in order to defeat bufferring by intervening proxies # (in bytes). Set higher if you see data leaving the server, but it never arrives at the # client machine. With older legacy proxies, values as high as 256k may be required. messaging.flushBufferSize: 8096 # dispatcher to use for user registration/message queueing # com.isomorphic.messaging.LocalMessageDispatcher for simple one-jvm messaging # com.isomorphic.messaging.JMSMessageDispatcher for JMS-backed messaging messaging.dispatcherImplementer: com.isomorphic.messaging.LocalMessageDispatcher # jms configuration - for JMSMessageDispatcher only messaging.jms.context: _container_ messaging.jms.jndiPrefix: jms messaging.jms.topicConnectionFactory: TopicConnectionFactory messaging.jms.queueConnectionFactory: QueueConnectionFactory