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 <bfz...@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(); > >
