https://activemq.apache.org/components/artemis/documentation/latest/core.html#core-api
Greetings...
While reading this section, I believe a few reformulated paragraphs might be
beneficial, as well as some grammatic improvement. I'm pasting my suggestion
below for consideration. Hope you find it meaningful.
Thanks & regards,
Ben
Using Core API
Apache ActiveMQ Artemis is a messaging system with its own core API.
If you don't want to use JMS API or any of the other supported protocols, you
can use the core API directly. The core API provides all the functionality of
JMS but without much of the complexity. It also contains features that are not
available in JMS.
1. Core Messaging Concepts
The core messaging concepts are similar to those in JMS. However, in general,
the core API is simpler. This is because the distinctions between queues,
topics and subscriptions are absent in the Core API. We'll discuss each of the
major core messaging concepts in turn. For details about the API, please
consult Javadoc.
Also please refer to the address model chapter for a high-level overview of
these concepts as well as configuration details.
1.1. Message
A message is a unit of data which is transmitted between clients and
servers.
A message has a body which is a buffer object with 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 to be sent to. When the message arrives on
the server it is routed to one or more queues that are bound to the address.
The routing semantics (i.e. anycast or multicast) are determined by the
"routing type" of the address and queue. If the queues are bound to a filter,
the message will only be routed to the queue(s) the filter matches. An address
may have many queues bound to it or none. There may also be entities other than
queues (e.g. diverts) bound to an address.
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. (How about durable messages in a
non-durable queue? Or non-durable messages in a durable queue?)
Messages can be specified with a priority value between 0 and 9. 0
represents the lowest priority and 9 represents the highest. The broker will
attempt to deliver higher priority messages before lower priority ones.
A Message can be set with an optional expiry time. The broker will not
deliver messages after its expiry time has been exceeded.
A Message may carry an optional timestamp that represents the time the
message was sent.
Apache ActiveMQ Artemis also supports the sending/receiving of messages larger
than what can fit in the available RAM.
2. Core API
2.1. ServerLocator
Clients use ServerLocator instances to create a ClientSessionFactory instance.
A ServerLocator instance is used to locate server and create connections to it.
In JMS terms think of a ServerLocator in the same way you would a JMS
Connection Factory.
A ServerLocator instance is created with the ActiveMQClient factory class.
2.2. ClientSessionFactory
A client uses a ClientSessionFactory instance to create a ClientSession
instance. A ClientSessionFactory instance is basically the connection to a
server. In JMS terms think of them as JMS Connections.
A ClientSessionFactory instance is created using the ServerLocator class.
2.3. ClientSession
A client uses a ClientSession to consume and produce messages and group them in
transactions. A ClientSession instance can support both transactional and non
transactional semantics and provide XAResource interface so messaging
operations can be part of a JTA transaction.
A ClientSession instance may contain both ClientConsumer and ClientProducer
instances.
A ClientSession instance can be registered with an optional
SendAcknowledgementHandler. This allows your client code to be notified
asynchronously when a message it transmitted has successfully reached the
server. This feature guarantees that the message you sent reaches the server
without having to block and wait for confirmation of delivery before sending
the next message. Blocking on each message sent is costly since it requires a
network round trip for each message. By not blocking but receive
acknowledgements 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 please see the section Guarantees of sends and commits.
2.3.1. Identifying your session for management and debugging
Assigning IDs to your core sessions will be helpful with monitoring and
debugging the cluster using the management console.
ClientSession session;
// ...
session.addMetaData(ClientSession.JMS_SESSION_IDENTIFIER_PROPERTY,
"jms-client-id");
session.addMetaData("jms-client-id", "my-session");
This session ID will appear in the Client ID column under the Connections,
Consumers and Producers tabs. It is the same as setClientID in JMS.
2.4. ClientConsumer
Clients use a ClientConsumer instance to consume messages from a queue. Core
messaging supports both synchronous and asynchronous message consumption
semantics.
If a ClientConsumer instance is configured with an optional filter expression,
it will only consume messages that match that expression.
2.5. ClientProducer
To send messages, A Client creates a ClientProducer instance on ClientSession.
A ClientProducer instance can specify an address to which all outgoing messages
are routed. If no address is specified when the ClientProvider is created, it
can be set at time of message transmission.
Please note that ClientSession, ClientProducer and ClientConsumer instances are
designed to be re-used.
It's an anti-pattern to create new ClientSession, ClientProducer and
ClientConsumer instances for each message you produce or consume. If you do
this, your application performance will be poor. This is discussed further in
the section on Performance Tuning.
3. A simple example of using Core
This is a simple program that uses the core messaging API to send and receive a
message. It takes two steps: 1. set up the producer to write a message to an
address, and 2. create a queue for the consumer using anycast routing, create
the consumer, and start it.
ServerLocator locator = ActiveMQClient.createServerLocator("vm://0");
// In this simple example, one session is used for both producing and consuming
ClientSessionFactory factory = locator.createClientSessionFactory();
ClientSession session = factory.createSession();
// A producer is associated with an address ...
ClientProducer producer = session.createProducer("example");
ClientMessage message = session.createMessage(true);
message.getBodyBuffer().writeString("Hello");
// We need a queue attached to the address ...
session.createQueue("example", RoutingType.ANYCAST, "example", true);
// And a consumer attached to the queue ...
ClientConsumer consumer = session.createConsumer("example");
// Once we have a queue, we can send the message ...
producer.send(message);
// We need to start the session before we can -receive- messages ...
session.start();
ClientMessage msgReceived = consumer.receive();
System.out.println("message = " + msgReceived.getBodyBuffer().readString());
session.close();
