You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@activemq.apache.org by "Ben F. Zhou" <bf...@hotmail.com> on 2024/02/26 04:17:53 UTC
Suggested improvement in documentation section "Using Core"
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();
Re: Suggested improvement in documentation section "Using Core"
Posted by Jiri Daněk <jd...@redhat.com>.
On Mon, Feb 26, 2024 at 4:11 PM Ben F. Zhou <bf...@hotmail.com> wrote:
> Hi Justin,
>
> Thanks for the information. I'll go ahead to learn these tools.
>
That might be a bit too much learning to do upfront. I suggest you do this
instead.
GitHub has two ways to let you edit files without really knowing Git at
all. See
https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
(recommended) or the more fancy
https://docs.github.com/en/codespaces/the-githubdev-web-based-editor#opening-the-githubdev-editor
(less recommended). The page you want to edit is
https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/core.adoc.
Create an account or log in, click the Edit in place command top right on
that page, the pencil icon, and edit away.
--
Mit freundlichen Grüßen / Kind regards
Jiri Daněk
RE: Suggested improvement in documentation section "Using Core"
Posted by "Ben F. Zhou" <bf...@hotmail.com>.
Hi Justin,
Thanks for the information. I'll go ahead to learn these tools.
this is apparently a fantastic community. It will be great if I can contribute to it in a small way.
Thanks a lot!
Ben
-----Original Message-----
From: Justin Bertram <jb...@apache.org>
Sent: Sunday, February 25, 2024 11:51 PM
To: users@activemq.apache.org
Subject: Re: Suggested improvement in documentation section "Using Core"
Thanks for the suggestions!
To be clear, the user manual is located in the source repository [1] so if you have suggestions the best way to submit them is via a Git pull request.
That way we can review your changes, see exactly what's been changed, make suggestions of our own, etc.
The specific "Using Core" chapter you're suggesting changes to is located here [2].
If you're not familiar with Git, pull-requests, GitHub, etc. there are great resources online to get you up to speed. These are great tools which have really opened up access to Open Source software to developers and non-developers alike.
Justin
[1] https://github.com/apache/activemq-artemis/tree/main/docs/user-manual
[2]
https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/core.adoc
On Sun, Feb 25, 2024 at 10:18 PM Ben F. Zhou <bf...@hotmail.com> wrote:
>
> https://activemq.apache.org/components/artemis/documentation/latest/co
> re.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();
>
>
Re: Suggested improvement in documentation section "Using Core"
Posted by Justin Bertram <jb...@apache.org>.
Thanks for the suggestions!
To be clear, the user manual is located in the source repository [1] so if
you have suggestions the best way to submit them is via a Git pull request.
That way we can review your changes, see exactly what's been changed, make
suggestions of our own, etc.
The specific "Using Core" chapter you're suggesting changes to is located
here [2].
If you're not familiar with Git, pull-requests, GitHub, etc. there are
great resources online to get you up to speed. These are great tools which
have really opened up access to Open Source software to developers and
non-developers alike.
Justin
[1] https://github.com/apache/activemq-artemis/tree/main/docs/user-manual
[2]
https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/core.adoc
On Sun, Feb 25, 2024 at 10:18 PM Ben F. Zhou <bf...@hotmail.com> wrote:
>
> 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();
>
>