diff --git a/.github/workflows/brokenlinks-config.json b/.github/workflows/brokenlinks-config.json index fa92850..90301dc 100644 --- a/.github/workflows/brokenlinks-config.json +++ b/.github/workflows/brokenlinks-config.json @@ -7,5 +7,5 @@ "pattern": "/solacevmr:8080/" } ], - "aliveStatusCodes": [400, 429, 200, 0, 403] + "aliveStatusCodes": [400, 429, 200, 0, 403, 503] } diff --git a/gatsby-config.js b/gatsby-config.js index 59d81d7..69d7a25 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -202,7 +202,7 @@ module.exports = { }, { pathname: "/jms", - crumbLabel: "JMS", + crumbLabel: "Jakarta Messaging", }, { pathname: "/tanzu", diff --git a/src/pages/tutorials/jms/confirmed-delivery.md b/src/pages/tutorials/jms/confirmed-delivery.md index 353b298..514dc8b 100644 --- a/src/pages/tutorials/jms/confirmed-delivery.md +++ b/src/pages/tutorials/jms/confirmed-delivery.md @@ -10,14 +10,14 @@ links: This tutorial builds on the basic concepts introduced in [Persistence with Queues](../persistence-with-queues/) tutorial and will show you how to properly process publisher acknowledgements. Once an acknowledgement for a message has been received and processed, you have confirmed your persistent messages have been properly accepted by Solace messaging and therefore can be guaranteed of no message loss. -## Persistent Publishing with JMS version 1.1 +## Persistent Publishing with Jakarta Messaging -In the JMS version 1.1, when sending PERSISTENT messages, the JMS MessageProducer must not return from the blocking send() method until the message is fully acknowledged by Solace messaging. This behavior is mandated by the specification. Therefore applications sending persistent messages using JMS version 1.1 are guaranteed that the messages is accepted by Solace messaging by the time the MessageProducer.send() returns. No extra publisher acknowledgement handling is required or possible using the JMS API. +In Jakarta Messaging (and its JMS predecessors), when sending PERSISTENT messages, the MessageProducer must not return from the blocking send() method until the message is fully acknowledged by Solace messaging. This behavior is mandated by the specification. Therefore applications sending persistent messages using Jakarta Messaging are guaranteed that the message is accepted by Solace messaging by the time the MessageProducer.send() returns. No extra publisher acknowledgement handling is required or possible using the Jakarta Messaging API. -This restriction of the JMS 1.1 specification does mean that PERSISTENT message producers are forced to block on each message until it is fully guaranteed by the messaging system. This can lead to performance bottlenecks on publish. Applications can work around this by using JMS Session based transactions and committing the transaction only after several messages are sent to the messaging system. +This restriction of the specification does mean that PERSISTENT message producers are forced to block on each message until it is fully guaranteed by the messaging system. This can lead to performance bottlenecks on publish. Applications can work around this by using Jakarta Messaging Session based transactions and committing the transaction only after several messages are sent to the messaging system. -Refer to the [JMS specification](http://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/) for further details on this subject. +Refer to the [Jakarta Messaging 3.1 specification](https://jakarta.ee/specifications/messaging/3.1/) for further details on this subject. ## Summarizing -For a JMS version 1.1 applications there is nothing further they must do to confirm message delivery with Solace messaging. This is handled by the API by making the send call blocking. \ No newline at end of file +For Jakarta Messaging applications there is nothing further they must do to confirm message delivery with Solace messaging. This is handled by the API by making the send call blocking. \ No newline at end of file diff --git a/src/pages/tutorials/jms/persistence-with-queues.md b/src/pages/tutorials/jms/persistence-with-queues.md index 4cbb2ff..a8bb9a9 100644 --- a/src/pages/tutorials/jms/persistence-with-queues.md +++ b/src/pages/tutorials/jms/persistence-with-queues.md @@ -5,9 +5,9 @@ summary: Learn how to set up persistence for guaranteed delivery. icon: I_dev_Persistent.svg links: - label: QueueProducer.java - link: /blob/master/src/main/java/com/solace/samples/QueueProducer.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueProducer.java - label: QueueConsumer.java - link: /blob/master/src/main/java/com/solace/samples/QueueConsumer.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueConsumer.java - label: feedback link: https://github.com/SolaceDev/solace-dev-tutorials/blob/master/src/pages/tutorials/jms/persistence-with-queues.md --- @@ -34,26 +34,26 @@ The goal of this tutorial is to understand the following: 2. How to send a persistent message to a Solace queue 3. How to bind to this queue and receive a persistent message -## Java Messaging Service (JMS) Introduction +## Jakarta Messaging (JMS) Introduction -JMS is a standard API for sending and receiving messages. As such, in addition to information provided on the Solace developer portal, you may also look at some external sources for more details about JMS. The following are good places to start +Jakarta Messaging (the successor to Java Message Service — JMS — under the Jakarta EE project) is a standard API for sending and receiving messages. It uses the `jakarta.jms.*` namespace where earlier JMS versions used `javax.jms.*`. In addition to information provided on the Solace developer portal, you may also look at some external sources for more details. The following are good places to start: -1. [https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html](https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html) -2. [https://en.wikipedia.org/wiki/Java_Message_Service](https://en.wikipedia.org/wiki/Java_Message_Service) -3. [https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3](https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3) +1. [Jakarta Messaging 3.1 Specification](https://jakarta.ee/specifications/messaging/3.1/) +2. [Jakarta Messaging 3.1 API Javadoc](https://jakarta.ee/specifications/messaging/3.1/apidocs/jakarta.messaging/jakarta/jms/package-summary.html) +3. [https://en.wikipedia.org/wiki/Jakarta_Messaging](https://en.wikipedia.org/wiki/Jakarta_Messaging) -The oracle link points you to the JavaEE official tutorials which provide a good introduction to JMS. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. +The Jakarta EE links above provide the official specification and API reference. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. `markdown:solaceMessaging-part1.md` ![Screenshot: Messaging Connectivity Information](../../../images/screenshots/connectivity-info.png) `markdown:solaceMessaging-part2.md` `markdown:solaceApi.md` -## JMS administered objects +## Jakarta Messaging administered objects -This tutorial will make use of two JMS administered objects: +This tutorial will make use of two Jakarta Messaging administered objects: -* A ConnectionFactory object – Used by JMS clients to successfully connect to a message broker like Solace messaging +* A ConnectionFactory object – Used by Jakarta Messaging clients to successfully connect to a message broker like Solace messaging * A Queue Destination – Used for publishing and subscribing to messages. This example will use the queue `Q/tutorial` As described in the [publish/subscribe tutorial](../publish-subscribe/) we will use the approach of programmatically creating the required objects. @@ -62,15 +62,15 @@ As described in the [publish/subscribe tutorial](../publish-subscribe/) we will A difference to the publish/subscribe tutorial is that here a physical endpoint resource – a durable queue, associated with the Queue Destination – needs to be created on Solace messaging, which will persist the messages until consumed. -We will use the Dynamic Durables feature, which enables the physical endpoint resource to be dynamically created without any additional steps, when the JMS Queue Destination is created programmatically. It is also possible to create resources administratively on the router using the Solace message router [Management Tools](https://docs.solace.com/#Management). +We will use the Dynamic Durables feature, which enables the physical endpoint resource to be dynamically created without any additional steps, when the Jakarta Messaging Queue Destination is created programmatically. It is also possible to create resources administratively on the router using the Solace message router [Management Tools](https://docs.solace.com/#Management). -To use Dynamic Durables, you need to connect the JMS Connection as outlined in the [publish/subscribe tutorial](../publish-subscribe/) with one additional property: +To use Dynamic Durables, you need to connect the Jakarta Messaging Connection as outlined in the [publish/subscribe tutorial](../publish-subscribe/) with one additional property: ```java connectionFactory.setDynamicDurables(true); ``` -Then we simply create a queue from the JMS `Session`. For other ways of obtaining a queue, for example using JNDI, refer to the [Solace JMS Documentation - Working with Destinations](https://docs.solace.com/Solace-JMS-API/Working-with-Destination.htm). +Then we simply create a queue from the Jakarta Messaging `Session`. For other ways of obtaining a queue, for example using JNDI, refer to the [Solace Jakarta Messaging Documentation - Working with Destinations](https://docs.solace.com/API/Solace-Jakarta-API/Working-with-Destination.htm). ```java final String QUEUE_NAME = "Q/tutorial"; @@ -85,7 +85,7 @@ Now it is time to send a message to the queue. ![Diagram: Sending a Message to a Queue](../../../images/diagrams/sending-message-to-queue-300x160.png) -There is no difference in the actual method calls to the JMS `MessageProducer` when sending a PERSISTENT message as compared to a NON-PERSISTENT message shown in the publish/subscribe tutorial. The difference in the PERSISTENT message is that Solace messaging will acknowledge the message once it is successfully stored on the message router and the `MessageProducer.send()` call will not return until it has successfully received this acknowledgement. This means that in JMS, all calls to the `MessageProducer.send()` are blocking calls and they wait for message confirmation from Solace messaging before proceeding. This is outlined in the JMS 1.1 specification and Solace JMS adheres to this requirement. +There is no difference in the actual method calls to the Jakarta Messaging `MessageProducer` when sending a PERSISTENT message as compared to a NON-PERSISTENT message shown in the publish/subscribe tutorial. The difference in the PERSISTENT message is that Solace messaging will acknowledge the message once it is successfully stored on the message router and the `MessageProducer.send()` call will not return until it has successfully received this acknowledgement. This means that in Jakarta Messaging, all calls to the `MessageProducer.send()` are blocking calls and they wait for message confirmation from Solace messaging before proceeding. This is outlined in the Jakarta Messaging specification, and the Solace Jakarta Messaging API adheres to this requirement. To send a message, you must still create a message. The difference from sending a NON-PERSISTENT message is that you must set the message delivery mode to PERSISTENT on send. @@ -102,7 +102,7 @@ Now it is time to receive the messages sent to your queue. ![Diagram: Receiving a Message from a Queue](../../../images/diagrams/receiving-message-from-queue-300x160.png) -You still need a JMS `Connection` just as you did with the producer. With a connection, you then need to create a Session and bind to Solace messaging queue by creating a `MessageConsumer`. This is nearly identical to what was shown in the publish/subscribe tutorial. In this case, create a Session but use the Solace client acknowledgement mode. This allows the consumers to acknowledge each message individually without side-effects. You can learn more about acknowledgement modes in the Establishing Connections sections of [Solace JMS Documentation – Establishing Connections](https://docs.solace.com/Solace-JMS-API/Establishing-Connections.htm). +You still need a Jakarta Messaging `Connection` just as you did with the producer. With a connection, you then need to create a Session and bind to Solace messaging queue by creating a `MessageConsumer`. This is nearly identical to what was shown in the publish/subscribe tutorial. In this case, create a Session but use the Solace client acknowledgement mode. This allows the consumers to acknowledge each message individually without side-effects. You can learn more about acknowledgement modes in the Establishing Connections sections of [Solace Jakarta Messaging Documentation – Establishing Connections](https://docs.solace.com/API/Solace-Jakarta-API/Establishing-Connections.htm). ```java Session session = connection.createSession(false, SupportedProperty.SOL_CLIENT_ACKNOWLEDGE)); @@ -135,10 +135,10 @@ messageConsumer.setMessageListener(new MessageListener() { ## Summarizing -The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms). If you combine the example source code shown above results in the following source: +The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms-jakarta). If you combine the example source code shown above results in the following source: -* [QueueProducer.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/QueueProducer.java) -* [QueueConsumer.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/QueueConsumer.java) +* [QueueProducer.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueProducer.java) +* [QueueConsumer.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueConsumer.java) ### Getting the Source @@ -146,8 +146,8 @@ The full source code for this example is available in [GitHub](https://github.co Clone the GitHub repository containing the Solace samples. ``` -git clone https://github.com/SolaceSamples/solace-samples-jms -cd solace-samples-jms +git clone https://github.com/SolaceSamples/solace-samples-jms-jakarta +cd solace-samples-jms-jakarta ``` ### Building @@ -158,7 +158,7 @@ Building these examples is simple. You can simply build the project using Gradl ./gradlew assemble ``` -This builds all of the JMS Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. +This builds all of the Jakarta Messaging Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. ### Running the Sample diff --git a/src/pages/tutorials/jms/publish-subscribe.md b/src/pages/tutorials/jms/publish-subscribe.md index 560dfe6..01f7ae2 100644 --- a/src/pages/tutorials/jms/publish-subscribe.md +++ b/src/pages/tutorials/jms/publish-subscribe.md @@ -5,45 +5,45 @@ summary: Learn how to set up pub/sub messaging on a Solace VMR. icon: I_dev_P+S.svg links: - label: TopicPublisher.java - link: /blob/master/src/main/java/com/solace/samples/TopicPublisher.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/TopicPublisher.java - label: TopicSubscriber.java - link: /blob/master/src/main/java/com/solace/samples/TopicSubscriber.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/TopicSubscriber.java - label: feedback link: https://github.com/SolaceDev/solace-dev-tutorials/blob/master/src/pages/tutorials/jms/publish-subscribe.md --- -This tutorial will introduce you to the fundamentals of the JMS 1.1 API as implemented by Solace. The tutorial will exemplify connecting a client, subscribing to a topic and sending a message matching this topic subscription. This forms the basis for any publish / subscribe message exchange. +This tutorial will introduce you to the fundamentals of the Jakarta Messaging 3.1 API as implemented by Solace. The tutorial will exemplify connecting a client, subscribing to a topic and sending a message matching this topic subscription. This forms the basis for any publish / subscribe message exchange. `markdown:assumption.md` `markdown:pubSubGoal.md` -## Java Messaging Service (JMS) Introduction +## Jakarta Messaging (JMS) Introduction -JMS is a standard API for sending and receiving messages. As such, in addition to information provided on the Solace developer portal, you may also look at some external sources for more details about JMS. The following are good places to start +Jakarta Messaging (the successor to Java Message Service — JMS — under the Jakarta EE project) is a standard API for sending and receiving messages. It uses the `jakarta.jms.*` namespace where earlier JMS versions used `javax.jms.*`. In addition to information provided on the Solace developer portal, you may also look at some external sources for more details. The following are good places to start: -1. [https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html](https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html) -2. [https://en.wikipedia.org/wiki/Java_Message_Service](https://en.wikipedia.org/wiki/Java_Message_Service) -3. [https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3](https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3) +1. [Jakarta Messaging 3.1 Specification](https://jakarta.ee/specifications/messaging/3.1/) +2. [Jakarta Messaging 3.1 API Javadoc](https://jakarta.ee/specifications/messaging/3.1/apidocs/jakarta.messaging/jakarta/jms/package-summary.html) +3. [https://en.wikipedia.org/wiki/Jakarta_Messaging](https://en.wikipedia.org/wiki/Jakarta_Messaging) -The oracle link points you to the JavaEE official tutorials which provide a good introduction to JMS. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. +The Jakarta EE links above provide the official specification and API reference. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. `markdown:solaceMessaging-part1.md` ![Screenshot: Messaging Connectivity Information](../../../images/screenshots/connectivity-info.png) `markdown:solaceMessaging-part2.md` `markdown:solaceApi.md` -## JMS administered objects +## Jakarta Messaging administered objects -This tutorial will make use of two JMS administered objects: +This tutorial will make use of two Jakarta Messaging administered objects: -* A ConnectionFactory object – used by JMS clients to successfully connect to a message broker like a Solace message router +* A ConnectionFactory object – used by Jakarta Messaging clients to successfully connect to a message broker like a Solace message router * A Topic Destination – used for publishing and subscribing to messages. This example will use the topic `T/GettingStarted/pubsub` -The [JMS specification](https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html) provides two ways to create administered objects: +The [Jakarta Messaging specification](https://jakarta.ee/specifications/messaging/3.1/) provides two ways to create administered objects: * JNDI Lookup -* Programmatic creation through the JMS API. +* Programmatic creation through the Jakarta Messaging API. This tutorial will use the approach of programmatically creating the required objects. For developers, this is the recommended approach as this enables: @@ -51,14 +51,14 @@ This tutorial will use the approach of programmatically creating the required ob * No requirement to preconfigure the JNDI on Solace messaging or within an LDAP server * Easier integration into frameworks by avoiding external JNDI lookups. -The programmatic approach is also the convention most often followed with JMS samples. So it should be familiar to developers of JMS application. The Solace JMS API supports both programmatically creating administered objects and JNDI lookup. Developers can learn all about Solace JMS by referring to the [Solace JMS Documentation](https://docs.solace.com/Solace-JMS-API/jms-get-started-open.htm). +The programmatic approach is also the convention most often followed with Jakarta Messaging samples. So it should be familiar to developers of Jakarta Messaging applications. The Solace Jakarta Messaging API supports both programmatically creating administered objects and JNDI lookup. Developers can learn all about the Solace Jakarta Messaging API by referring to the [Solace Jakarta Messaging Documentation](https://docs.solace.com/API/Solace-Jakarta-API/jakarta-get-started-open.htm). ## Connecting to Solace Messaging -In order to send or receive messages, an application must connect to Solace messaging. In JMS, a client connects by creating a `Connection` from the `ConnectionFactory`. Then a JMS `Session` is used as a factory for consumers and producers. +In order to send or receive messages, an application must connect to Solace messaging. In Jakarta Messaging, a client connects by creating a `Connection` from the `ConnectionFactory`. Then a Jakarta Messaging `Session` is used as a factory for consumers and producers. -The following code shows how to create a connection using a programmatically created `ConnectionFactory`. You can learn more about other ways to create ConnectionFactories by referring to [Solace JMS Documentation - Obtaining Connection Factories](https://docs.solace.com/Solace-JMS-API/Obtaining-Connection-Fac.htm). +The following code shows how to create a connection using a programmatically created `ConnectionFactory`. You can learn more about other ways to create ConnectionFactories by referring to [Solace Jakarta Messaging Documentation - Obtaining Connection Factories](https://docs.solace.com/API/Solace-Jakarta-API/Connection-Factories.htm). ```java @@ -79,21 +79,21 @@ Connection connection = connectionFactory.createConnection(); Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); ``` -This tutorial uses an auto acknowledgement session. This is the simplest to use. However, it often makes sense to customize the acknowledgement mode in JMS to suit your application needs. Solace supports all of the JMS acknowledgement modes and introduces an extension which allows applications to individually acknowledge each message which we believe is a significant improvement of the behaviour of the default JMS client acknowledgement. Learn more in the [Solace JMS Documentation - Managing Sessions](https://docs.solace.com/Solace-JMS-API/Managing-Sessions.htm). +This tutorial uses an auto acknowledgement session. This is the simplest to use. However, it often makes sense to customize the acknowledgement mode in Jakarta Messaging to suit your application needs. Solace supports all of the Jakarta Messaging acknowledgement modes and introduces an extension which allows applications to individually acknowledge each message which we believe is a significant improvement of the behaviour of the default Jakarta Messaging client acknowledgement. Learn more in the [Solace Jakarta Messaging Documentation - Managing Sessions](https://docs.solace.com/API/Solace-Jakarta-API/Managing-Sessions.htm). At this point your client is connected to Solace messaging. You can use Broker Manager to view the client connection and related details. ## Receiving a message -This tutorial uses JMS “Non-Persistent” messages which are at most once delivery messages. So first, let’s express interest in the messages by subscribing to a Solace topic. Then you can look at publishing a matching message and see it received. +This tutorial uses Jakarta Messaging “Non-Persistent” messages which are at most once delivery messages. So first, let’s express interest in the messages by subscribing to a Solace topic. Then you can look at publishing a matching message and see it received. -With a session connected in the previous step, the next step is to create a message consumer. Message consumers enable the synchronous or asynchronous receipt of messages. Asynchronous receipt of messages is accomplished through callbacks. These callbacks are defined in JMS by the `MessageListener` interface. +With a session connected in the previous step, the next step is to create a message consumer. Message consumers enable the synchronous or asynchronous receipt of messages. Asynchronous receipt of messages is accomplished through callbacks. These callbacks are defined in Jakarta Messaging by the `MessageListener` interface. ![Diagram: Receiving a Message](../../../images/diagrams/pub-sub-receiving-message-300x134.png) -First a `Topic` object is required. Here we create a topic from the JMS Session session programmatically. For other ways of obtaining a `Topic`, for example using JNDI, refer to the [Solace JMS Documentation - Working with Destinations](https://docs.solace.com/Solace-JMS-API/Working-with-Destination.htm). +First a `Topic` object is required. Here we create a topic from the Jakarta Messaging Session session programmatically. For other ways of obtaining a `Topic`, for example using JNDI, refer to the [Solace Jakarta Messaging Documentation - Working with Destinations](https://docs.solace.com/API/Solace-Jakarta-API/Working-with-Destination.htm). -Then create the `MessageConsumer` using the JMS `Session`. +Then create the `MessageConsumer` using the Jakarta Messaging `Session`. ```java final String TOPIC_NAME = "T/GettingStarted/pubsub"; @@ -150,7 +150,7 @@ Now it is time to send a message to the waiting consumer. ### Establishing the publisher flow -In JMS, a message producer is required for sending messages to Solace messaging. +In Jakarta Messaging, a message producer is required for sending messages to Solace messaging. ```java final String TOPIC_NAME = "T/GettingStarted/pubsub"; @@ -159,11 +159,11 @@ Topic topic = session.createTopic(TOPIC_NAME); MessageProducer messageProducer = session.createProducer(topic); ``` -JMS Message Producers are created from the session object and are assigned a default destination on creation. +Jakarta Messaging Message Producers are created from the session object and are assigned a default destination on creation. ### Creating and sending the message -To send a message, first create a message from the JMS `Session`. Then use the MessageProducer to send the message. The message producer offers several options for sending. Since we wish to send a non-persistent message in this tutorial, we will use the most flexible option where delivery mode, priority and time to live is specified. +To send a message, first create a message from the Jakarta Messaging `Session`. Then use the MessageProducer to send the message. The message producer offers several options for sending. Since we wish to send a non-persistent message in this tutorial, we will use the most flexible option where delivery mode, priority and time to live is specified. ```java TextMessage message = session.createTextMessage("Hello world!"); @@ -175,10 +175,10 @@ At this point the producer has sent a message to Solace messaging and your waiti ## Summarizing -The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms). If you combine the example source code shown above results in the following source: +The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms-jakarta). If you combine the example source code shown above results in the following source: -* [TopicPublisher.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/TopicPublisher.java) -* [TopicSubscriber.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/TopicSubscriber.java) +* [TopicPublisher.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/TopicPublisher.java) +* [TopicSubscriber.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/TopicSubscriber.java) ### Getting the Source @@ -186,8 +186,8 @@ The full source code for this example is available in [GitHub](https://github.co Clone the GitHub repository containing the Solace samples. ``` -git clone https://github.com/SolaceSamples/solace-samples-jms -cd solace-samples-jms +git clone https://github.com/SolaceSamples/solace-samples-jms-jakarta +cd solace-samples-jms-jakarta ``` ### Building @@ -198,7 +198,7 @@ Building these examples is simple. You can simply build the project using Gradl ./gradlew assemble ``` -This builds all of the JMS Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. +This builds all of the Jakarta Messaging Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. ### Running the Sample diff --git a/src/pages/tutorials/jms/request-reply.md b/src/pages/tutorials/jms/request-reply.md index b19be11..e447df7 100644 --- a/src/pages/tutorials/jms/request-reply.md +++ b/src/pages/tutorials/jms/request-reply.md @@ -5,9 +5,9 @@ summary: Learn how to set up request/reply messaging. icon: I_dev_R+R.svg links: - label: BasicRequestor.java - link: /blob/master/src/main/java/com/solace/samples/BasicRequestor.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/BasicRequestor.java - label: BasicReplier.java - link: /blob/master/src/main/java/com/solace/samples/BasicReplier.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/BasicReplier.java - label: feedback link: https://github.com/SolaceDev/solace-dev-tutorials/blob/master/src/pages/tutorials/jms/request-reply.md --- @@ -24,52 +24,52 @@ The goal of this tutorial is to understand the following: * On the requestor side: 1. How to create a request 2. How to receive a response - 3. How to use the Solace JMS API to correlate the request and response + 3. How to use the Solace Jakarta Messaging API to correlate the request and response * On the replier side: 1. How to detect a request expecting a reply 2. How to generate a reply message -## Java Messaging Service (JMS) Introduction +## Jakarta Messaging (JMS) Introduction -JMS is a standard API for sending and receiving messages. As such, in addition to information provided on the Solace developer portal, you may also look at some external sources for more details about JMS. The following are good places to start +Jakarta Messaging (the successor to Java Message Service — JMS — under the Jakarta EE project) is a standard API for sending and receiving messages. It uses the `jakarta.jms.*` namespace where earlier JMS versions used `javax.jms.*`. In addition to information provided on the Solace developer portal, you may also look at some external sources for more details. The following are good places to start: -1. [https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html](https://docs.oracle.com/javaee/7/api/javax/jms/package-summary.html) -2. [https://en.wikipedia.org/wiki/Java_Message_Service](https://en.wikipedia.org/wiki/Java_Message_Service) -3. [https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3](https://docs.oracle.com/javaee/7/tutorial/partmessaging.htm#GFIRP3) +1. [Jakarta Messaging 3.1 Specification](https://jakarta.ee/specifications/messaging/3.1/) +2. [Jakarta Messaging 3.1 API Javadoc](https://jakarta.ee/specifications/messaging/3.1/apidocs/jakarta.messaging/jakarta/jms/package-summary.html) +3. [https://en.wikipedia.org/wiki/Jakarta_Messaging](https://en.wikipedia.org/wiki/Jakarta_Messaging) -The oracle link points you to the JavaEE official tutorials which provide a good introduction to JMS. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. +The Jakarta EE links above provide the official specification and API reference. This getting started tutorial follows a similar path and shows you the Solace specifics that you need to do to get this working with Solace messaging. ## Overview -Request-reply messaging is supported by Solace messaging for all delivery modes. The JMS API does provide a `TopicRequestor` and `QueueRequestor` interface which is very simple. However, this interface lacks the ability to timeout the requests. This limitation means that it is often simpler to implement the request – reply pattern in your application. This tutorial will follow this approach. +Request-reply messaging is supported by Solace messaging for all delivery modes. The Jakarta Messaging API does provide a `TopicRequestor` and `QueueRequestor` interface which is very simple. However, this interface lacks the ability to timeout the requests. This limitation means that it is often simpler to implement the request – reply pattern in your application. This tutorial will follow this approach. It is also possible to use guaranteed messaging for request reply scenarios. In this case the replier can listen on a queue for incoming requests and the requestor can use a temporary endpoint to attract replies. This is explained further in the [Solace product documentation](https://docs.solace.com/Solace-JMS-API/Using-Topic-Requestors.htm) and shown in the API samples named `SolJMSRRGuaranteedRequestor` and `SolJMSRRGuaranteedReplier`. ### Message Correlation -For request-reply messaging to be successful it must be possible for the requestor to correlate the request with the subsequent reply. Solace messages support two fields that are needed to enable request-reply correlation. The reply-to field can be used by the requestor to indicate a Solace Topic or Queue where the reply should be sent. In JMS, a natural choice for this is a temporary queue. The second requirement is to be able to identify the reply message within the stream of incoming messages. This is accomplished using the correlation-id field. This field will transit the Solace messaging system unmodified. Repliers can include the same correlation-id in a reply message to allow the requestor to detect the corresponding reply. The figure below outlines this exchange. +For request-reply messaging to be successful it must be possible for the requestor to correlate the request with the subsequent reply. Solace messages support two fields that are needed to enable request-reply correlation. The reply-to field can be used by the requestor to indicate a Solace Topic or Queue where the reply should be sent. In Jakarta Messaging, a natural choice for this is a temporary queue. The second requirement is to be able to identify the reply message within the stream of incoming messages. This is accomplished using the correlation-id field. This field will transit the Solace messaging system unmodified. Repliers can include the same correlation-id in a reply message to allow the requestor to detect the corresponding reply. The figure below outlines this exchange. ![Diagram: Message Correlation](../../../images/diagrams/Request-Reply_diagram-1.png) -Note: In JMS it also common for the requestor to put a unique message ID into the message on send and have the replier respond with this message ID in the correlation ID field of the response message. This is equally possible with the Solace JMS API. This tutorial favors the correlation ID approach because it works commonly with all Solace messaging APIs. +Note: In Jakarta Messaging it is also common for the requestor to put a unique message ID into the message on send and have the replier respond with this message ID in the correlation ID field of the response message. This is equally possible with the Solace Jakarta Messaging API. This tutorial favors the correlation ID approach because it works commonly with all Solace messaging APIs. `markdown:solaceMessaging-part1.md` ![Screenshot: Messaging Connectivity Information](../../../images/screenshots/connectivity-info.png) `markdown:solaceMessaging-part2.md` `markdown:solaceApi.md` -## JMS administered objects +## Jakarta Messaging administered objects -This tutorial will make use of two JMS administered objects: +This tutorial will make use of two Jakarta Messaging administered objects: -* A ConnectionFactory object – Used by JMS clients to successfully connect to a message broker like Solace messaging +* A ConnectionFactory object – Used by Jakarta Messaging clients to successfully connect to a message broker like Solace messaging * A Queue Destination – Used for publishing and subscribing to messages. This example will use the topic `T/GettingStarted/requests` As described in the [publish/subscribe tutorial](../publish-subscribe/) we will use the approach of programmatically creating the required objects. ## Connecting a session to Solace Messaging -As with other tutorials, this tutorial requires a JMS `Connection` connected to the default message VPN of a Solace VMR which has authentication disabled. So the only required information to proceed is the Solace VMR host string which this tutorial accepts as an argument. Connect the JMS `Connection` as outlined in the [publish/subscribe tutorial](../publish-subscribe/). +As with other tutorials, this tutorial requires a Jakarta Messaging `Connection` connected to the default message VPN of a Solace VMR which has authentication disabled. So the only required information to proceed is the Solace VMR host string which this tutorial accepts as an argument. Connect the Jakarta Messaging `Connection` as outlined in the [publish/subscribe tutorial](../publish-subscribe/). ## Making a request @@ -77,7 +77,7 @@ First let’s look at the requestor. This is the application that will send the ![Diagram: Making a Request](../../../images/diagrams/Request-Reply_diagram-2.png) -In order to be able to receive the response message back from the Replier, the Requestor must setup a JMS `Consumer`. For simplicity, this tutorial will use a blocking Consumer to receive the response messages using a temporary queue. +In order to be able to receive the response message back from the Replier, the Requestor must setup a Jakarta Messaging `Consumer`. For simplicity, this tutorial will use a blocking Consumer to receive the response messages using a temporary queue. ```java TemporaryQueue replyToQueue = session.createTemporaryQueue(); @@ -85,7 +85,7 @@ MessageConsumer replyConsumer = session.createConsumer(replyToQueue); connection.start(); ``` -With the connection started, now the Requestor is ready to receive any reply messages on its temporary JMS Queue. Next you must create a message and the topic to send the message to. This is done in the same way as illustrated in the [publish/subscribe tutorial](../publish-subscribe/). +With the connection started, now the Requestor is ready to receive any reply messages on its temporary Jakarta Messaging Queue. Next you must create a message and the topic to send the message to. This is done in the same way as illustrated in the [publish/subscribe tutorial](../publish-subscribe/). ```java final String REQUEST_TOPIC_NAME = "T/GettingStarted/requests"; @@ -121,7 +121,7 @@ Now it is time to receive the request and generate an appropriate reply. ![Diagram: Replying to a Request](../../../images/diagrams/Request-Reply_diagram-3.png) -Just as with previous tutorials, you still need to connect a JMS Connection and Session and create a MessageConsumer to receive request messages. However, in order to send replies back to the requestor, you will also need a MessageProducer. The following code will create the producer and consumer that is required. +Just as with previous tutorials, you still need to connect a Jakarta Messaging Connection and Session and create a MessageConsumer to receive request messages. However, in order to send replies back to the requestor, you will also need a MessageProducer. The following code will create the producer and consumer that is required. ```java final String REQUEST_TOPIC_NAME = "T/GettingStarted/requests"; @@ -132,7 +132,7 @@ final MessageProducer replyProducer = session.createProducer(null); Then you simply have to modify the `onMessage()` method of the `MessageConsumer` from the publish/subscribe tutorial to inspect incoming messages and generate appropriate replies. -For example, the following code will send a response to all messages that have a reply-to field. It will copy over any `JMSCorrelationID` found in the incoming messages. It will also set a Solace specific boolean field indicating this message is a reply message. This is a Solace extension to enable JMS applications to exchange requests and replies easily with applications using other Solace APIs. +For example, the following code will send a response to all messages that have a reply-to field. It will copy over any `JMSCorrelationID` found in the incoming messages. It will also set a Solace specific boolean field indicating this message is a reply message. This is a Solace extension to enable Jakarta Messaging applications to exchange requests and replies easily with applications using other Solace APIs. ```java public void onMessage(Message request) { @@ -190,10 +190,10 @@ System.out.printf("Message Content:%n%s%n", SolJmsUtility.dumpMessage(reply)); ## Summarizing -The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms). If you combine the example source code shown above results in the following source: +The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms-jakarta). If you combine the example source code shown above results in the following source: -* [BasicRequestor.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/BasicRequestor.java) -* [BasicReplier.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/BasicReplier.java) +* [BasicRequestor.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/BasicRequestor.java) +* [BasicReplier.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/BasicReplier.java) ### Getting the Source @@ -201,8 +201,8 @@ The full source code for this example is available in [GitHub](https://github.co Clone the GitHub repository containing the Solace samples. ``` -git clone https://github.com/SolaceSamples/solace-samples-jms -cd solace-samples-jms +git clone https://github.com/SolaceSamples/solace-samples-jms-jakarta +cd solace-samples-jms-jakarta ``` ### Building @@ -213,7 +213,7 @@ Building these examples is simple. You can simply build the project using Gradl ./gradlew assemble ``` -This builds all of the JMS Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. +This builds all of the Jakarta Messaging Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. ### Running the Sample @@ -224,4 +224,4 @@ $ ./build/staged/bin/basicReplier @ @ ``` -With that you now know how to successfully implement the request-reply message exchange pattern using JMS NON-PERSISTENT messages and temporary endpoints. \ No newline at end of file +With that you now know how to successfully implement the request-reply message exchange pattern using Jakarta Messaging NON-PERSISTENT messages and temporary endpoints. \ No newline at end of file diff --git a/src/pages/tutorials/jms/topic-to-queue-mapping.md b/src/pages/tutorials/jms/topic-to-queue-mapping.md index b451c39..7ffe891 100644 --- a/src/pages/tutorials/jms/topic-to-queue-mapping.md +++ b/src/pages/tutorials/jms/topic-to-queue-mapping.md @@ -14,13 +14,13 @@ In addition to spooling messages published directly to the queue, it is possible The following diagram illustrates this feature. -![Diagram: JMS Queue Mapping](../../../images/diagrams/topic-to-queue-mapping-detail.png) +![Diagram: Jakarta Messaging Queue Mapping](../../../images/diagrams/topic-to-queue-mapping-detail.png) If you have a durable queue named “Q”, it will receive messages published directly to the queue destination named “Q”. However, it is also possible to add subscriptions to this queue in the form of topics. This example adds topics “A” and “B”. Once these subscriptions are added, the queue will start receiving messages published to the topic destinations “A” and “B”. When you combine this with the wildcard support provided by Solace topics this opens up a number of interesting use cases. -## Topic to Queue Mapping and JMS +## Topic to Queue Mapping and Jakarta Messaging -JMS is a standard programmatic interface with a design goal of being messaging middleware agnostic. As such, the JMS interface does not provide a way for applications to directly take advantage of the Solace Topic to Queue Mapping feature. However JMS applications wishing to take advantage of this Solace feature have a few options. +Jakarta Messaging (and its JMS predecessors) is a standard programmatic interface with a design goal of being messaging middleware agnostic. As such, the Jakarta Messaging interface does not provide a way for applications to directly take advantage of the Solace Topic to Queue Mapping feature. However Jakarta Messaging applications wishing to take advantage of this Solace feature have a few options. One option is to use a management interface to administratively configure the topic to queue mapping, by adding topic subscriptions to the queue. This can either be done through the CLI or Broker Manager application; or the SEMP programmatic management API. The SEMP API enables applications to fully configure Solace message routers. Applications can use this API by logging in to the Solace message router using a Message-VPN admin account. This concept is introduced in the [Technology – Messaging Platform Features](https://solace.com/products/tech/) and further details are available in the [Solace Message Router Product Documentation](https://docs.solace.com/SEMP/Using-Legacy-SEMP.htm). @@ -28,7 +28,7 @@ A second option is to consider using a Solace Java API session directly for this ## Summarizing -So in summary JMS applications wishing to take advantage of this feature have two options: +So in summary Jakarta Messaging applications wishing to take advantage of this feature have two options: * [Use one of the Solace management interfaces and directly configure the topic subscriptions on the queue](https://docs.solace.com/PubSub-Basics/Core-Concepts.htm). * [Use the Solace API for Java directly for this part of your application](https://solace.com/samples/solace-samples-java/topic-to-queue-mapping/). \ No newline at end of file diff --git a/src/pages/tutorials/jms/tutorials.yml b/src/pages/tutorials/jms/tutorials.yml index 3f1061c..7cebf29 100644 --- a/src/pages/tutorials/jms/tutorials.yml +++ b/src/pages/tutorials/jms/tutorials.yml @@ -1,8 +1,8 @@ -- title: JMS Tutorials - summary: These tutorials get you up to speed sending and receiving messages with Solace technology in your JMS applications. +- title: Solace Jakarta Messaging (JMS) Tutorials + summary: These tutorials get you up to speed sending and receiving messages with Solace using the Jakarta Messaging API (the successor to JMS, using the jakarta.jms namespace). icon: jms.svg buttons: doclink: https://docs.solace.com/Solace-PubSub-Messaging-APIs/C-API/c-api-home.htm - github: https://github.com/SolaceSamples/solace-samples-jms + github: https://github.com/SolaceSamples/solace-samples-jms-jakarta type: solace diff --git a/src/pages/tutorials/jms/using-external-jndi.md b/src/pages/tutorials/jms/using-external-jndi.md index 581a4dc..6bd4760 100644 --- a/src/pages/tutorials/jms/using-external-jndi.md +++ b/src/pages/tutorials/jms/using-external-jndi.md @@ -1,31 +1,31 @@ --- layout: tutorials -title: Obtaining JMS objects using external JNDI service -summary: Learn how to provision and lookup Solace JMS objects when using an external JNDI service. +title: Using an external Java Naming and Directory Interface (JNDI) service to look up Jakarta Messaging administered objects +summary: Learn how to provision and lookup Solace Jakarta Messaging administered objects when using an external JNDI service. icon: I_dev_JNDI.svg links: - label: ExtJndiImport.java - link: /blob/master/src/main/java/com/solace/samples/ExtJndiImport.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/ExtJndiImport.java - label: ExtJndiTest.java - link: /blob/master/src/main/java/com/solace/samples/ExtJndiTest.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/ExtJndiTest.java - label: feedback link: https://github.com/SolaceDev/solace-dev-tutorials/blob/master/src/pages/tutorials/jms/using-external-jndi.md --- -This tutorial shows how to provision and look up Solace JMS objects from an external [Java Naming and Directory Interface (JNDI)](https://en.wikipedia.org/wiki/Java_Naming_and_Directory_Interface) service, hosted outside the Solace message broker. +This tutorial shows how to provision and look up Solace Jakarta Messaging administered objects from an external [Java Naming and Directory Interface (JNDI)](https://en.wikipedia.org/wiki/Java_Naming_and_Directory_Interface) service, hosted outside the Solace message broker. -The [Obtaining JMS objects using JNDI](../using-jndi/) tutorial provided an introduction to JNDI and the use of JNDI services hosted by the message broker. Using the Solace built-in (internal) JNDI server makes integration easy, but some enterprise use-cases already utilize a dedicated JNDI server, and prefer to store Solace JMS objects at the same location. +The [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects](../using-jndi/) tutorial provided an introduction to JNDI and the use of JNDI services hosted by the message broker. Using the Solace built-in (internal) JNDI server makes integration easy, but some enterprise use-cases already utilize a dedicated JNDI server, and prefer to store Solace Jakarta Messaging administered objects at the same location. ## Assumptions This tutorial assumes the following: -* You are familiar with JNDI basics and the Solace message broker's built-in JNDI service. Refer to the [Java JNDI](https://docs.oracle.com/javase/jndi/tutorial/) and the [Obtaining JMS objects using JNDI](../using-jndi/) tutorials for more. +* You are familiar with JNDI basics and the Solace message broker's built-in JNDI service. Refer to the [Java JNDI](https://docs.oracle.com/javase/jndi/tutorial/) and the [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects](../using-jndi/) tutorials for more. * You are familiar with Solace [core concepts](https://docs.solace.com/PubSub-Basics/Core-Concepts.htm). * You have an understanding, or you can refer to the [Persistence with Queues](../persistence-with-queues/) tutorial for: - * the Java Messaging Service (JMS) basics - * how to send and receive a message using the JMS API - * how obtain the Solace JMS API + * the Jakarta Messaging basics + * how to send and receive a message using the Jakarta Messaging API + * how to obtain the Solace Jakarta Messaging API * You have access to Solace messaging with the following configuration details: * Connectivity information for a Solace Message-VPN configured for guaranteed messaging support * Enabled client username and password @@ -36,7 +36,7 @@ This tutorial assumes the following: The goal of this tutorial is to provide guidance and sample code to: -1. Populate Solace JMS objects into a non-Solace external JNDI store +1. Populate Solace Jakarta Messaging administered objects into a non-Solace external JNDI store 2. Use the external JNDI service for Solace JNDI messaging `markdown:solaceMessaging-part1.md` @@ -46,26 +46,26 @@ The goal of this tutorial is to provide guidance and sample code to: ## Overview -This tutorial will use the two JMS objects from the [Persistence with Queues](../persistence-with-queues/) and [Obtaining JMS objects using JNDI](../using-jndi/) tutorials: +This tutorial will use the two Jakarta Messaging administered objects from the [Persistence with Queues](../persistence-with-queues/) and [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects](../using-jndi/) tutorials: -* A `ConnectionFactory` – used by JMS clients to connect to the message broker +* A `ConnectionFactory` – used by Jakarta Messaging clients to connect to the message broker * A Queue `Destination` – used for publishing and subscribing to guaranteed messages. This time they will be created from an external JNDI server lookup, essentially de-serialized from the respective references returned. The sample code will act as a client to the JNDI server. -JNDI has a wide range of server implementations. We will use the simplest: a local file system based JNDI implementation that is so simple that it will not even use authentication. Your JNDI service provider will likely be more complex in that you will need specific configuration, but this example will give an idea of usage, and the kind of data being stored in JNDI for the Solace JMS objects. Examples of JNDI providers include LDAP or CORBA Naming Service implementations, the native JNDI service of application servers like IBM WebSphere, JBoss and Oracle WebLogic. +JNDI has a wide range of server implementations. We will use the simplest: a local file system based JNDI implementation that is so simple that it will not even use authentication. Your JNDI service provider will likely be more complex in that you will need specific configuration, but this example will give an idea of usage, and the kind of data being stored in JNDI for the Solace Jakarta Messaging administered objects. Examples of JNDI providers include LDAP or CORBA Naming Service implementations, the native JNDI service of application servers like IBM WebSphere, JBoss and Oracle WebLogic. -The first sample application will provision Solace JMS object data (entries) into the external JNDI server. The sample code will show how to create, read, update, or delete JNDI entries. When creating JNDI entries, we will import existing real JNDI data from the Solace internal JNDI server by using a separate JNDI connection to read from there. This tutorial can be used together with the [Obtaining JMS objects using JNDI](../using-jndi/) tutorial to learn more and experiment with the differences. +The first sample application will provision Solace Jakarta Messaging administered object data (entries) into the external JNDI server. The sample code will show how to create, read, update, or delete JNDI entries. When creating JNDI entries, we will import existing real JNDI data from the Solace internal JNDI server by using a separate JNDI connection to read from there. This tutorial can be used together with the [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects](../using-jndi/) tutorial to learn more and experiment with the differences. Next, another sample will look up the external JNDI data, and use it to connect and send a message to the message broker then read it back. -## Importing JMS objects from Solace internal JNDI +## Importing Jakarta Messaging administered objects from Solace internal JNDI The following sections describe the code building blocks of the "ExtJndiImport" sample. Section [Running the Sample](#running-the-sample) demonstrates how to use it. Importing involves the following steps: * Connecting to both the Solace and the external JNDI servers -* Creating a local JMS object from lookup in Solace internal JNDI +* Creating a local Jakarta Messaging object from lookup in Solace internal JNDI * Creating an entry for that object in the external JNDI server Additional basic administration operations included are: @@ -75,7 +75,7 @@ Additional basic administration operations included are: ### Connecting to a JNDI server -JNDI clients need a Java jar library supplied by the service provider to connect and use the JNDI server. The jar client library contains the implementation of [javax.naming.spi.InitialContextFactory](https://docs.oracle.com/javase/8/docs/api/javax/naming/spi/InitialContextFactory.html). For example, for the Solace message broker internal JNDI this is included in the Solace JMS API jar file, and the factory class is `com.solacesystems.jndi.SolJNDIInitialContextFactory`. The jar file for the file system based JNDI implementation used in this tutorial is [fscontext.jar](https://mvnrepository.com/artifact/com.sun.messaging.mq/fscontext), and the factory class is `com.sun.jndi.fscontext.RefFSContextFactory`. +JNDI clients need a Java jar library supplied by the service provider to connect and use the JNDI server. The jar client library contains the implementation of [javax.naming.spi.InitialContextFactory](https://docs.oracle.com/javase/8/docs/api/javax/naming/spi/InitialContextFactory.html) (note: the JNDI API itself still lives in the `javax.naming` namespace in Jakarta EE). For example, for the Solace message broker internal JNDI this is included in the Solace Jakarta Messaging API jar file, and the factory class is `com.solacesystems.jndi.SolJNDIInitialContextFactory`. The jar file for the file system based JNDI implementation used in this tutorial is [fscontext.jar](https://mvnrepository.com/artifact/com.sun.messaging.mq/fscontext), and the factory class is `com.sun.jndi.fscontext.RefFSContextFactory`. This is the typical pattern to connect to a JNDI server. Generally, it requires the InitialContextFactory implementation class name (INITIAL_CONTEXT_FACTORY), connection url (PROVIDER_URL), username (SECURITY_PRINCIPAL), and password (SECURITY_CREDENTIALS). In our simple file system based JNDI example the username and password will be ignored. @@ -106,9 +106,9 @@ solEnv.put(Context.SECURITY_CREDENTIALS, solacePassword); solInitialContext = new InitialContext(solEnv); ``` -### Creating a local JMS object from lookup of a JNDI entry +### Creating a local Jakarta Messaging object from lookup of a JNDI entry -A local JMS object will be created when looked up by its JNDI name. Here are examples of looking up ConnectionFactory and Queue type objects from the Solace internal JNDI: +A local Jakarta Messaging object will be created when looked up by its JNDI name. Here are examples of looking up ConnectionFactory and Queue type objects from the Solace internal JNDI: ```java // ConnectionFactory @@ -121,7 +121,7 @@ SolQueue queue = (SolQueue) solInitialContext.solInitialContext(queueName); ### Creating a new JNDI entry -A local JMS object needs to exist as a starting point, and information that is necessary to recreate it will be entered into the JNDI store. The following example will take above `cf` and `queue` JMS objects and insert them into the external JNDI store. There will be an exception thrown if there is already an entry for that name. +A local Jakarta Messaging object needs to exist as a starting point, and information that is necessary to recreate it will be entered into the JNDI store. The following example will take above `cf` and `queue` Jakarta Messaging objects and insert them into the external JNDI store. There will be an exception thrown if there is already an entry for that name. ``` // ConnectionFactory @@ -184,24 +184,24 @@ try { ## Messaging using external JNDI server lookup -The previous section described how the "ExtJndiImport" sample can be used to create JNDI entries for a Solace JMS ConnectionFactory and a Queue in the external JNDI server. +The previous section described how the "ExtJndiImport" sample can be used to create JNDI entries for a Solace Jakarta Messaging ConnectionFactory and a Queue in the external JNDI server. The "ExtJndiTest" sample will look up these JNDI entries to connect to the message broker and send or receive messages. -The code consists of the building blocks from earlier sections of this tutorial and the [Obtaining JMS objects using JNDI](../using-jndi/) tutorial: +The code consists of the building blocks from earlier sections of this tutorial and the [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects](../using-jndi/) tutorial: - Create the LDAP Initial Context to the external JNDI server -- Lookup the connection factory and queue destination by names and create the Solace JMS ConnectionFactory and Queue JMS objects -- Create a JMS connection to the message broker using the JMS ConnectionFactory -- Create a JMS session, MessageProducer and MessageConsumer +- Lookup the connection factory and queue destination by names and create the Solace Jakarta Messaging ConnectionFactory and Queue objects +- Create a Jakarta Messaging connection to the message broker using the Jakarta Messaging ConnectionFactory +- Create a Jakarta Messaging session, MessageProducer and MessageConsumer - Send a message using the MessageProducer and wait for the MessageConsumer to receive it ## Summarizing -The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms). If you combine the example source code shown above results in the following source: +The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms-jakarta). If you combine the example source code shown above results in the following source: -* [ExtJndiImport.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/ExtJndiImport.java) -* [ExtJndiTest.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/ExtJndiTest.java) +* [ExtJndiImport.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/ExtJndiImport.java) +* [ExtJndiTest.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/ExtJndiTest.java) ### Getting the Source @@ -209,8 +209,8 @@ The full source code for this example is available in [GitHub](https://github.co Clone the GitHub repository containing the Solace samples. ``` -git clone https://github.com/SolaceSamples/solace-samples-jms -cd https://github.com/SolaceSamples/solace-samples-jms +git clone https://github.com/SolaceSamples/solace-samples-jms-jakarta +cd solace-samples-jms-jakarta ``` ### Building @@ -221,13 +221,13 @@ Building these examples is simple; you can use Gradle. ./gradlew assemble ``` -This builds all the JMS Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. +This builds all the Jakarta Messaging Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. Note: the file-based JNDI provider jar "fscontext" is included as a Maven dependency in the Gradle build file `build.gradle`. Replace this with your JNDI provider jar file's reference. If it is are not available from Maven create a directory "libs" under the project root (same level as the "src" directory) and place the jar file there as the build file has this directory in its source path. ### Running the Sample -First, ensure that the Solace internal JNDI has been configured as described in the [Obtaining JMS objects using JNDI tutorial](../using-jndi/), so we can assume followings exist: +First, ensure that the Solace internal JNDI has been configured as described in the [Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects tutorial](../using-jndi/), so we can assume followings exist: | Solace JNDI ConnectionFactory name | /JNDI/CF/GettingStarted | | Solace JNDI Queue name | /JNDI/Q/tutorial | @@ -241,8 +241,8 @@ Using the "ExtJndiImport" sample, export the JNDI configuration to the external * The url for the file-based JNDI must be an existing directory, where a file named `.bindings` will be created if it didn't exist and it can be considered as a simple database. There is no control over the filename. In this tutorial we use the `/tmp` directory, which in Windows may refer to a `\tmp` folder under the current drive. * The file-based JNDI example will ignore username and password; the code has been written to require it. * Operation: BIND, REBIND, UNBIND or LIST (UNBIND and LIST don't require Solace JNDI access details) -* The JMS object reference name in Solace JNDI (-cf for ConnectionFactory, -queue or -topic) -* The JMS object reference name to be created in External JNDI (-name) +* The Jakarta Messaging administered object reference name in Solace JNDI (-cf for ConnectionFactory, -queue or -topic) +* The Jakarta Messaging administered object reference name to be created in External JNDI (-name) ```shell-session # Export first the connection factory @@ -283,4 +283,4 @@ $ ./build/staged/bin/extJndiTest -jndiUrl file:///tmp/ \ : ``` -You have now successfully imported settings into the external JNDI server, then used it to access the Solace message broker for JMS messaging. \ No newline at end of file +You have now successfully imported settings into the external JNDI server, then used it to access the Solace message broker for Jakarta Messaging. \ No newline at end of file diff --git a/src/pages/tutorials/jms/using-jndi.md b/src/pages/tutorials/jms/using-jndi.md index a9e5c20..60868ef 100644 --- a/src/pages/tutorials/jms/using-jndi.md +++ b/src/pages/tutorials/jms/using-jndi.md @@ -1,22 +1,22 @@ --- layout: tutorials -title: Obtaining JMS objects using JNDI -summary: Learn how to use JNDI as a way to create JMS objects. +title: Using Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects +summary: Learn how to use JNDI to look up Jakarta Messaging administered objects. icon: I_dev_JNDI.svg links: - label: QueueProducerJNDI.java - link: /blob/master/src/main/java/com/solace/samples/QueueProducerJNDI.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueProducerJNDI.java - label: QueueConsumerJNDI.java - link: /blob/master/src/main/java/com/solace/samples/QueueConsumerJNDI.java + link: /blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueConsumerJNDI.java - label: feedback link: https://github.com/SolaceDev/solace-dev-tutorials/blob/master/src/pages/tutorials/jms/using-jndi.md --- -This tutorial outlines the use of Java Naming and Directory Interface (JNDI) to create JMS objects including ConnectionFactories and Topic or Queue destinations. The [Publish/Subscribe](../publish-subscribe/) and other tutorials use the approach of programmatically creating these JMS objects, which is usually recommended for developers but JNDI is also a good option which increases the portability of your JMS application code. +This tutorial outlines the use of Java Naming and Directory Interface (JNDI) to look up Jakarta Messaging administered objects including ConnectionFactories and Topic or Queue destinations. The [Publish/Subscribe](../publish-subscribe/) and other tutorials use the approach of programmatically creating these Jakarta Messaging administered objects, which is usually recommended for developers but JNDI is also a good option which increases the portability of your Jakarta Messaging application code. -In this tutorial, we’ll follow the same flow as the [Persistence with Queues](../persistence-with-queues/) tutorial but use JNDI to retrieve the JMS Objects. +In this tutorial, we’ll follow the same flow as the [Persistence with Queues](../persistence-with-queues/) tutorial but use JNDI to retrieve the Jakarta Messaging administered objects. -Obtaining JMS objects using JNDI requires a lookup of a Solace messaging resource by its reference in a JNDI store and then creating a local JMS object from the information returned. With the local JMS object available, the client can start using the associated resource: +Obtaining Jakarta Messaging administered objects using JNDI requires a lookup of a Solace messaging resource by its reference in a JNDI store and then creating a local Jakarta Messaging object from the information returned. With the local Jakarta Messaging object available, the client can start using the associated resource: ![Diagram: Using Jindi](../../../images/diagrams/jndi-tutorial.png) @@ -28,9 +28,9 @@ This tutorial assumes the following: * You are familiar with Solace [core concepts](https://docs.solace.com/PubSub-Basics/Core-Concepts.htm). * You have an understanding or you can refer to the [Persistence with Queues](../persistence-with-queues/) tutorial for - * the Java Messaging Service (JMS) basics - * how to send and receive a message using the JMS API - * how obtain the Solace JMS API + * the Jakarta Messaging basics + * how to send and receive a message using the Jakarta Messaging API + * how to obtain the Solace Jakarta Messaging API * You have access to Solace messaging with the following configuration details: * Connectivity information for a Solace message-VPN configured for guaranteed messaging support * Enabled client username and password @@ -41,11 +41,11 @@ One simple way to get access to Solace messaging quickly is to create a messagin ### Goals -The goal of this tutorial is to demonstrate the use of JNDI as a way to create JMS objects. This tutorial will show you following steps: +The goal of this tutorial is to demonstrate the use of JNDI as a way to look up Jakarta Messaging administered objects. This tutorial will show you following steps: 1. How to configure the JNDI service on Solace messaging -2. How to retrieve a JMS Connection Factory using JNDI so the client can connect to Solace messaging -3. How to lookup a JMS Queue destination object using JNDI so the client can publish or subscribe to it +2. How to retrieve a Jakarta Messaging Connection Factory using JNDI so the client can connect to Solace messaging +3. How to lookup a Jakarta Messaging Queue destination object using JNDI so the client can publish or subscribe to it `markdown:solaceMessaging-part1.md` ![Screenshot: Messaging Connectivity Information](../../../images/screenshots/connectivity-info.png) @@ -54,9 +54,9 @@ The goal of this tutorial is to demonstrate the use of JNDI as a way to create J ## Step 1: Configuring the JNDI service -This tutorial will make use of the same two JMS objects as the [Persistence with Queues](../persistence-with-queues/): +This tutorial will make use of the same two Jakarta Messaging administered objects as the [Persistence with Queues](../persistence-with-queues/): -* A ConnectionFactory object – Used by JMS clients to successfully connect to a message broker like a Solace message router +* A ConnectionFactory object – Used by Jakarta Messaging clients to successfully connect to a message broker like a Solace message router * A Queue Destination – Used for publishing and subscribing to messages. This time we will take the approach of using JNDI lookup to create these objects. @@ -159,9 +159,9 @@ See the [Solace Documentation - Solace Router CLI](https://docs.solace.com/Solac To learn how to use the SEMP API, refer to the [Solace Element Management Protocol (SEMP) tutorials](https://docs.solace.com/SEMP/Using-SEMP.htm). To learn about the Broker Manager application, refer to the [Solace Documentation - Broker Manager Overview](https://docs.solace.com/Broker-Manager/PubSub-Manager-Overview.htm) and the application's online Help. -## Step 2: Obtaining a JMS ConnectionFactory object using JNDI +## Step 2: Obtaining a Jakarta Messaging ConnectionFactory object using JNDI -In order to send or receive messages, an application must connect Solace messaging using a `ConnectionFactory`. The following code shows how to obtain a `ConnectionFactory` JMS object using Solace JNDI. +In order to send or receive messages, an application must connect Solace messaging using a `ConnectionFactory`. The following code shows how to obtain a `ConnectionFactory` Jakarta Messaging object using Solace JNDI. ```java final String CONNECTION_FACTORY_JNDI_NAME = "/JNDI/CF/GettingStarted"; @@ -183,17 +183,17 @@ InitialContext initialContext = new InitialContext(env); ConnectionFactory connectionFactory = (ConnectionFactory) initialContext.lookup(CONNECTION_FACTORY_JNDI_NAME); ``` -### JMS Properties +### Jakarta Messaging Properties -This is a good place to talk about the JMS Properties, which provide access to Solace JMS API functionality that extends the JMS standard. +This is a good place to talk about the Jakarta Messaging Properties, which provide access to Solace Jakarta Messaging API functionality that extends the Jakarta Messaging standard. -JMS Properties can be used to: +Jakarta Messaging Properties can be used to: -* Configure the JNDI or JMS data connection properties such as security, connection retry or timeouts +* Configure the JNDI or Jakarta Messaging data connection properties such as security, connection retry or timeouts * Set message or message delivery properties, such as marking a message as a Reply Message, as seen in the [Request/Reply](../request-reply/) tutorial. * Set general API properties, such as when Dynamic Durables were set to enable dynamic creation of a resource in the [Persistence with Queues](../persistence-with-queues/) tutorial. -JMS Properties can be passed to the API in several ways, allowing flexibility to have them preset or a runtime setting. Here we show the use of `Username` as a JMS Property, which the JMS standard does not define. +Jakarta Messaging Properties can be passed to the API in several ways, allowing flexibility to have them preset or a runtime setting. Here we show the use of `Username` as a Jakarta Messaging Property, which the Jakarta Messaging standard does not define. Following example used above shows the configuration of the JNDI connection runtime with the Username through Initial Context: @@ -219,24 +219,24 @@ Or it could have also been taken as preset default from a `jndi.properties` file java.naming.security.principal=my-username ``` -Some JMS properties can even be configured on Solace messaging and the API will use this setting as a default, for example when the JNDI connection factory Delivery Mode property was set by the CLI script: +Some Jakarta Messaging properties can even be configured on Solace messaging and the API will use this setting as a default, for example when the JNDI connection factory Delivery Mode property was set by the CLI script: ``` property "default-delivery-mode" "persistent" ``` -The [Solace JMS Documentation - JMS Properties Reference](https://docs.solace.com/Solace-JMS-API/JMS-Properties-Reference.htm) provides detailed description of the use and the list of all JMS properties with options how to configure them. It is recommended to carefully consider the effect of the JMS Properties applied in order to achieve the desired configuration goal. +The [Solace Jakarta Messaging Documentation - Jakarta Messaging Properties Reference](https://docs.solace.com/API/Solace-Jakarta-API/Jakarta-Properties-Reference.htm) provides a detailed description of the use and the list of all Jakarta Messaging properties with options how to configure them. It is recommended to carefully consider the effect of the Jakarta Messaging Properties applied in order to achieve the desired configuration goal. ### Connecting to the Solace Messaging -Next, the 'ConnectionFactory' can be used the same way as described in the Persistence with Queues tutorial to create a JMS Connection, at which point your client is connected to Solace messaging and can create a JMS Session. +Next, the 'ConnectionFactory' can be used the same way as described in the Persistence with Queues tutorial to create a Jakarta Messaging Connection, at which point your client is connected to Solace messaging and can create a Jakarta Messaging Session. ```java Connection connection = connectionFactory.createConnection(); final Session session = connection.createSession(false, SupportedProperty.SOL_CLIENT_ACKNOWLEDGE); ``` -## Step 3: Obtaining JMS Destination objects using JNDI +## Step 3: Obtaining Jakarta Messaging Destination objects using JNDI A Queue or Topic destination is needed to send and receive messages. When using JNDI, destination objects are looked up by their JNDI reference. @@ -248,18 +248,18 @@ final String QUEUE_JNDI_NAME = "/JNDI/" + QUEUE_NAME; Queue queue = (Queue) initialContext.lookup(QUEUE_JNDI_NAME); ``` -In contrast to the Persistence with Queues tutorial, the physical queue resource name `Q/tutorial` is not used here directly; it has been associated with `/JNDI/Q/tutorial` when the JNDI reference was created by the CLI script. Also note that same CLI script has already administratively created the physical queue object behind `Q/tutorial` and the `Dynamic Durables` JMS Property does not need to be enabled to automatically create it. +In contrast to the Persistence with Queues tutorial, the physical queue resource name `Q/tutorial` is not used here directly; it has been associated with `/JNDI/Q/tutorial` when the JNDI reference was created by the CLI script. Also note that same CLI script has already administratively created the physical queue object behind `Q/tutorial` and the `Dynamic Durables` Jakarta Messaging Property does not need to be enabled to automatically create it. ### Sending and Receiving messages to a queue -Once the JMS queue object has been created using JNDI, producers and consumers can use it to send and receive messages the same way as described in the Persistence with Queues and other tutorials. +Once the Jakarta Messaging queue object has been created using JNDI, producers and consumers can use it to send and receive messages the same way as described in the Persistence with Queues and other tutorials. ## Summarizing -The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms). If you combine the example source code shown above results in the following source: +The full source code for this example is available in [GitHub](https://github.com/SolaceSamples/solace-samples-jms-jakarta). If you combine the example source code shown above results in the following source: -* [QueueProducerJNDI.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/QueueProducerJNDI.java) -* [QueueConsumerJNDI.java](https://github.com/SolaceSamples/solace-samples-jms/blob/master/src/main/java/com/solace/samples/QueueConsumerJNDI.java) +* [QueueProducerJNDI.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueProducerJNDI.java) +* [QueueConsumerJNDI.java](https://github.com/SolaceSamples/solace-samples-jms-jakarta/blob/master/src/main/java/com/solace/samples/jakarta/messaging/QueueConsumerJNDI.java) ### Getting the Source @@ -267,8 +267,8 @@ The full source code for this example is available in [GitHub](https://github.co Clone the GitHub repository containing the Solace samples. ``` -git clone https://github.com/SolaceSamples/solace-samples-jms -cd solace-samples-jms +git clone https://github.com/SolaceSamples/solace-samples-jms-jakarta +cd solace-samples-jms-jakarta ``` ### Building @@ -279,7 +279,7 @@ Building these examples is simple. You can simply build the project using Gradl ./gradlew assemble ``` -This builds all of the JMS Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. +This builds all of the Jakarta Messaging Getting Started Samples with OS specific launch scripts. The files are staged in the `build/staged` directory. ### Running the Sample