Chapter 7. Using Core
HornetQ core is a completely JMS-agnostic messaging system with its own non-JMS API. This is called the core API.
You can use the core API directly if you do not want to use JMS. The core API provides all the functionality of JMS but without much of the complexity. It also provides features that are not available using JMS.
7.1. Core Messaging Concepts
Some of the core messaging concepts are similar to JMS concepts, but there are still differences between them. In general, the core messaging API is simpler than the JMS API, since distinctions between queues, topics and subscriptions are removed. Each of these major core messaging concepts will be discussed in turn.
7.1.1. Message
- A message is the unit of data that is sent between clients and servers.
- A message has a body which is a buffer containing convenient methods for reading and writing data into it.
- A message has a set of properties which are key-value pairs. Each property key is a string and property values can be of type integer, long, short, byte, byte[], String, double, float or boolean.
- A message has an address it is being sent to. When the message arrives on the server it is routed to any queues that are bound to the address - if the queues are bound with any filter, the message will only be routed to that queue if the filter matches. An address may have many queues bound to it or none. There may also be entities other than queues, like diverts bound to addresses.
- Messages can be either durable or non durable. Durable messages in a durable queue will survive a server crash or restart. Non durable messages will not survive a server crash or restart.
- Messages can be specified with a priority value between 0 and 9. 0 represents the lowest priority and 9 represents the highest. HornetQ will attempt to deliver higher priority messages before lower priority ones.
- Messages can be specified with an optional expiry time. HornetQ will not deliver messages after its expiry time has been exceeded.
- Messages have an optional time stamp which represents the time the message was sent.
- HornetQ also supports the sending or consuming of very large messages - much larger than can fit in available RAM at any one time.
7.1.2. Address
A server maintains a mapping between an address and a set of queues. Zero or more queues can be bound to a single address. Each queue can be bound with an optional message filter. When a message is routed, it is routed to the set of queues bound to the message's address. If any of the queues are bound with a filter expression, then the message will only be routed to the subset of bound queues which match that filter expression.
Other entities, such as diverts can also be bound to an address and messages will also be routed there.
Note
In core, there is no concept of a topic; topic is a JMS only term. Instead, in core, we just deal with addresses and queues.
For example, a JMS topic would be implemented by a single address to which many queues are bound. Each queue represents a subscription of the topic. A JMS queue would be implemented as a single address to which one queue is bound; that queue represents the JMS queue.
7.1.3. Queue
Queues can be durable, which means the messages they contain survive a server crash or restart, as long as the messages in them are durable. Non-durable queues do not survive a server restart or crash even if the messages they contain are durable.
Queues can also be temporary, meaning they are automatically deleted when the client connection is closed, if they are not explicitly deleted before that.
Queues can be bound with an optional filter expression. If a filter expression is supplied then the server will only route messages that match that filter expression to any queues bound to the address.
Many queues can be bound to a single address. A particular queue is only bound to a maximum of one address.
7.1.4. ClientSessionFactory
Clients use
ClientSessionFactory instances to create ClientSession instances. ClientSessionFactory instances know how to connect to the server to create sessions, and are configurable with many settings.
ClientSessionFactory instances are created using the HornetQClient factory class.
7.1.5. ClientSession
A client uses a ClientSession for consuming and producing messages and for grouping them in transactions. ClientSession instances can support both transactional and non transactional semantics and also provide an
XAResource interface so messaging operations can be performed as part of a JTA transaction.
ClientSession instances group ClientConsumers and ClientProducers.
ClientSession instances can be registered with an optional
SendAcknowledgementHandler. This allows your client code to be notified asynchronously when sent messages have successfully reached the server. This feature ensures sent messages have reached the server without having to block on each message sent until a response is received.
Blocking on each messages sent is costly since it requires a network round trip for each message sent. By not blocking and receiving send acknowledgments asynchronously, you can create true end-to-end asynchronous systems which is not possible using the standard JMS API. For more information on this feature refer to Chapter 18, Guarantees of sends and commits.
7.1.6. ClientConsumer
Clients use
ClientConsumer instances to consume messages from a queue. Core Messaging supports both synchronous and asynchronous message consumption semantics. ClientConsumer instances can be configured with an optional filter expression and will only consume messages which match that expression.
7.1.7. ClientProducer
Clients create
ClientProducer instances on ClientSession instances so they can send messages. ClientProducer instances can specify an address to which all sent messages are routed, or they can have no specified address, and the address is specified at send time for the message.
Warning
ClientSession, ClientProducer and ClientConsumer instances are designed to be re-used.
It is an anti-pattern to create new ClientSession, ClientProducer, and ClientConsumer instances for each message you produce or consume. If you do this, your application will suffer from poor performance. This is discussed further in Chapter 43, Performance Tuning.
