Java Message Service Concepts - The Java EE 6 Tutorial: Advanced Topics - page 369

that implements the MessageListener interface, you can register the message listener
as follows:
Listener myListener = new Listener();
consumer.setMessageListener(myListener);
Note
In the Java EE platform, a MessageListener can be used only in
an application client, not in a web component or enterprise bean.
After you register the message listener, you call the start method on the Connection
to begin message delivery. (If you call start before you register the message listener,
you are likely to miss messages.)
When message delivery begins, the JMS provider automatically calls the message listen-
er's onMessage method whenever a message is delivered. The onMessage method
takes one argument of type Message , which your implementation of the method can cast
to any of the other message types (see “ Message Bodies ” on page 357 ) .
A message listener is not specific to a particular destination type. The same listener can
obtain messages from either a queue or a topic, depending on the type of destination for
which the message consumer was created. A message listener does, however, usually ex-
pect a specific message type and format.
Your onMessage method should handle all exceptions. It must not throw checked ex-
ceptions, and throwing a RuntimeException is considered a programming error.
The session used to create the message consumer serializes the execution of all message
listeners registered with the session. At any time, only one of the session's message listen-
ers is running.
In the Java EE platform, a message-driven bean is a special kind of message listener.
For details, see “ Using Message-Driven Beans to Receive Messages Asynchronously ” on
page 370 .
JMS Message Selectors
If your messaging application needs to filter the messages it receives, you can use a JMS
API message selector, which allows a message consumer to specify the messages that
interest it. Message selectors assign the work of filtering messages to the JMS provider
rather than to the application. For an example of an application that uses a message select-
or, see “ An Application That Uses the JMS API with a Session Bean ” on page 416 .