24 | * When the sending of the message is complete, the Jakarta Messaging provider notifies the application by calling the 25 | * {@code onCompletion(Message)} method of the specified completion listener. If the sending if the message fails for 26 | * any reason, and an exception cannot be thrown by the {@code send} method, then the Jakarta Messaging provider calls the 27 | * {@code onException(Exception)} method of the specified completion listener. 28 | * 29 | * @see jakarta.jms.MessageProducer#send(jakarta.jms.Message,int,int,long,jakarta.jms.CompletionListener) 30 | * @see jakarta.jms.MessageProducer#send(jakarta.jms.Destination,jakarta.jms.Message,jakarta.jms.CompletionListener) 31 | * @see jakarta.jms.MessageProducer#send(jakarta.jms.Destination,jakarta.jms.Message,int,int,long,jakarta.jms.CompletionListener) 32 | * @see jakarta.jms.JMSProducer#setAsync(jakarta.jms.CompletionListener) 33 | * @see jakarta.jms.JMSProducer#getAsync() 34 | * 35 | * @version Jakarta Messaging 2.0 36 | * @since JMS 2.0 37 | * 38 | */ 39 | public interface CompletionListener { 40 | 41 | /** 42 | * Notifies the application that the message has been successfully sent 43 | * 44 | * @param message the message that was sent. 45 | */ 46 | void onCompletion(Message message); 47 | 48 | /** 49 | * Notifies user that the specified exception was thrown while attempting to send the specified message. If an exception 50 | * occurs it is undefined whether or not the message was successfully sent. 51 | * 52 | * @param message the message that was sent. 53 | * @param exception the exception 54 | * 55 | */ 56 | void onException(Message message, Exception exception); 57 | } 58 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ConnectionConsumer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * For application servers, {@code Connection} objects provide a special facility for creating a 21 | * {@code ConnectionConsumer} (optional). The messages it is to consume are specified by a {@code Destination} and a 22 | * message selector. In addition, a {@code ConnectionConsumer} must be given a {@code ServerSessionPool} to use for 23 | * processing its messages. 24 | * 25 | *
26 | * Normally, when traffic is light, a {@code ConnectionConsumer} gets a {@code ServerSession} from its pool, loads it 27 | * with a single message, and starts it. As traffic picks up, messages can back up. If this happens, a 28 | * {@code ConnectionConsumer} can load each {@code ServerSession} with more than one message. This reduces the thread 29 | * context switches and minimizes resource use at the expense of some serialization of message processing. 30 | * 31 | * @see jakarta.jms.Connection#createConnectionConsumer 32 | * @see jakarta.jms.Connection#createDurableConnectionConsumer 33 | * @see jakarta.jms.QueueConnection#createConnectionConsumer 34 | * @see jakarta.jms.TopicConnection#createConnectionConsumer 35 | * @see jakarta.jms.TopicConnection#createDurableConnectionConsumer 36 | * 37 | * @version Jakarta Messaging 2.0 38 | * @since JMS 1.0 39 | * 40 | */ 41 | public interface ConnectionConsumer { 42 | 43 | /** 44 | * Gets the server session pool associated with this connection consumer. 45 | * 46 | * @return the server session pool used by this connection consumer 47 | * 48 | * @exception JMSException if the Jakarta Messaging provider fails to get the server session pool associated with this consumer due to 49 | * some internal error. 50 | */ 51 | ServerSessionPool getServerSessionPool() throws JMSException; 52 | 53 | /** 54 | * Closes the connection consumer. 55 | * 56 | *
57 | * Since a provider may allocate some resources on behalf of a connection consumer outside the Java virtual machine, 58 | * clients should close these resources when they are not needed. Relying on garbage collection to eventually reclaim 59 | * these resources may not be timely enough. 60 | * 61 | * @exception JMSException if the Jakarta Messaging provider fails to release resources on behalf of the connection consumer or fails 62 | * to close the connection consumer. 63 | */ 64 | 65 | void close() throws JMSException; 66 | } 67 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ConnectionMetaData.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import java.util.Enumeration; 20 | 21 | /** 22 | * A {@code ConnectionMetaData} object provides information describing the {@code Connection} object. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 1.0 26 | */ 27 | public interface ConnectionMetaData { 28 | 29 | /** 30 | * Gets the Jakarta Messaging API version. 31 | * 32 | * @return the Jakarta Messaging API version 33 | * 34 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 35 | */ 36 | String getJMSVersion() throws JMSException; 37 | 38 | /** 39 | * Gets the Jakarta Messaging major version number. 40 | * 41 | * @return the Jakarta Messaging API major version number 42 | * 43 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 44 | */ 45 | int getJMSMajorVersion() throws JMSException; 46 | 47 | /** 48 | * Gets the Jakarta Messaging minor version number. 49 | * 50 | * @return the Jakarta Messaging API minor version number 51 | * 52 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 53 | */ 54 | int getJMSMinorVersion() throws JMSException; 55 | 56 | /** 57 | * Gets the Jakarta Messaging provider name. 58 | * 59 | * @return the Jakarta Messaging provider name 60 | * 61 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 62 | */ 63 | String getJMSProviderName() throws JMSException; 64 | 65 | /** 66 | * Gets the Jakarta Messaging provider version. 67 | * 68 | * @return the Jakarta Messaging provider version 69 | * 70 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 71 | */ 72 | String getProviderVersion() throws JMSException; 73 | 74 | /** 75 | * Gets the Jakarta Messaging provider major version number. 76 | * 77 | * @return the Jakarta Messaging provider major version number 78 | * 79 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 80 | */ 81 | int getProviderMajorVersion() throws JMSException; 82 | 83 | /** 84 | * Gets the Jakarta Messaging provider minor version number. 85 | * 86 | * @return the Jakarta Messaging provider minor version number 87 | * 88 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 89 | */ 90 | int getProviderMinorVersion() throws JMSException; 91 | 92 | /** 93 | * Gets an enumeration of the JMSX property names. 94 | * 95 | * @return an Enumeration of JMSX property names 96 | * 97 | * @exception JMSException if the Jakarta Messaging provider fails to retrieve the metadata due to some internal error. 98 | */ 99 | Enumeration getJMSXPropertyNames() throws JMSException; 100 | } 101 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/DeliveryMode.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * The delivery modes supported by the Jakarta Messaging API are {@code PERSISTENT} and {@code NON_PERSISTENT}. 21 | * 22 | *
23 | * A client marks a message as persistent if it feels that the application will have problems if the message is lost in 24 | * transit. A client marks a message as non-persistent if an occasional lost message is tolerable. Clients use delivery 25 | * mode to tell a Jakarta Messaging provider how to balance message transport reliability with throughput. 26 | * 27 | *
28 | * Delivery mode covers only the transport of the message to its destination. Retention of a message at the destination 29 | * until its receipt is acknowledged is not guaranteed by a {@code PERSISTENT} delivery mode. Clients should assume that 30 | * message retention policies are set administratively. Message retention policy governs the reliability of message 31 | * delivery from destination to message consumer. For example, if a client's message storage space is exhausted, some 32 | * messages may be dropped in accordance with a site-specific message retention policy. 33 | * 34 | *
35 | * A message is guaranteed to be delivered once and only once by a Jakarta Messaging provider if the delivery mode of the message is 36 | * {@code PERSISTENT} and if the destination has a sufficient message retention policy. 37 | * 38 | * @version Jakarta Messaging 2.0 39 | * @since JMS 1.0 40 | */ 41 | public interface DeliveryMode { 42 | 43 | /** 44 | * This is the lowest-overhead delivery mode because it does not require that the message be logged to stable storage. 45 | * The level of Jakarta Messaging provider failure that causes a {@code NON_PERSISTENT} message to be lost is not defined. 46 | * 47 | *
48 | * A Jakarta Messaging provider must deliver a {@code NON_PERSISTENT} message with an at-most-once guarantee. This means that it may 49 | * lose the message, but it must not deliver it twice. 50 | */ 51 | int NON_PERSISTENT = 1; 52 | 53 | /** 54 | * This delivery mode instructs the Jakarta Messaging provider to log the message to stable storage as part of the client's send 55 | * operation. Only a hard media failure should cause a {@code PERSISTENT} message to be lost. 56 | */ 57 | int PERSISTENT = 2; 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/Destination.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code Destination} object encapsulates a provider-specific address. The Jakarta Messaging API does not define a standard address 21 | * syntax. Although a standard address syntax was considered, it was decided that the differences in address semantics 22 | * between existing message-oriented middleware (MOM) products were too wide to bridge with a single syntax. 23 | * 24 | *
25 | * Since {@code Destination} is an administered object, it may contain provider-specific configuration information in 26 | * addition to its address. 27 | * 28 | *
29 | * The Jakarta Messaging API also supports a client's use of provider-specific address names. 30 | * 31 | *
32 | * {@code Destination} objects support concurrent use. 33 | * 34 | *
35 | * A {@code Destination} object is a Jakarta Messaging administered object. 36 | * 37 | *
38 | * Jakarta Messaging administered objects are objects containing configuration information that are created by an administrator and 39 | * later used by Jakarta Messaging clients. They make it practical to administer the Jakarta Messaging API in the enterprise. 40 | * 41 | *
42 | * Although the interfaces for administered objects do not explicitly depend on the Java Naming and Directory Interface 43 | * (JNDI) API, the Jakarta Messaging API establishes the convention that Jakarta Messaging clients find administered objects by looking them up in a 44 | * JNDI namespace. 45 | * 46 | *
47 | * An administrator can place an administered object anywhere in a namespace. The Jakarta Messaging API does not define a naming 48 | * policy. 49 | * 50 | *
51 | * It is expected that Jakarta Messaging providers will provide the tools an administrator needs to create and configure administered 52 | * objects in a JNDI namespace. Jakarta Messaging provider implementations of administered objects should implement the 53 | * {@code javax.naming.Referenceable} and {@code java.io.Serializable} interfaces so that they can be stored in all JNDI 54 | * naming contexts. In addition, it is recommended that these implementations follow the 55 | * JavaBeansTM design patterns. 56 | * 57 | *
58 | * This strategy provides several benefits: 59 | * 60 | *
69 | * An administered object should not hold on to any remote resources. Its lookup should not use remote resources other 70 | * than those used by the JNDI API itself. 71 | * 72 | *
73 | * Clients should think of administered objects as local Java objects. Looking them up should not have any hidden side 74 | * effects or use surprising amounts of local resources. 75 | * 76 | * @see jakarta.jms.Queue 77 | * @see jakarta.jms.Topic 78 | * 79 | * @version Jakarta Messaging 2.0 80 | * @since JMS 1.0 81 | * 82 | */ 83 | public interface Destination { 84 | } 85 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ExceptionListener.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * If a Jakarta Messaging provider detects a serious problem with a {@code Connection} object, it informs the {@code Connection} 21 | * object's {@code ExceptionListener}, if one has been registered. It does this by calling the listener's 22 | * {@code onException} method, passing it a {@code JMSException} argument describing the problem. 23 | * 24 | *
25 | * An exception listener allows a client to be notified of a problem asynchronously. Some connections only consume 26 | * messages, so they would have no other way to learn that their connection has failed. 27 | * 28 | *
29 | * A Jakarta Messaging provider should attempt to resolve connection problems itself before it notifies the client of them. 30 | * 31 | * @see jakarta.jms.Connection#setExceptionListener(ExceptionListener) 32 | * 33 | * @version Jakarta Messaging 2.0 34 | * @since JMS 1.0 35 | * 36 | */ 37 | public interface ExceptionListener { 38 | 39 | /** 40 | * Notifies user of a Jakarta Messaging exception. 41 | * 42 | * @param exception the Jakarta Messaging exception 43 | */ 44 | void onException(JMSException exception); 45 | } 46 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/IllegalStateException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | *
22 | * This exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is not in an 23 | * appropriate state for the requested operation. For example, this exception must be thrown if {@code Session.commit} 24 | * is called on a non-transacted session. This exception is also called when a domain inappropriate method is called, 25 | * such as calling {@code TopicSession.CreateQueueBrowser}. 26 | * 27 | * @version Jakarta Messaging 2.0 28 | * @since JMS 1.0 29 | * 30 | **/ 31 | public class IllegalStateException extends JMSException { 32 | 33 | /** 34 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 35 | */ 36 | private static final long serialVersionUID = -6850763061112244487L; 37 | 38 | /** 39 | * Constructs an {@code IllegalStateException} with the specified reason, error code 40 | * and linked exception. 41 | * 42 | * @param reason a description of the exception 43 | * @param errorCode a string specifying the vendor-specific error code 44 | * @param linkedException a linked exception 45 | * 46 | **/ 47 | public IllegalStateException(String reason, String errorCode, Exception linkedException) { 48 | super(reason, errorCode, linkedException); 49 | } 50 | 51 | /** 52 | * Constructs an {@code IllegalStateException} with the specified reason and error code. 53 | * 54 | * @param reason a description of the exception 55 | * @param errorCode a string specifying the vendor-specific error code 56 | * 57 | **/ 58 | public IllegalStateException(String reason, String errorCode) { 59 | super(reason, errorCode); 60 | } 61 | 62 | /** 63 | * Constructs an {@code IllegalStateException} with the specified reason. The error code defaults to null. 64 | * 65 | * @param reason a description of the exception 66 | **/ 67 | public IllegalStateException(String reason) { 68 | super(reason); 69 | } 70 | 71 | } 72 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/IllegalStateRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is 21 | * not in an appropriate state for the requested operation, and the method signature does not permit a 22 | * {@code IllegalStateRuntimeException} to be thrown. For example, this exception must be thrown if 23 | * {@code JMSContext.commit} is called on a non-transacted session. 24 | * 25 | * @version Jakarta Messaging 2.0 26 | * @since JMS 2.0 27 | * 28 | **/ 29 | public class IllegalStateRuntimeException extends JMSRuntimeException { 30 | 31 | /** 32 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 33 | */ 34 | private static final long serialVersionUID = 6838714637432837899L; 35 | 36 | /** 37 | * Constructs a {@code IllegalStateRuntimeException} with the specified detail message 38 | * 39 | * @param detailMessage a description of the exception 40 | **/ 41 | public IllegalStateRuntimeException(String detailMessage) { 42 | super(detailMessage); 43 | } 44 | 45 | /** 46 | * Constructs a {@code IllegalStateRuntimeException} with the specified detail message and error code. 47 | * 48 | * @param detailMessage a description of the exception 49 | * @param errorCode a provider-specific error code 50 | **/ 51 | public IllegalStateRuntimeException(String detailMessage, String errorCode) { 52 | super(detailMessage, errorCode); 53 | } 54 | 55 | /** 56 | * Constructs a {@code IllegalStateRuntimeException} with the specified detail message, error code and cause 57 | * 58 | * @param detailMessage a description of the exception 59 | * @param errorCode a provider-specific error code 60 | * @param cause the underlying cause of this exception 61 | */ 62 | public IllegalStateRuntimeException(String detailMessage, String errorCode, Throwable cause) { 63 | super(detailMessage, errorCode, cause); 64 | } 65 | 66 | } 67 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidClientIDException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | *
22 | * This exception must be thrown when a client attempts to set a connection's client ID to a value that is rejected by a 23 | * provider. 24 | * 25 | * @version Jakarta Messaging 2.0 26 | * @since JMS 1.0 27 | * 28 | **/ 29 | public class InvalidClientIDException extends JMSException { 30 | 31 | /** 32 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 33 | */ 34 | private static final long serialVersionUID = 2410181719763491702L; 35 | 36 | /** 37 | * Constructs an {@code InvalidClientIDException} with the specified reason, error code 38 | * and linked exception. 39 | * 40 | * @param reason a description of the exception 41 | * @param errorCode a string specifying the vendor-specific error code 42 | * @param linkedException a linked exception 43 | * 44 | **/ 45 | public InvalidClientIDException(String reason, String errorCode, Exception linkedException) { 46 | super(reason, errorCode, linkedException); 47 | } 48 | 49 | /** 50 | * Constructs an {@code InvalidClientIDException} with the specified reason and error code. 51 | * 52 | * @param reason a description of the exception 53 | * @param errorCode a string specifying the vendor-specific error code 54 | * 55 | **/ 56 | public InvalidClientIDException(String reason, String errorCode) { 57 | super(reason, errorCode); 58 | } 59 | 60 | /** 61 | * Constructs an {@code InvalidClientIDException} with the specified reason. The error code defaults to null. 62 | * 63 | * @param reason a description of the exception 64 | **/ 65 | public InvalidClientIDException(String reason) { 66 | super(reason); 67 | } 68 | 69 | } 70 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidClientIDRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a client attempts to set a connection's client ID to a value that is 21 | * rejected by a provider, and the method signature does not permit a {@code InvalidClientIDException} to be thrown. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 2.0 25 | * 26 | **/ 27 | public class InvalidClientIDRuntimeException extends JMSRuntimeException { 28 | 29 | /** 30 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 31 | */ 32 | private static final long serialVersionUID = -1997236208457896631L; 33 | 34 | /** 35 | * Constructs a {@code InvalidClientIDRuntimeException} with the specified detail message 36 | * 37 | * @param detailMessage a description of the exception 38 | **/ 39 | public InvalidClientIDRuntimeException(String detailMessage) { 40 | super(detailMessage); 41 | } 42 | 43 | /** 44 | * Constructs a {@code InvalidClientIDRuntimeException} with the specified detail message and error code. 45 | * 46 | * @param detailMessage a description of the exception 47 | * @param errorCode a provider-specific error code 48 | **/ 49 | public InvalidClientIDRuntimeException(String detailMessage, String errorCode) { 50 | super(detailMessage, errorCode); 51 | } 52 | 53 | /** 54 | * Constructs a {@code InvalidClientIDRuntimeException} with the specified detail message, error code and cause 55 | * 56 | * @param detailMessage a description of the exception 57 | * @param errorCode a provider-specific error code 58 | * @param cause the underlying cause of this exception 59 | */ 60 | public InvalidClientIDRuntimeException(String detailMessage, String errorCode, Throwable cause) { 61 | super(detailMessage, errorCode, cause); 62 | } 63 | } 64 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidDestinationException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | *
22 | * This exception must be thrown when a destination either is not understood by a provider or is no longer valid. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 1.0 26 | * 27 | **/ 28 | public class InvalidDestinationException extends JMSException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 32 | */ 33 | private static final long serialVersionUID = -8588063794606036755L; 34 | 35 | /** 36 | * Constructs an {@code InvalidDestinationException} with the specified reason, error code 37 | * and linked exception. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * @param linkedException a linked exception 42 | * 43 | **/ 44 | public InvalidDestinationException(String reason, String errorCode, Exception linkedException) { 45 | super(reason, errorCode, linkedException); 46 | } 47 | 48 | /** 49 | * Constructs an {@code InvalidDestinationException} with the specified reason and error code. 50 | * 51 | * @param reason a description of the exception 52 | * @param errorCode a string specifying the vendor-specific error code 53 | * 54 | **/ 55 | public InvalidDestinationException(String reason, String errorCode) { 56 | super(reason, errorCode); 57 | } 58 | 59 | /** 60 | * Constructs an {@code InvalidDestinationException} with the specified reason. The error code defaults to null. 61 | * 62 | * @param reason a description of the exception 63 | **/ 64 | public InvalidDestinationException(String reason) { 65 | super(reason); 66 | } 67 | 68 | } 69 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidDestinationRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a destination either is not understood by a provider or is no longer 21 | * valid, and the method signature does not permit a {@code InvalidDestinationException} to be thrown. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 2.0 25 | * 26 | **/ 27 | public class InvalidDestinationRuntimeException extends JMSRuntimeException { 28 | 29 | /** 30 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 31 | */ 32 | private static final long serialVersionUID = 2765276997130843763L; 33 | 34 | /** 35 | * Constructs a {@code InvalidDestinationRuntimeException} with the specified detail message 36 | * 37 | * @param detailMessage a description of the exception 38 | **/ 39 | public InvalidDestinationRuntimeException(String detailMessage) { 40 | super(detailMessage); 41 | } 42 | 43 | /** 44 | * Constructs a {@code InvalidDestinationRuntimeException} with the specified detail message and error code. 45 | * 46 | * @param detailMessage a description of the exception 47 | * @param errorCode a provider-specific error code 48 | **/ 49 | public InvalidDestinationRuntimeException(String detailMessage, String errorCode) { 50 | super(detailMessage, errorCode); 51 | } 52 | 53 | /** 54 | * Constructs a {@code InvalidDestinationRuntimeException} with the specified detail message, error code and cause 55 | * 56 | * @param detailMessage a description of the exception 57 | * @param errorCode a provider-specific error code 58 | * @param cause the underlying cause of this exception 59 | */ 60 | public InvalidDestinationRuntimeException(String detailMessage, String errorCode, Throwable cause) { 61 | super(detailMessage, errorCode, cause); 62 | } 63 | 64 | } 65 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidSelectorException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | *
22 | * This exception must be thrown when a Jakarta Messaging client attempts to give a provider a message selector with invalid syntax. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 1.0 26 | * 27 | **/ 28 | public class InvalidSelectorException extends JMSException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 32 | */ 33 | private static final long serialVersionUID = 6223038613086963841L; 34 | 35 | /** 36 | * Constructs an {@code InvalidSelectorException} with the specified reason, error code 37 | * and linked exception. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * @param linkedException a linked exception 42 | * 43 | **/ 44 | public InvalidSelectorException(String reason, String errorCode, Exception linkedException) { 45 | super(reason, errorCode, linkedException); 46 | } 47 | 48 | /** 49 | * Constructs an {@code InvalidSelectorException} with the specified reason and error code. 50 | * 51 | * @param reason a description of the exception 52 | * @param errorCode a string specifying the vendor-specific error code 53 | * 54 | **/ 55 | public InvalidSelectorException(String reason, String errorCode) { 56 | super(reason, errorCode); 57 | } 58 | 59 | /** 60 | * Constructs an {@code InvalidSelectorException} with the specified reason. The error code defaults to null. 61 | * 62 | * @param reason a description of the exception 63 | **/ 64 | public InvalidSelectorException(String reason) { 65 | super(reason); 66 | } 67 | 68 | } 69 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/InvalidSelectorRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a Jakarta Messaging client attempts to give a provider a message selector with invalid 21 | * syntax, and the method signature does not permit a {@code InvalidSelectorException} to be thrown. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 2.0 25 | * 26 | **/ 27 | public class InvalidSelectorRuntimeException extends JMSRuntimeException { 28 | 29 | /** 30 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 31 | */ 32 | private static final long serialVersionUID = 1974783946275023548L; 33 | 34 | /** 35 | * Constructs a {@code InvalidSelectorRuntimeException} with the specified detail message 36 | * 37 | * @param detailMessage a description of the exception 38 | **/ 39 | public InvalidSelectorRuntimeException(String detailMessage) { 40 | super(detailMessage); 41 | } 42 | 43 | /** 44 | * Constructs a {@code InvalidSelectorRuntimeException} with the specified detail message and error code. 45 | * 46 | * @param detailMessage a description of the exception 47 | * @param errorCode a provider-specific error code 48 | **/ 49 | public InvalidSelectorRuntimeException(String detailMessage, String errorCode) { 50 | super(detailMessage, errorCode); 51 | } 52 | 53 | /** 54 | * Constructs a {@code InvalidSelectorRuntimeException} with the specified detail message, error code and cause 55 | * 56 | * @param detailMessage a description of the exception 57 | * @param errorCode a provider-specific error code 58 | * @param cause the underlying cause of this exception 59 | */ 60 | public InvalidSelectorRuntimeException(String detailMessage, String errorCode, Throwable cause) { 61 | super(detailMessage, errorCode, cause); 62 | } 63 | 64 | } 65 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import static java.lang.annotation.ElementType.FIELD; 20 | import static java.lang.annotation.ElementType.METHOD; 21 | import static java.lang.annotation.ElementType.PARAMETER; 22 | import static java.lang.annotation.ElementType.TYPE; 23 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 24 | 25 | import java.lang.annotation.Retention; 26 | import java.lang.annotation.Target; 27 | 28 | /** 29 | * This annotation may be used on a field to specify the JNDI lookup name of a {@code jakarta.jms.ConnectionFactory} to be 30 | * used when injecting a {@code jakarta.jms.JMSContext} object. 31 | * 32 | *
33 | * It may also be used to specify that a callback method on a Jakarta Messaging message-driven bean must use the specified message 34 | * selector. In this case it may be specified either on the callback method or on the message-driven bean class. 35 | * 36 | *
37 | * If this annotation is specified on a method of a message-driven bean class then that method must also be annotated 38 | * with {@code QueueListener} or {@code TopicListener}. If it is not then deployment will fail. 39 | * 40 | *
41 | * If this annotation is specified on the message-driven bean class then at least one method must be annotated with 42 | * {@code QueueListener} or {@code TopicListener}. If no method is annotated with {@code QueueListener} or 43 | * {@code TopicListener} then deployment will fail. 44 | * 45 | *
46 | * If this annotation is specified on both a method of a message-driven bean class and on the message-driven bean class 47 | * itself then deployment will fail. 48 | * 49 | * @version Jakarta Messaging 2.0 50 | * @since JMS 2.0 51 | */ 52 | @Retention(RUNTIME) 53 | @Target({ METHOD, FIELD, PARAMETER, TYPE }) 54 | public @interface JMSConnectionFactory { 55 | 56 | /** 57 | * Specifies the JNDI lookup name of a {@code jakarta.jms.ConnectionFactory} to be used. 58 | * 59 | * @return the JNDI lookup name of a {@code jakarta.jms.ConnectionFactory} to be used 60 | */ 61 | String value(); 62 | } 63 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSConnectionFactoryDefinition.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import static java.lang.annotation.ElementType.TYPE; 20 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 21 | 22 | import java.lang.annotation.Repeatable; 23 | import java.lang.annotation.Retention; 24 | import java.lang.annotation.Target; 25 | 26 | /** 27 | * An application may use this annotation to specify a Jakarta Messaging {@code 28 | * ConnectionFactory} resource that it requires in its operational environment. This provides information that can be 29 | * used at the application's deployment to provision the required resource and allows an application to be deployed into 30 | * a Jakarta EE environment with more minimal administrative configuration. 31 | *
32 | * The {@code ConnectionFactory} resource may be configured by setting the annotation elements for commonly used 33 | * properties. Additional properties may be specified using the {@code properties} element. Once defined, a 34 | * {@code ConnectionFactory} resource may be referenced by a component in the same way as any other 35 | * {@code ConnectionFactory} resource, for example by using the {@code lookup} element of the {@code Resource} 36 | * annotation. 37 | * 38 | * @version Jakarta Messaging 2.0 39 | * @since JMS 2.0 40 | * 41 | * @see jakarta.annotation.Resource 42 | */ 43 | @Target(TYPE) 44 | @Retention(RUNTIME) 45 | @Repeatable(JMSConnectionFactoryDefinitions.class) 46 | public @interface JMSConnectionFactoryDefinition { 47 | 48 | /** 49 | * Description of this Jakarta Messaging connection factory. 50 | * 51 | * @return The description of this Jakarta Messaging connection factory. 52 | */ 53 | String description() default ""; 54 | 55 | /** 56 | * JNDI name of the Jakarta Messaging connection factory being defined. 57 | * 58 | * @return The JNDI name of the Jakarta Messaging connection factory being defined. 59 | */ 60 | String name(); 61 | 62 | /** 63 | * Fully qualified name of the Jakarta Messaging connection factory interface. Permitted values are 64 | * {@code jakarta.jms.ConnectionFactory} or {@code jakarta.jms.QueueConnectionFactory} or 65 | * {@code jakarta.jms.TopicConnectionFactory}. If not specified then {@code jakarta.jms.ConnectionFactory} will be used. 66 | * 67 | * @return The fully qualified name of the Jakarta Messaging connection factory interface. 68 | */ 69 | String interfaceName() default "jakarta.jms.ConnectionFactory"; 70 | 71 | /** 72 | * Fully-qualified name of the Jakarta Messaging connection factory implementation class. Ignored if a resource adapter is used. 73 | * 74 | * @return The fully-qualified name of the Jakarta Messaging connection factory implementation class. 75 | */ 76 | String className() default ""; 77 | 78 | /** 79 | * Resource adapter name. If not specified then the application server will define the default behaviour, which may or 80 | * may not involve the use of a resource adapter. 81 | * 82 | * @return The resource adapter name. 83 | */ 84 | String resourceAdapter() default ""; 85 | 86 | /** 87 | * User name to use for connection authentication. 88 | * 89 | * @return The user name to use for connection authentication. 90 | */ 91 | String user() default ""; 92 | 93 | /** 94 | * Password to use for connection authentication. 95 | * 96 | * @return The password to use for connection authentication. 97 | */ 98 | String password() default ""; 99 | 100 | /** 101 | * Client id to use for connection. 102 | * 103 | * @return The client id to use for connection. 104 | */ 105 | String clientId() default ""; 106 | 107 | /** 108 | * Jakarta Messaging connection factory property. This may be a vendor-specific property or a less commonly used 109 | * {@code ConnectionFactory} property. 110 | * 111 | *
112 | * Properties are specified using the format: propertyName=propertyValue with one property per array element. 113 | * 114 | * @return The Jakarta Messaging connection factory property. 115 | */ 116 | String[] properties() default {}; 117 | 118 | /** 119 | * Set to {@code false} if connections should not participate in transactions. 120 | * 121 | *
122 | * Default is to enlist in a transaction when one is active or becomes active. 123 | * 124 | * @return Whether connections should participate in transactions. 125 | */ 126 | boolean transactional() default true; 127 | 128 | /** 129 | * Maximum number of connections that should be concurrently allocated for a connection pool. 130 | * 131 | *
132 | * Default is vendor-specific. 133 | * 134 | * @return The maximum number of connections that should be concurrently allocated for a connection pool. 135 | */ 136 | int maxPoolSize() default -1; 137 | 138 | /** 139 | * Minimum number of connections that should be concurrently allocated for a connection pool. 140 | * 141 | *
142 | * Default is vendor-specific. 143 | * 144 | * @return The minimum number of connections that should be concurrently allocated for a connection pool. 145 | */ 146 | int minPoolSize() default -1; 147 | 148 | } 149 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSConnectionFactoryDefinitions.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import static java.lang.annotation.ElementType.TYPE; 20 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 21 | 22 | import java.lang.annotation.Retention; 23 | import java.lang.annotation.Target; 24 | 25 | /** 26 | * Specifies one or more {@code JMSConnectionFactoryDefinition} annotations. 27 | * 28 | * @version Jakarta Messaging 2.0 29 | * @since JMS 2.0 30 | * 31 | * @see JMSConnectionFactoryDefinition 32 | */ 33 | @Target(TYPE) 34 | @Retention(RUNTIME) 35 | public @interface JMSConnectionFactoryDefinitions { 36 | 37 | JMSConnectionFactoryDefinition[] value(); 38 | } 39 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSDestinationDefinition.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | import java.lang.annotation.ElementType; 21 | import java.lang.annotation.Repeatable; 22 | import java.lang.annotation.Retention; 23 | import java.lang.annotation.RetentionPolicy; 24 | import java.lang.annotation.Target; 25 | 26 | /** 27 | * An application may use this annotation to specify a Jakarta Messaging {@code 28 | * Destination} resource that it requires in its operational environment. This provides information that can be used at 29 | * the application's deployment to provision the required resource and allows an application to be deployed into a Java 30 | * EE environment with more minimal administrative configuration. 31 | * 32 | *
33 | * The {@code Destination} resource may be configured by setting the annotation elements for commonly used properties. 34 | * Additional properties may be specified using the {@code properties} element. Once defined, a {@code Destination} 35 | * resource may be referenced by a component in the same way as any other {@code Destination} resource, for example by 36 | * using the {@code lookup} element of the {@code Resource} annotation. 37 | * 38 | * @see jakarta.annotation.Resource 39 | * 40 | * @version Jakarta Messaging 2.0 41 | * @since JMS 2.0 42 | * 43 | */ 44 | @Target({ ElementType.TYPE }) 45 | @Retention(RetentionPolicy.RUNTIME) 46 | @Repeatable(JMSDestinationDefinitions.class) 47 | public @interface JMSDestinationDefinition { 48 | 49 | /** 50 | * Description of this Jakarta Messaging destination. 51 | * 52 | * @return The description of this Jakarta Messaging destination. 53 | */ 54 | String description() default ""; 55 | 56 | /** 57 | * JNDI name of the destination resource being defined. 58 | * 59 | * @return The JNDI name of the destination resource being defined. 60 | */ 61 | String name(); 62 | 63 | /** 64 | * Fully qualified name of the Jakarta Messaging destination interface. Permitted values are {@code jakarta.jms.Queue} or 65 | * {@code jakarta.jms.Topic}. 66 | * 67 | * @return The fully qualified name of the Jakarta Messaging destination interface. 68 | */ 69 | String interfaceName(); 70 | 71 | /** 72 | * Fully-qualified name of the Jakarta Messaging destination implementation class. Ignored if a resource adapter is used unless the 73 | * resource adapter defines more than one Jakarta Messaging destination implementation class for the specified interface. 74 | * 75 | * @return The fully-qualified name of the Jakarta Messaging destination implementation class. 76 | */ 77 | String className() default ""; 78 | 79 | /** 80 | * Resource adapter name. If not specified then the application server will define the default behaviour, which may or 81 | * may not involve the use of a resource adapter. 82 | * 83 | * @return The resource adapter name. 84 | */ 85 | String resourceAdapter() default ""; 86 | 87 | /** 88 | * Name of the queue or topic. 89 | * 90 | * @return The name of the queue or topic. 91 | */ 92 | String destinationName() default ""; 93 | 94 | /** 95 | * Jakarta Messaging destination property. This may be a vendor-specific property or a less commonly used destination 96 | * property. 97 | * 98 | *
99 | * Properties are specified using the format: propertyName=propertyValue with one property per array element. 100 | * 101 | * @return The Jakarta Messaging destination properties. 102 | */ 103 | String[] properties() default {}; 104 | } 105 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSDestinationDefinitions.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import static java.lang.annotation.ElementType.TYPE; 20 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 21 | 22 | import java.lang.annotation.Retention; 23 | import java.lang.annotation.Target; 24 | 25 | /** 26 | * Specifies one or more {@code JMSDestinationDefinition} annotations. 27 | * 28 | * @see JMSDestinationDefinition 29 | * 30 | * @version Jakarta Messaging 2.0 31 | * @since JMS 2.0 32 | * 33 | */ 34 | @Target(TYPE) 35 | @Retention(RUNTIME) 36 | public @interface JMSDestinationDefinitions { 37 | 38 | JMSDestinationDefinition[] value(); 39 | } 40 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | *
22 | * This is the root class of all checked exceptions in the Jakarta Messaging API. 23 | * 24 | *
25 | * It provides the following information: 26 | *
23 | * In additional to the detailMessage and cause fields inherited from {@code Throwable}, this class also allows a 24 | * provider-specific errorCode to be set. 25 | * 26 | * @version Jakarta Messaging 2.0 27 | * @since JMS 2.0 28 | * 29 | **/ 30 | public class JMSRuntimeException extends RuntimeException { 31 | 32 | /** 33 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 34 | */ 35 | private static final long serialVersionUID = -5204332229969809982L; 36 | 37 | /** 38 | * Provider-specific error code. 39 | **/ 40 | private String errorCode = null; 41 | 42 | /** 43 | * Constructs a {@code JMSRuntimeException} with the specified detail message and error code. 44 | * 45 | * @param detailMessage a description of the exception 46 | * @param errorCode a provider-specific error code 47 | **/ 48 | public JMSRuntimeException(String detailMessage, String errorCode) { 49 | super(detailMessage); 50 | this.errorCode = errorCode; 51 | } 52 | 53 | /** 54 | * Constructs a {@code JMSRuntimeException} with the specified detail message 55 | * 56 | * @param detailMessage a description of the exception 57 | **/ 58 | public JMSRuntimeException(String detailMessage) { 59 | super(detailMessage); 60 | } 61 | 62 | /** 63 | * Constructs a {@code JMSRuntimeException} with the specified detail message, error code and cause 64 | * 65 | * @param detailMessage a description of the exception 66 | * @param errorCode a provider-specific error code 67 | * @param cause the underlying cause of this exception 68 | */ 69 | public JMSRuntimeException(String detailMessage, String errorCode, Throwable cause) { 70 | super(detailMessage, cause); 71 | this.errorCode = errorCode; 72 | } 73 | 74 | /** 75 | * Returns the vendor-specific error code. 76 | * 77 | * @return the provider-specific error code 78 | **/ 79 | public String getErrorCode() { 80 | return this.errorCode; 81 | } 82 | } 83 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSSecurityException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when a provider rejects a user name/password submitted by a client. It may also be 22 | * thrown for any case where a security restriction prevents a method from completing. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 1.0 26 | * 27 | **/ 28 | public class JMSSecurityException extends JMSException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 32 | */ 33 | private static final long serialVersionUID = -7512859695190450217L; 34 | 35 | /** 36 | * Constructs a {@code JMSSecurityException} with the specified reason, error code 37 | * and linked exception. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * @param linkedException a linked exception 42 | * 43 | **/ 44 | public JMSSecurityException(String reason, String errorCode, Exception linkedException) { 45 | super(reason, errorCode, linkedException); 46 | } 47 | 48 | /** 49 | * Constructs a {@code JMSSecurityException} with the specified reason and error code. 50 | * 51 | * @param reason a description of the exception 52 | * @param errorCode a string specifying the vendor-specific error code 53 | * 54 | **/ 55 | public JMSSecurityException(String reason, String errorCode) { 56 | super(reason, errorCode); 57 | } 58 | 59 | /** 60 | * Constructs a {@code JMSSecurityException} with the specified reason. The error code defaults to null. 61 | * 62 | * @param reason a description of the exception 63 | **/ 64 | public JMSSecurityException(String reason) { 65 | super(reason); 66 | } 67 | 68 | } 69 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSSecurityRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a provider rejects a user name/password submitted by a client, or for 21 | * any case where a security restriction prevents a method from completing, and the method signature does not permit a 22 | * {@code JMSSecurityException} to be thrown. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 2.0 26 | * 27 | **/ 28 | public class JMSSecurityRuntimeException extends JMSRuntimeException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 32 | */ 33 | private static final long serialVersionUID = 1020149469192845616L; 34 | 35 | /** 36 | * Constructs a {@code JMSSecurityRuntimeException} with the specified detail message 37 | * 38 | * @param detailMessage a description of the exception 39 | **/ 40 | public JMSSecurityRuntimeException(String detailMessage) { 41 | super(detailMessage); 42 | } 43 | 44 | /** 45 | * Constructs a {@code JMSSecurityRuntimeException} with the specified detail message and error code. 46 | * 47 | * @param detailMessage a description of the exception 48 | * @param errorCode a provider-specific error code 49 | **/ 50 | public JMSSecurityRuntimeException(String detailMessage, String errorCode) { 51 | super(detailMessage, errorCode); 52 | } 53 | 54 | /** 55 | * Constructs a {@code JMSSecurityRuntimeException} with the specified detail message, error code and cause 56 | * 57 | * @param detailMessage a description of the exception 58 | * @param errorCode a provider-specific error code 59 | * @param cause the underlying cause of this exception 60 | */ 61 | public JMSSecurityRuntimeException(String detailMessage, String errorCode, Throwable cause) { 62 | super(detailMessage, errorCode, cause); 63 | } 64 | 65 | } 66 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/JMSSessionMode.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import static java.lang.annotation.ElementType.FIELD; 20 | import static java.lang.annotation.ElementType.METHOD; 21 | import static java.lang.annotation.ElementType.PARAMETER; 22 | import static java.lang.annotation.ElementType.TYPE; 23 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 24 | import static jakarta.jms.JMSContext.AUTO_ACKNOWLEDGE; 25 | 26 | import java.lang.annotation.Retention; 27 | import java.lang.annotation.Target; 28 | 29 | /** 30 | * This annotation may be used to specify the session mode to be used when injecting a {@code jakarta.jms.JMSContext} 31 | * object. The meaning and possible values of session mode are the same as for the {@code ConnectionFactory} method 32 | * {@code createContext(int sessionMode)}. 33 | * 34 | * @version Jakarta Messaging 2.0 35 | * @since JMS 2.0 36 | * 37 | * @see jakarta.jms.JMSContext#createContext(int) 38 | */ 39 | @Retention(RUNTIME) 40 | @Target({ METHOD, FIELD, PARAMETER, TYPE }) 41 | public @interface JMSSessionMode { 42 | 43 | /** 44 | * Specifies the session mode used when injecting a {@code jakarta.jms.JMSContext} object. 45 | * 46 | * @return The session mode used when injecting a {@code jakarta.jms.JMSContext} object. 47 | */ 48 | int value() default AUTO_ACKNOWLEDGE; 49 | } 50 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageEOFException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when an unexpected end of stream has been reached when a {@code StreamMessage} or 22 | * {@code BytesMessage} is being read. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 1.0 26 | * 27 | **/ 28 | public class MessageEOFException extends JMSException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 32 | */ 33 | private static final long serialVersionUID = -4829621000056590895L; 34 | 35 | /** 36 | * Constructs a {@code MessageEOFException} with the specified reason, error code 37 | * and linked exception. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * @param linkedException a linked exception 42 | * 43 | **/ 44 | public MessageEOFException(String reason, String errorCode, Exception linkedException) { 45 | super(reason, errorCode, linkedException); 46 | } 47 | 48 | /** 49 | * Constructs a {@code MessageEOFException} with the specified reason and error code. 50 | * 51 | * @param reason a description of the exception 52 | * @param errorCode a string specifying the vendor-specific error code 53 | * 54 | **/ 55 | public MessageEOFException(String reason, String errorCode) { 56 | super(reason, errorCode); 57 | } 58 | 59 | /** 60 | * Constructs a {@code MessageEOFException} with the specified reason. The error code defaults to null. 61 | * 62 | * @param reason a description of the exception 63 | **/ 64 | public MessageEOFException(String reason) { 65 | super(reason); 66 | } 67 | 68 | } 69 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageFormatException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when a Jakarta Messaging client attempts to use a data type not supported by a message or attempts to 22 | * read data in a message as the wrong type. 23 | * 24 | *
25 | * It must also be thrown when equivalent type errors are made with message 26 | * property values. For example, this exception must be thrown if {@code StreamMessage.writeObject} is given an 27 | * unsupported class or if {@code StreamMessage.readShort} is used to read a {@code boolean} value. Note that the 28 | * special case of a failure caused by an attempt to read improperly formatted {@code String} data as numeric values 29 | * must throw the {@code java.lang.NumberFormatException}. 30 | * 31 | * @version Jakarta Messaging 2.0 32 | * @since JMS 1.0 33 | * 34 | **/ 35 | public class MessageFormatException extends JMSException { 36 | 37 | /** 38 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 39 | */ 40 | private static final long serialVersionUID = -3642297253594750138L; 41 | 42 | /** 43 | * Constructs a {@code MessageFormatException} with the specified reason, error code 44 | * and linked exception. 45 | * 46 | * @param reason a description of the exception 47 | * @param errorCode a string specifying the vendor-specific error code 48 | * @param linkedException a linked exception 49 | * 50 | **/ 51 | public MessageFormatException(String reason, String errorCode, Exception linkedException) { 52 | super(reason, errorCode, linkedException); 53 | } 54 | 55 | /** 56 | * Constructs a {@code MessageFormatException} with the specified reason and error code. 57 | * 58 | * @param reason a description of the exception 59 | * @param errorCode a string specifying the vendor-specific error code 60 | * 61 | **/ 62 | public MessageFormatException(String reason, String errorCode) { 63 | super(reason, errorCode); 64 | } 65 | 66 | /** 67 | * Constructs a {@code MessageFormatException} with the specified reason. The error code defaults to null. 68 | * 69 | * @param reason a description of the exception 70 | **/ 71 | public MessageFormatException(String reason) { 72 | super(reason); 73 | } 74 | 75 | } 76 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageFormatRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a Jakarta Messaging application attempts to use a data type not supported by a message 21 | * or attempts to read data in a message as the wrong type, and the method signature does not permit a 22 | * {@code MessageFormatException} to be thrown. 23 | * 24 | *
25 | * It must also be thrown when equivalent type errors are made with message 26 | * property values. Note that the special case of a failure caused by an attempt to read improperly formatted 27 | * {@code String} data as numeric values must throw the {@code java.lang.NumberFormatException}. 28 | * 29 | * @version Jakarta Messaging 2.0 30 | * @since JMS 2.0 31 | * 32 | **/ 33 | public class MessageFormatRuntimeException extends JMSRuntimeException { 34 | 35 | /** 36 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 37 | */ 38 | private static final long serialVersionUID = 416918643772467720L; 39 | 40 | /** 41 | * Constructs a {@code MessageFormatRuntimeException} with the specified detail message 42 | * 43 | * @param detailMessage a description of the exception 44 | **/ 45 | public MessageFormatRuntimeException(String detailMessage) { 46 | super(detailMessage); 47 | } 48 | 49 | /** 50 | * Constructs a {@code MessageFormatRuntimeException} with the specified detail message and error code. 51 | * 52 | * @param detailMessage a description of the exception 53 | * @param errorCode a provider-specific error code 54 | **/ 55 | public MessageFormatRuntimeException(String detailMessage, String errorCode) { 56 | super(detailMessage, errorCode); 57 | } 58 | 59 | /** 60 | * Constructs a {@code MessageFormatRuntimeException} with the specified detail message, error code and cause 61 | * 62 | * @param detailMessage a description of the exception 63 | * @param errorCode a provider-specific error code 64 | * @param cause the underlying cause of this exception 65 | */ 66 | public MessageFormatRuntimeException(String detailMessage, String errorCode, Throwable cause) { 67 | super(detailMessage, errorCode, cause); 68 | } 69 | } 70 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageListener.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code MessageListener} object is used to receive asynchronously delivered messages. 21 | * 22 | *
23 | * Each session must ensure that it passes messages serially to the listener. This means that a listener assigned to one 24 | * or more consumers of the same session can assume that the {@code onMessage} method is not called with the next 25 | * message until the session has completed the last call. 26 | * 27 | * @version Jakarta Messaging 2.0 28 | * @since JMS 1.0 29 | * 30 | */ 31 | public interface MessageListener { 32 | 33 | /** 34 | * Passes a message to the listener. 35 | * 36 | * @param message the message passed to the listener 37 | */ 38 | void onMessage(Message message); 39 | } 40 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageNotReadableException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when a Jakarta Messaging client attempts to read a write-only message. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 1.0 25 | * 26 | **/ 27 | public class MessageNotReadableException extends JMSException { 28 | 29 | /** 30 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 31 | */ 32 | private static final long serialVersionUID = 8044835867550650748L; 33 | 34 | /** 35 | * Constructs a {@code MessageNotReadableException} with the specified reason, error code 36 | * and linked exception. 37 | * 38 | * @param reason a description of the exception 39 | * @param errorCode a string specifying the vendor-specific error code 40 | * @param linkedException a linked exception 41 | * 42 | **/ 43 | public MessageNotReadableException(String reason, String errorCode, Exception linkedException) { 44 | super(reason, errorCode, linkedException); 45 | } 46 | 47 | /** 48 | * Constructs a {@code MessageNotReadableException} with the specified reason and error code. 49 | * 50 | * @param reason a description of the exception 51 | * @param errorCode a string specifying the vendor-specific error code 52 | * 53 | **/ 54 | public MessageNotReadableException(String reason, String errorCode) { 55 | super(reason, errorCode); 56 | } 57 | 58 | /** 59 | * Constructs a {@code MessageNotReadableException} with the specified reason. The error code defaults to null. 60 | * 61 | * @param reason a description of the exception 62 | **/ 63 | public MessageNotReadableException(String reason) { 64 | super(reason); 65 | } 66 | 67 | } 68 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageNotWriteableException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when a Jakarta Messaging client attempts to write to a read-only message. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 1.0 25 | **/ 26 | public class MessageNotWriteableException extends JMSException { 27 | 28 | /** 29 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 30 | */ 31 | private static final long serialVersionUID = -4241931174711518830L; 32 | 33 | /** 34 | * Constructs a {@code MessageNotWriteableException} with the specified reason, error code 35 | * and linked exception. 36 | * 37 | * @param reason a description of the exception 38 | * @param errorCode a string specifying the vendor-specific error code 39 | * @param linkedException a linked exception 40 | * 41 | **/ 42 | public MessageNotWriteableException(String reason, String errorCode, Exception linkedException) { 43 | super(reason, errorCode, linkedException); 44 | } 45 | 46 | /** 47 | * Constructs a {@code MessageNotWriteableException} with the specified reason and error code. 48 | * 49 | * @param reason a description of the exception 50 | * @param errorCode a string specifying the vendor-specific error code 51 | * 52 | **/ 53 | public MessageNotWriteableException(String reason, String errorCode) { 54 | super(reason, errorCode); 55 | } 56 | 57 | /** 58 | * Constructs a {@code MessageNotWriteableException} with the specified reason. The error code defaults to null. 59 | * 60 | * @param reason a description of the exception 61 | **/ 62 | public MessageNotWriteableException(String reason) { 63 | super(reason); 64 | } 65 | 66 | } 67 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/MessageNotWriteableRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a Jakarta Messaging client attempts to write to a read-only message. 21 | * 22 | * @version Jakarta Messaging 2.0 23 | * @since JMS 2.0 24 | **/ 25 | public class MessageNotWriteableRuntimeException extends JMSRuntimeException { 26 | 27 | /** 28 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 29 | */ 30 | private static final long serialVersionUID = 6075922984499850209L; 31 | 32 | /** 33 | * Constructs a {@code MessageNotWriteableRuntimeException} with the specified reason and error code. 34 | * 35 | * @param reason a description of the exception 36 | * @param errorCode a string specifying the vendor-specific error code 37 | * 38 | **/ 39 | public MessageNotWriteableRuntimeException(String reason, String errorCode) { 40 | super(reason, errorCode); 41 | } 42 | 43 | /** 44 | * Constructs a {@code MessageNotWriteableRuntimeException} with the specified reason. The error code defaults to null. 45 | * 46 | * @param reason a description of the exception 47 | **/ 48 | public MessageNotWriteableRuntimeException(String reason) { 49 | super(reason); 50 | } 51 | 52 | /** 53 | * Constructs a {@code MessageNotWriteableRuntimeException} with the specified detail message, error code and cause 54 | * 55 | * @param detailMessage a description of the exception 56 | * @param errorCode a provider-specific error code 57 | * @param cause the underlying cause of this exception 58 | */ 59 | public MessageNotWriteableRuntimeException(String detailMessage, String errorCode, Throwable cause) { 60 | super(detailMessage, errorCode, cause); 61 | } 62 | 63 | } 64 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ObjectMessage.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import java.io.Serializable; 20 | 21 | /** 22 | * An {@code ObjectMessage} object is used to send a message that contains a serializable object in the Java programming 23 | * language ("Java object"). It inherits from the {@code Message} interface and adds a body containing a single 24 | * reference to an object. Only {@code Serializable} Java objects can be used. 25 | * 26 | *
27 | * If a collection of Java objects must be sent, one of the {@code Collection} classes provided since JDK 1.2 can be 28 | * used. 29 | * 30 | *
31 | * When a client receives an {@code ObjectMessage}, it is in read-only mode. If a client attempts to write to the 32 | * message at this point, a {@code MessageNotWriteableException} is thrown. If {@code clearBody} is called, the message 33 | * can now be both read from and written to. 34 | * 35 | * @see jakarta.jms.Session#createObjectMessage() 36 | * @see jakarta.jms.Session#createObjectMessage(Serializable) 37 | * @see jakarta.jms.BytesMessage 38 | * @see jakarta.jms.MapMessage 39 | * @see jakarta.jms.Message 40 | * @see jakarta.jms.StreamMessage 41 | * @see jakarta.jms.TextMessage 42 | * 43 | * @version Jakarta Messaging 2.0 44 | * @since JMS 1.0 45 | */ 46 | public interface ObjectMessage extends Message { 47 | 48 | /** 49 | * Sets the serializable object containing this message's data. It is important to note that an {@code ObjectMessage} 50 | * contains a snapshot of the object at the time {@code setObject()} is called; subsequent modifications of the object 51 | * will have no effect on the {@code ObjectMessage} body. 52 | * 53 | * @param object the message's data 54 | * 55 | * @exception JMSException if the Jakarta Messaging provider fails to set the object due to some internal error. 56 | * @exception MessageFormatException if object serialization fails. 57 | * @exception MessageNotWriteableException if the message is in read-only mode. 58 | */ 59 | void setObject(Serializable object) throws JMSException; 60 | 61 | /** 62 | * Gets the serializable object containing this message's data. The default value is null. 63 | * 64 | * @return the serializable object containing this message's data 65 | * 66 | * @exception JMSException if the Jakarta Messaging provider fails to get the object due to some internal error. 67 | * @exception MessageFormatException if object deserialization fails. 68 | */ 69 | Serializable getObject() throws JMSException; 70 | } 71 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/Queue.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code Queue} object encapsulates a provider-specific queue name. 21 | * 22 | *
23 | * It is the way a client specifies the identity of a queue to Jakarta Messaging API methods. For those methods that use a 24 | * {@code Destination} as a parameter, a {@code Queue} object used as an argument. For example, a queue can be used to 25 | * create a {@code MessageConsumer} and a {@code MessageProducer} by calling: 26 | * 27 | *
33 | * The actual length of time messages are held by a queue and the consequences of resource overflow are not defined by 34 | * the Jakarta Messaging API. 35 | * 36 | * @see Session#createConsumer(Destination) 37 | * @see Session#createProducer(Destination) 38 | * @see Session#createQueue(String) 39 | * @see QueueSession#createQueue(String) 40 | * 41 | * @version Jakarta Messaging 2.0 42 | * @since JMS 1.0 43 | */ 44 | public interface Queue extends Destination { 45 | 46 | /** 47 | * Gets the name of this queue. 48 | * 49 | *
50 | * Clients that depend upon the name are not portable. 51 | * 52 | * @return the queue name 53 | * 54 | * @exception JMSException if the Jakarta Messaging provider implementation of {@code Queue} fails to return the queue name due to 55 | * some internal error. 56 | */ 57 | String getQueueName() throws JMSException; 58 | 59 | /** 60 | * Returns a string representation of this object. 61 | * 62 | * @return the provider-specific identity values for this queue 63 | */ 64 | @Override 65 | String toString(); 66 | } 67 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/QueueBrowser.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import java.util.Enumeration; 20 | 21 | /** 22 | * A client uses a {@code QueueBrowser} object to look at messages on a queue without removing them. 23 | * 24 | *
25 | * The {@code getEnumeration} method returns a {@code java.util.Enumeration} that is used to scan the queue's messages. 26 | * It may be an enumeration of the entire content of a queue, or it may contain only the messages matching a message 27 | * selector. 28 | * 29 | *
30 | * Messages may be arriving and expiring while the scan is done. The Jakarta Messaging API does not require the content of an 31 | * enumeration to be a static snapshot of queue content. Whether these changes are visible or not depends on the JMS 32 | * provider. 33 | *
34 | * A message must not be returned by a {@code QueueBrowser} before its delivery time has been reached. 35 | * 36 | *
37 | * A {@code QueueBrowser} can be created from either a {@code Session} or a {@code QueueSession}. 38 | * 39 | * @see jakarta.jms.Session#createBrowser 40 | * @see jakarta.jms.QueueSession#createBrowser 41 | * @see jakarta.jms.QueueReceiver 42 | * 43 | * @version Jakarta Messaging 2.0 44 | * @since JMS 1.0 45 | */ 46 | public interface QueueBrowser extends AutoCloseable { 47 | 48 | /** 49 | * Gets the queue associated with this queue browser. 50 | * 51 | * @return the queue 52 | * 53 | * @exception JMSException if the Jakarta Messaging provider fails to get the queue associated with this browser due to some internal 54 | * error. 55 | */ 56 | Queue getQueue() throws JMSException; 57 | 58 | /** 59 | * Gets this queue browser's message selector expression. 60 | * 61 | * @return this queue browser's message selector, or null if no message selector exists for the message consumer (that 62 | * is, if the message selector was not set or was set to null or the empty string) 63 | * 64 | * @exception JMSException if the Jakarta Messaging provider fails to get the message selector for this browser due to some internal 65 | * error. 66 | */ 67 | String getMessageSelector() throws JMSException; 68 | 69 | /** 70 | * Gets an enumeration for browsing the current queue messages in the order they would be received. 71 | * 72 | * @return an enumeration for browsing the messages 73 | * 74 | * @exception JMSException if the Jakarta Messaging provider fails to get the enumeration for this browser due to some internal error. 75 | */ 76 | Enumeration getEnumeration() throws JMSException; 77 | 78 | /** 79 | * Closes the {@code QueueBrowser}. 80 | * 81 | *
82 | * Since a provider may allocate some resources on behalf of a QueueBrowser outside the Java virtual machine, clients 83 | * should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may 84 | * not be timely enough. 85 | * 86 | * @exception JMSException if the Jakarta Messaging provider fails to close this browser due to some internal error. 87 | */ 88 | @Override 89 | void close() throws JMSException; 90 | } 91 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/QueueConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A client uses a {@code QueueConnectionFactory} object to create {@code QueueConnection} objects with a point-to-point 21 | * Jakarta Messaging provider. 22 | * 23 | *
24 | * {@code QueueConnectionFactory} can be used to create a {@code QueueConnection}, from which specialized queue-related 25 | * objects can be created. A more general, and recommended, approach is to use the {@code ConnectionFactory} object. 26 | * 27 | *
28 | * The {@code QueueConnectionFactory} object can be used to support existing code that already uses it. 29 | * 30 | * @see jakarta.jms.ConnectionFactory 31 | * 32 | * @version Jakarta Messaging 2.0 33 | * @since JMS 1.0 34 | * 35 | */ 36 | public interface QueueConnectionFactory extends ConnectionFactory { 37 | 38 | /** 39 | * Creates a queue connection with the default user identity. The connection is created in stopped mode. No messages 40 | * will be delivered until the {@code Connection.start} method is explicitly called. 41 | * 42 | * @return a newly created queue connection 43 | * 44 | * @exception JMSException if the Jakarta Messaging provider fails to create the queue connection due to some internal error. 45 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 46 | */ 47 | QueueConnection createQueueConnection() throws JMSException; 48 | 49 | /** 50 | * Creates a queue connection with the specified user identity. The connection is created in stopped mode. No messages 51 | * will be delivered until the {@code Connection.start} method is explicitly called. 52 | * 53 | * @param userName the caller's user name 54 | * @param password the caller's password 55 | * 56 | * @return a newly created queue connection 57 | * 58 | * @exception JMSException if the Jakarta Messaging provider fails to create the queue connection due to some internal error. 59 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 60 | */ 61 | QueueConnection createQueueConnection(String userName, String password) throws JMSException; 62 | } 63 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/QueueReceiver.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A client uses a {@code QueueReceiver} object to receive messages that have been delivered to a queue. 21 | * 22 | *
23 | * Although it is possible to have multiple {@code QueueReceiver}s for the same queue, the Jakarta Messaging API does not define how 24 | * messages are distributed between the {@code QueueReceiver}s. 25 | * 26 | *
27 | * If a {@code QueueReceiver} specifies a message selector, the messages that are not selected remain on the queue. By 28 | * definition, a message selector allows a {@code QueueReceiver} to skip messages. This means that when the skipped 29 | * messages are eventually read, the total ordering of the reads does not retain the partial order defined by each 30 | * message producer. Only {@code QueueReceiver}s without a message selector will read messages in message producer 31 | * order. 32 | * 33 | *
34 | * Creating a {@code MessageConsumer} provides the same features as creating a {@code QueueReceiver}. A 35 | * {@code MessageConsumer} object is recommended for creating new code. The {@code QueueReceiver} is provided to support 36 | * existing code. 37 | * 38 | * @see jakarta.jms.Session#createConsumer(Destination, String) 39 | * @see jakarta.jms.Session#createConsumer(Destination) 40 | * @see jakarta.jms.QueueSession#createReceiver(Queue, String) 41 | * @see jakarta.jms.QueueSession#createReceiver(Queue) 42 | * @see jakarta.jms.MessageConsumer 43 | * 44 | * @version Jakarta Messaging 2.0 45 | * @since JMS 1.0 46 | */ 47 | public interface QueueReceiver extends MessageConsumer { 48 | 49 | /** 50 | * Gets the {@code Queue} associated with this queue receiver. 51 | * 52 | * @return this receiver's {@code Queue} 53 | * 54 | * @exception JMSException if the Jakarta Messaging provider fails to get the queue for this queue receiver due to some internal 55 | * error. 56 | */ 57 | Queue getQueue() throws JMSException; 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/QueueRequestor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * The {@code QueueRequestor} helper class simplifies making service requests. 22 | * 23 | *
24 | * The {@code QueueRequestor} constructor is given a non-transacted {@code QueueSession} and a destination 25 | * {@code Queue}. It creates a {@code TemporaryQueue} for the responses and provides a {@code request} method that sends 26 | * the request message and waits for its reply. 27 | * 28 | *
29 | * This is a very basic request/reply abstraction which assumes the session is non-transacted with a delivery mode of 30 | * either AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE. It is expected that most applications will create less basic 31 | * implementations. 32 | * 33 | * @see jakarta.jms.TopicRequestor 34 | * 35 | * @version Jakarta Messaging 2.0 36 | * @since JMS 1.0 37 | */ 38 | public class QueueRequestor { 39 | 40 | QueueSession session; // The queue session the queue belongs to. 41 | TemporaryQueue tempQueue; 42 | QueueSender sender; 43 | QueueReceiver receiver; 44 | 45 | /** 46 | * Constructor for the {@code QueueRequestor} class. 47 | * 48 | *
49 | * This implementation assumes the session parameter to be non-transacted, with a delivery mode of either 50 | * {@code AUTO_ACKNOWLEDGE} or {@code DUPS_OK_ACKNOWLEDGE}. 51 | * 52 | * @param session the {@code QueueSession} the queue belongs to 53 | * @param queue the queue to perform the request/reply call on 54 | * 55 | * @exception JMSException if the Jakarta Messaging provider fails to create the {@code QueueRequestor} due to some internal error. 56 | * @exception InvalidDestinationException if an invalid queue is specified. 57 | */ 58 | public QueueRequestor(QueueSession session, Queue queue) throws JMSException { 59 | if (queue == null) { 60 | throw new InvalidDestinationException("queue==null"); 61 | } 62 | 63 | this.session = session; 64 | tempQueue = session.createTemporaryQueue(); 65 | sender = session.createSender(queue); 66 | receiver = session.createReceiver(tempQueue); 67 | } 68 | 69 | /** 70 | * Sends a request and waits for a reply. The temporary queue is used for the {@code JMSReplyTo} destination, and only 71 | * one reply per request is expected. 72 | * 73 | * @param message the message to send 74 | * 75 | * @return the reply message 76 | * 77 | * @exception JMSException if the Jakarta Messaging provider fails to complete the request due to some internal error. 78 | */ 79 | public Message request(Message message) throws JMSException { 80 | message.setJMSReplyTo(tempQueue); 81 | sender.send(message); 82 | return receiver.receive(); 83 | } 84 | 85 | /** 86 | * Closes the {@code QueueRequestor} and its session. 87 | * 88 | *
89 | * Since a provider may allocate some resources on behalf of a {@code QueueRequestor} outside the Java virtual machine, 90 | * clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these 91 | * resources may not be timely enough. 92 | * 93 | *
94 | * Note that this method closes the {@code QueueSession} object passed to the {@code QueueRequestor} constructor. 95 | * 96 | * @exception JMSException if the Jakarta Messaging provider fails to close the {@code QueueRequestor} due to some internal error. 97 | */ 98 | public void close() throws JMSException { 99 | 100 | // publisher and consumer created by constructor are implicitly closed. 101 | session.close(); 102 | tempQueue.delete(); 103 | } 104 | } 105 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/QueueSession.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code QueueSession} object provides methods for creating {@code QueueReceiver}, {@code QueueSender}, 21 | * {@code QueueBrowser}, and {@code TemporaryQueue} objects. 22 | * 23 | *
24 | * If there are messages that have been received but not acknowledged when a {@code QueueSession} terminates, these 25 | * messages will be retained and redelivered when a consumer next accesses the queue. 26 | * 27 | *
28 | * A {@code QueueSession} is used for creating Point-to-Point specific objects. In general, use the {@code Session} 29 | * object. The {@code QueueSession} is used to support existing code. Using the {@code Session} object simplifies the 30 | * programming model, and allows transactions to be used across the two messaging domains. 31 | * 32 | *
33 | * A {@code QueueSession} cannot be used to create objects specific to the publish/subscribe domain. The following 34 | * methods inherit from {@code Session}, but must throw an {@code IllegalStateException} if they are used from 35 | * {@code QueueSession}: 36 | * 37 | *
60 | * This facility is provided for the rare cases where clients need to dynamically manipulate queue identity. It allows 61 | * the creation of a queue identity with a provider-specific name. Clients that depend on this ability are not portable. 62 | * 63 | *
64 | * Note that this method is not for creating the physical queue. The physical creation of queues is an administrative 65 | * task and is not to be initiated by the Jakarta Messaging API. The one exception is the creation of temporary queues, which is 66 | * accomplished with the {@code createTemporaryQueue} method. 67 | * 68 | * @param queueName the name of this {@code Queue} 69 | * 70 | * @return a {@code Queue} with the given name 71 | * 72 | * @exception JMSException if the session fails to create a queue due to some internal error. 73 | */ 74 | @Override 75 | Queue createQueue(String queueName) throws JMSException; 76 | 77 | /** 78 | * Creates a {@code QueueReceiver} object to receive messages from the specified queue. 79 | * 80 | * @param queue the {@code Queue} to access 81 | * 82 | * @return A {@code QueueReceiver} object to receive messages from the specified queue 83 | * 84 | * @exception JMSException if the session fails to create a receiver due to some internal error. 85 | * @exception InvalidDestinationException if an invalid queue is specified. 86 | */ 87 | QueueReceiver createReceiver(Queue queue) throws JMSException; 88 | 89 | /** 90 | * Creates a {@code QueueReceiver} object to receive messages from the specified queue using a message selector. 91 | * 92 | * @param queue the {@code Queue} to access 93 | * @param messageSelector only messages with properties matching the message selector expression are delivered. A value 94 | * of null or an empty string indicates that there is no message selector for the message consumer. 95 | * 96 | * @return A {@code QueueReceiver} object to receive messages from the specified queue 97 | * 98 | * @exception JMSException if the session fails to create a receiver due to some internal error. 99 | * @exception InvalidDestinationException if an invalid queue is specified. 100 | * @exception InvalidSelectorException if the message selector is invalid. 101 | * 102 | */ 103 | QueueReceiver createReceiver(Queue queue, String messageSelector) throws JMSException; 104 | 105 | /** 106 | * Creates a {@code QueueSender} object to send messages to the specified queue. 107 | * 108 | * @param queue the {@code Queue} to access, or null if this is an unidentified producer 109 | * 110 | * @return A {@code QueueSender} object to send messages to the specified queue. 111 | * 112 | * @exception JMSException if the session fails to create a sender due to some internal error. 113 | * @exception InvalidDestinationException if an invalid queue is specified. 114 | */ 115 | QueueSender createSender(Queue queue) throws JMSException; 116 | 117 | /** 118 | * Creates a {@code QueueBrowser} object to peek at the messages on the specified queue. 119 | * 120 | * @param queue the {@code Queue} to access 121 | * 122 | * @return A {@code QueueBrowser} object to peek at the messages. 123 | * 124 | * @exception JMSException if the session fails to create a browser due to some internal error. 125 | * @exception InvalidDestinationException if an invalid queue is specified. 126 | */ 127 | @Override 128 | QueueBrowser createBrowser(Queue queue) throws JMSException; 129 | 130 | /** 131 | * Creates a {@code QueueBrowser} object to peek at the messages on the specified queue using a message selector. 132 | * 133 | * @param queue the {@code Queue} to access 134 | * @param messageSelector only messages with properties matching the message selector expression are delivered. A value 135 | * of null or an empty string indicates that there is no message selector for the message consumer. 136 | * 137 | * @return A {@code QueueBrowser} object to peek at the messages on the specified queue. 138 | * 139 | * @exception JMSException if the session fails to create a browser due to some internal error. 140 | * @exception InvalidDestinationException if an invalid queue is specified. 141 | * @exception InvalidSelectorException if the message selector is invalid. 142 | */ 143 | @Override 144 | QueueBrowser createBrowser(Queue queue, String messageSelector) throws JMSException; 145 | 146 | /** 147 | * Creates a {@code TemporaryQueue} object. Its lifetime will be that of the {@code QueueConnection} unless it is 148 | * deleted earlier. 149 | * 150 | * @return a temporary queue identity 151 | * 152 | * @exception JMSException if the session fails to create a temporary queue due to some internal error. 153 | */ 154 | @Override 155 | TemporaryQueue createTemporaryQueue() throws JMSException; 156 | } 157 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ResourceAllocationException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception is thrown when a provider is unable to allocate the resources required by a method. 22 | * 23 | *
24 | * For example, this exception should be thrown when a call to {@code TopicConnectionFactory.createTopicConnection} 25 | * fails due to a lack of Jakarta Messaging provider resources. 26 | * 27 | * @version Jakarta Messaging 2.0 28 | * @since JMS 1.0 29 | **/ 30 | public class ResourceAllocationException extends JMSException { 31 | 32 | /** 33 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 34 | */ 35 | private static final long serialVersionUID = -1172695755360706776L; 36 | 37 | /** 38 | * Constructs a {@code ResourceAllocationException} with the specified reason, error code 39 | * and linked exception. 40 | * 41 | * @param reason a description of the exception 42 | * @param errorCode a string specifying the vendor-specific error code 43 | * @param linkedException a linked exception 44 | * 45 | **/ 46 | public ResourceAllocationException(String reason, String errorCode, Exception linkedException) { 47 | super(reason, errorCode, linkedException); 48 | } 49 | 50 | /** 51 | * Constructs a {@code ResourceAllocationException} with the specified reason and error code. 52 | * 53 | * @param reason a description of the exception 54 | * @param errorCode a string specifying the vendor-specific error code 55 | * 56 | **/ 57 | public ResourceAllocationException(String reason, String errorCode) { 58 | super(reason, errorCode); 59 | } 60 | 61 | /** 62 | * Constructs a {@code ResourceAllocationException} with the specified reason. The error code defaults to null. 63 | * 64 | * @param reason a description of the exception 65 | **/ 66 | public ResourceAllocationException(String reason) { 67 | super(reason); 68 | } 69 | 70 | } 71 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ResourceAllocationRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception is thrown when a provider is unable to allocate the resources required by a method. 21 | * 22 | *
23 | * For example, this exception should be thrown when a call to {@code ConnectionFactory.createContext} fails due to a 24 | * lack of Jakarta Messaging provider resources. 25 | * 26 | * @version Jakarta Messaging 2.0 27 | * @since JMS 2.0 28 | **/ 29 | public class ResourceAllocationRuntimeException extends JMSRuntimeException { 30 | 31 | /** 32 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 33 | */ 34 | private static final long serialVersionUID = -1306897975610715374L; 35 | 36 | /** 37 | * Constructs a {@code ResourceAllocationRuntimeException} with the specified reason and error code. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * 42 | **/ 43 | public ResourceAllocationRuntimeException(String reason, String errorCode) { 44 | super(reason, errorCode); 45 | } 46 | 47 | /** 48 | * Constructs a {@code ResourceAllocationRuntimeException} with the specified reason. The error code defaults to null. 49 | * 50 | * @param reason a description of the exception 51 | **/ 52 | public ResourceAllocationRuntimeException(String reason) { 53 | super(reason); 54 | } 55 | 56 | /** 57 | * Constructs a {@code ResourceAllocationRuntimeException} with the specified detail message, error code and cause 58 | * 59 | * @param detailMessage a description of the exception 60 | * @param errorCode a provider-specific error code 61 | * @param cause the underlying cause of this exception 62 | */ 63 | public ResourceAllocationRuntimeException(String detailMessage, String errorCode, Throwable cause) { 64 | super(detailMessage, errorCode, cause); 65 | } 66 | 67 | } 68 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ServerSession.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code ServerSession} object is an application server object that is used by a server to associate a thread with a 21 | * Jakarta Messaging session (optional). 22 | * 23 | *
24 | * A {@code ServerSession} implements two methods: 25 | * 26 | *
33 | * A {@code ConnectionConsumer} implemented by a Jakarta Messaging provider uses a {@code ServerSession} to process one or more 34 | * messages that have arrived. It does this by getting a {@code ServerSession} from the {@code ConnectionConsumer}'s 35 | * {@code ServerSessionPool}; getting the {@code ServerSession}'s Jakarta Messaging session; loading it with the messages; and then 36 | * starting the {@code ServerSession}. 37 | * 38 | *
39 | * In most cases the {@code ServerSession} will register some object it provides as the {@code ServerSession}'s thread 40 | * run object. The {@code ServerSession}'s {@code start} method will call the thread's {@code start} method, which will 41 | * start the new thread, and from it, call the {@code run} method of the {@code ServerSession}'s run object. This object 42 | * will do some housekeeping and then call the {@code Session}'s {@code run} method. When {@code run} returns, the 43 | * {@code ServerSession}'s run object can return the {@code ServerSession} to the {@code ServerSessionPool}, and the 44 | * cycle starts again. 45 | * 46 | *
47 | * Note that the Jakarta Messaging API does not architect how the {@code ConnectionConsumer} loads the {@code Session} with messages. 48 | * Since both the {@code ConnectionConsumer} and {@code Session} are implemented by the same Jakarta Messaging provider, they can 49 | * accomplish the load using a private mechanism. 50 | * 51 | * @see jakarta.jms.ServerSessionPool 52 | * @see jakarta.jms.ConnectionConsumer 53 | * 54 | * @version Jakarta Messaging 2.0 55 | * @since JMS 1.0 56 | */ 57 | public interface ServerSession { 58 | 59 | /** 60 | * Return the {@code ServerSession}'s {@code Session}. This must be a {@code Session} created by the same 61 | * {@code Connection} that will be dispatching messages to it. The provider will assign one or more messages to the 62 | * {@code Session} and then call {@code start} on the {@code ServerSession}. 63 | * 64 | * @return the server session's session 65 | * 66 | * @exception JMSException if the Jakarta Messaging provider fails to get the associated session for this {@code ServerSession} due to 67 | * some internal error. 68 | **/ 69 | Session getSession() throws JMSException; 70 | 71 | /** 72 | * Cause the {@code Session}'s {@code run} method to be called to process messages that were just assigned to it. 73 | * 74 | * @exception JMSException if the Jakarta Messaging provider fails to start the server session to process messages due to some 75 | * internal error. 76 | */ 77 | void start() throws JMSException; 78 | } 79 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/ServerSessionPool.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code ServerSessionPool} object is an object implemented by an application server to provide a pool of 21 | * {@code ServerSession} objects for processing the messages of a {@code ConnectionConsumer} (optional). 22 | * 23 | *
24 | * Its only method is {@code getServerSession}. The Jakarta Messaging API does not architect how the pool is implemented. It could be 25 | * a static pool of {@code ServerSession} objects, or it could use a sophisticated algorithm to dynamically create 26 | * {@code ServerSession} objects as needed. 27 | * 28 | *
29 | * If the {@code ServerSessionPool} is out of {@code ServerSession} objects, the {@code getServerSession} call may 30 | * block. If a {@code ConnectionConsumer} is blocked, it cannot deliver new messages until a {@code ServerSession} is 31 | * eventually returned. 32 | * 33 | * @see jakarta.jms.ServerSession 34 | * 35 | * @version Jakarta Messaging 2.0 36 | * @since JMS 1.0 37 | */ 38 | public interface ServerSessionPool { 39 | 40 | /** 41 | * Return a server session from the pool. 42 | * 43 | * @return a server session from the pool 44 | * 45 | * @exception JMSException if an application server fails to return a {@code ServerSession} out of its server session 46 | * pool. 47 | */ 48 | ServerSession getServerSession() throws JMSException; 49 | } 50 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TemporaryQueue.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code TemporaryQueue} object is a unique {@code Queue} object created for the duration of a {@code Connection}. It 21 | * is a system-defined queue that can be consumed only by the {@code Connection} that created it. 22 | * 23 | *
24 | * A {@code TemporaryQueue} object can be created at either the {@code Session} or {@code QueueSession} level. Creating 25 | * it at the {@code Session} level allows to the {@code TemporaryQueue} to participate in transactions with objects from 26 | * the Pub/Sub domain. If it is created at the {@code QueueSession}, it will only be able participate in transactions 27 | * with objects from the PTP domain. 28 | * 29 | * @see Session#createTemporaryQueue() 30 | * @see QueueSession#createTemporaryQueue() 31 | * 32 | * @version Jakarta Messaging 2.0 33 | * @since JMS 1.0 34 | */ 35 | public interface TemporaryQueue extends Queue { 36 | 37 | /** 38 | * Deletes this temporary queue. If there are existing receivers still using it, a {@code JMSException} will be thrown. 39 | * 40 | * @exception JMSException if the Jakarta Messaging provider fails to delete the temporary queue due to some internal error. 41 | */ 42 | void delete() throws JMSException; 43 | } 44 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TemporaryTopic.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code TemporaryTopic} object is a unique {@code Topic} object created for the duration of a {@code Connection}. It 21 | * is a system-defined topic that can be consumed only by the {@code Connection} that created it. 22 | * 23 | *
24 | * A {@code TemporaryTopic} object can be created either at the {@code Session} or {@code TopicSession} level. Creating 25 | * it at the {@code Session} level allows the {@code TemporaryTopic} to participate in the same transaction with objects 26 | * from the PTP domain. If a {@code TemporaryTopic} is created at the {@code TopicSession}, it will only be able 27 | * participate in transactions with objects from the Pub/Sub domain. 28 | * 29 | * @see Session#createTemporaryTopic() 30 | * @see TopicSession#createTemporaryTopic() 31 | * 32 | * @version Jakarta Messaging 2.0 33 | * @since JMS 1.0 34 | */ 35 | public interface TemporaryTopic extends Topic { 36 | 37 | /** 38 | * Deletes this temporary topic. If there are existing subscribers still using it, a {@code JMSException} will be 39 | * thrown. 40 | * 41 | * @exception JMSException if the Jakarta Messaging provider fails to delete the temporary topic due to some internal error. 42 | */ 43 | void delete() throws JMSException; 44 | } 45 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TextMessage.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code TextMessage} object is used to send a message containing a {@code java.lang.String}. It inherits from the 21 | * {@code Message} interface and adds a text message body. 22 | * 23 | *
24 | * This message type can be used to transport text-based messages, including those with XML content. 25 | * 26 | *
27 | * When a client receives a {@code TextMessage}, it is in read-only mode. If a client attempts to write to the message 28 | * at this point, a {@code MessageNotWriteableException} is thrown. If {@code clearBody} is called, the message can now 29 | * be both read from and written to. 30 | * 31 | * @see jakarta.jms.Session#createTextMessage() 32 | * @see jakarta.jms.Session#createTextMessage(String) 33 | * @see jakarta.jms.BytesMessage 34 | * @see jakarta.jms.MapMessage 35 | * @see jakarta.jms.Message 36 | * @see jakarta.jms.ObjectMessage 37 | * @see jakarta.jms.StreamMessage 38 | * @see java.lang.String 39 | * 40 | * @version Jakarta Messaging 2.0 41 | * @since JMS 1.0 42 | */ 43 | public interface TextMessage extends Message { 44 | 45 | /** 46 | * Sets the string containing this message's data. 47 | * 48 | * @param string the {@code String} containing the message's data 49 | * 50 | * @exception JMSException if the Jakarta Messaging provider fails to set the text due to some internal error. 51 | * @exception MessageNotWriteableException if the message is in read-only mode. 52 | */ 53 | void setText(String string) throws JMSException; 54 | 55 | /** 56 | * Gets the string containing this message's data. The default value is null. 57 | * 58 | * @return the {@code String} containing the message's data 59 | * 60 | * @exception JMSException if the Jakarta Messaging provider fails to get the text due to some internal error. 61 | */ 62 | String getText() throws JMSException; 63 | } 64 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/Topic.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A {@code Topic} object encapsulates a provider-specific topic name. 21 | * 22 | *
23 | * It is the way a client specifies the identity of a topic to Jakarta Messaging API methods. For those methods that use a 24 | * {@code Destination} as a parameter, a {@code Topic} object may used as an argument . For example, a Topic can be used 25 | * to create a {@code MessageConsumer} and a {@code MessageProducer} by calling: 26 | * 27 | *
33 | * Many publish/subscribe (pub/sub) providers group topics into hierarchies and provide various options for subscribing 34 | * to parts of the hierarchy. The Jakarta Messaging API places no restriction on what a {@code Topic} object represents. It may be a 35 | * leaf in a topic hierarchy, or it may be a larger part of the hierarchy. 36 | * 37 | *
38 | * The organization of topics and the granularity of subscriptions to them is an important part of a pub/sub 39 | * application's architecture. The Jakarta Messaging API does not specify a policy for how this should be done. If an application 40 | * takes advantage of a provider-specific topic-grouping mechanism, it should document this. If the application is 41 | * installed using a different provider, it is the job of the administrator to construct an equivalent topic 42 | * architecture and create equivalent {@code Topic} objects. 43 | * 44 | * @see Session#createConsumer(Destination) 45 | * @see Session#createProducer(Destination) 46 | * @see jakarta.jms.TopicSession#createTopic(String) 47 | * 48 | * @version Jakarta Messaging 2.0 49 | * @since JMS 1.0 50 | */ 51 | public interface Topic extends Destination { 52 | 53 | /** 54 | * Gets the name of this topic. 55 | * 56 | *
57 | * Clients that depend upon the name are not portable. 58 | * 59 | * @return the topic name 60 | * 61 | * @exception JMSException if the Jakarta Messaging provider implementation of {@code Topic} fails to return the topic name due to 62 | * some internal error. 63 | */ 64 | String getTopicName() throws JMSException; 65 | 66 | /** 67 | * Returns a string representation of this object. 68 | * 69 | * @return the provider-specific identity values for this topic 70 | */ 71 | @Override 72 | String toString(); 73 | } 74 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TopicConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A client uses a {@code TopicConnectionFactory} object to create {@code TopicConnection} objects with a 21 | * publish/subscribe Jakarta Messaging provider. 22 | * 23 | *
24 | * A{@code TopicConnectionFactory} can be used to create a {@code TopicConnection}, from which specialized 25 | * topic-related objects can be created. A more general, and recommended approach is to use the 26 | * {@code ConnectionFactory} object. 27 | * 28 | *
29 | * The {@code TopicConnectionFactory} object should be used to support existing code. 30 | * 31 | * @see jakarta.jms.ConnectionFactory 32 | * 33 | * @version Jakarta Messaging 2.0 34 | * @since JMS 1.0 35 | */ 36 | public interface TopicConnectionFactory extends ConnectionFactory { 37 | 38 | /** 39 | * Creates a topic connection with the default user identity. The connection is created in stopped mode. No messages 40 | * will be delivered until the {@code Connection.start} method is explicitly called. 41 | * 42 | * @return a newly created topic connection 43 | * 44 | * @exception JMSException if the Jakarta Messaging provider fails to create a topic connection due to some internal error. 45 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 46 | */ 47 | TopicConnection createTopicConnection() throws JMSException; 48 | 49 | /** 50 | * Creates a topic connection with the specified user identity. The connection is created in stopped mode. No messages 51 | * will be delivered until the {@code Connection.start} method is explicitly called. 52 | * 53 | * @param userName the caller's user name 54 | * @param password the caller's password 55 | * 56 | * @return a newly created topic connection 57 | * 58 | * @exception JMSException if the Jakarta Messaging provider fails to create a topic connection due to some internal error. 59 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 60 | */ 61 | TopicConnection createTopicConnection(String userName, String password) throws JMSException; 62 | } 63 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TopicRequestor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * The {@code TopicRequestor} helper class simplifies making service requests. 22 | * 23 | *
24 | * The {@code TopicRequestor} constructor is given a non-transacted {@code TopicSession} and a destination 25 | * {@code Topic}. It creates a {@code TemporaryTopic} for the responses and provides a {@code request} method that sends 26 | * the request message and waits for its reply. 27 | * 28 | *
29 | * This is a very basic request/reply abstraction which assumes the session is non-transacted with a delivery mode of 30 | * either AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE. It is expected that most applications will create less basic 31 | * implementations. 32 | * 33 | * @see jakarta.jms.QueueRequestor 34 | * 35 | * @version Jakarta Messaging 2.0 36 | * @since JMS 1.0 37 | */ 38 | public class TopicRequestor { 39 | 40 | TopicSession session; // The topic session the topic belongs to. 41 | TemporaryTopic tempTopic; 42 | TopicPublisher publisher; 43 | TopicSubscriber subscriber; 44 | 45 | /** 46 | * Constructor for the {@code TopicRequestor} class. 47 | * 48 | *
49 | * This implementation assumes the session parameter to be non-transacted, with a delivery mode of either 50 | * {@code AUTO_ACKNOWLEDGE} or {@code DUPS_OK_ACKNOWLEDGE}. 51 | * 52 | * @param session the {@code TopicSession} the topic belongs to 53 | * @param topic the topic to perform the request/reply call on 54 | * 55 | * @exception JMSException if the Jakarta Messaging provider fails to create the {@code TopicRequestor} due to some internal error. 56 | * @exception InvalidDestinationException if an invalid topic is specified. 57 | */ 58 | 59 | public TopicRequestor(TopicSession session, Topic topic) throws JMSException { 60 | if (topic == null) { 61 | throw new InvalidDestinationException("topic==null"); 62 | } 63 | 64 | this.session = session; 65 | tempTopic = session.createTemporaryTopic(); 66 | publisher = session.createPublisher(topic); 67 | subscriber = session.createSubscriber(tempTopic); 68 | } 69 | 70 | /** 71 | * Sends a request and waits for a reply. The temporary topic is used for the {@code JMSReplyTo} destination; the first 72 | * reply is returned, and any following replies are discarded. 73 | * 74 | * @param message the message to send 75 | * 76 | * @return the reply message 77 | * 78 | * @exception JMSException if the Jakarta Messaging provider fails to complete the request due to some internal error. 79 | */ 80 | public Message request(Message message) throws JMSException { 81 | message.setJMSReplyTo(tempTopic); 82 | publisher.publish(message); 83 | return subscriber.receive(); 84 | } 85 | 86 | /** 87 | * Closes the {@code TopicRequestor} and its session. 88 | * 89 | *
90 | * Since a provider may allocate some resources on behalf of a {@code TopicRequestor} outside the Java virtual machine, 91 | * clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these 92 | * resources may not be timely enough. 93 | * 94 | *
95 | * Note that this method closes the {@code TopicSession} object passed to the {@code TopicRequestor} constructor. 96 | * 97 | * @exception JMSException if the Jakarta Messaging provider fails to close the {@code TopicRequestor} due to some internal error. 98 | */ 99 | public void close() throws JMSException { 100 | // publisher and consumer created by constructor are implicitly closed. 101 | session.close(); 102 | tempTopic.delete(); 103 | } 104 | } 105 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TopicSubscriber.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * A client uses a {@code TopicSubscriber} object to receive messages that have been published to a topic. A 21 | * {@code TopicSubscriber} object is the publish/subscribe form of a message consumer. A {@code MessageConsumer} can be 22 | * created by using {@code Session.createConsumer}. 23 | * 24 | *
25 | * A {@code TopicSession} allows the creation of multiple {@code TopicSubscriber} objects per topic. It will deliver 26 | * each message for a topic to each subscriber eligible to receive it. Each copy of the message is treated as a 27 | * completely separate message. Work done on one copy has no effect on the others; acknowledging one does not 28 | * acknowledge the others; one message may be delivered immediately, while another waits for its subscriber to process 29 | * messages ahead of it. 30 | * 31 | *
32 | * Regular {@code TopicSubscriber} objects are not durable. They receive only messages that are published while they are 33 | * active. 34 | * 35 | *
36 | * Messages filtered out by a subscriber's message selector will never be delivered to the subscriber. From the 37 | * subscriber's perspective, they do not exist. 38 | * 39 | *
40 | * In some cases, a connection may both publish and subscribe to a topic. The subscriber {@code NoLocal} attribute 41 | * allows a subscriber to inhibit the delivery of messages published by its own connection. 42 | * 43 | *
44 | * If a client needs to receive all the messages published on a topic, including the ones published while the subscriber 45 | * is inactive, it uses a durable {@code TopicSubscriber}. The Jakarta Messaging provider retains a record of this durable 46 | * subscription and insures that all messages from the topic's publishers are retained until they are acknowledged by 47 | * this durable subscriber or they have expired. 48 | * 49 | *
50 | * Sessions with durable subscribers must always provide the same client identifier. In addition, each client must 51 | * specify a name that uniquely identifies (within client identifier) each durable subscription it creates. Only one 52 | * session at a time can have a {@code TopicSubscriber} for a particular durable subscription. 53 | * 54 | *
55 | * A client can change an existing durable subscription by creating a durable {@code TopicSubscriber} with the same name 56 | * and a new topic and/or message selector. Changing a durable subscription is equivalent to unsubscribing (deleting) 57 | * the old one and creating a new one. 58 | * 59 | *
60 | * The {@code unsubscribe} method is used to delete a durable subscription. The {@code unsubscribe} method can be used 61 | * at the {@code Session} or {@code TopicSession} level. This method deletes the state being maintained on behalf of the 62 | * subscriber by its provider. 63 | * 64 | *
65 | * Creating a {@code MessageConsumer} provides the same features as creating a {@code TopicSubscriber}. To create a 66 | * durable subscriber, use of {@code Session.CreateDurableSubscriber} is recommended. The {@code TopicSubscriber} is 67 | * provided to support existing code. 68 | * 69 | * @see jakarta.jms.Session#createConsumer 70 | * @see jakarta.jms.Session#createDurableSubscriber 71 | * @see jakarta.jms.TopicSession 72 | * @see jakarta.jms.TopicSession#createSubscriber 73 | * @see jakarta.jms.MessageConsumer 74 | * 75 | * @version Jakarta Messaging 2.0 76 | * @since JMS 1.0 77 | */ 78 | public interface TopicSubscriber extends MessageConsumer { 79 | 80 | /** 81 | * Gets the {@code Topic} associated with this subscriber. 82 | * 83 | * @return this subscriber's {@code Topic} 84 | * 85 | * @exception JMSException if the Jakarta Messaging provider fails to get the topic for this topic subscriber due to some internal 86 | * error. 87 | */ 88 | Topic getTopic() throws JMSException; 89 | 90 | /** 91 | * Gets the {@code NoLocal} attribute for this subscriber. The default value for this attribute is false. 92 | * 93 | * @return true if locally published messages are being inhibited 94 | * 95 | * @exception JMSException if the Jakarta Messaging provider fails to get the {@code NoLocal} attribute for this topic subscriber due 96 | * to some internal error. 97 | */ 98 | boolean getNoLocal() throws JMSException; 99 | } 100 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TransactionInProgressException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception is thrown when an operation is invalid because a transaction is in progress. For instance, an attempt 22 | * to call {@code Session.commit} when a session is part of a distributed transaction should throw a 23 | * {@code TransactionInProgressException}. 24 | * 25 | * @version Jakarta Messaging 2.0 26 | * @since JMS 1.0 27 | */ 28 | public class TransactionInProgressException extends JMSException { 29 | 30 | /** 31 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 32 | */ 33 | private static final long serialVersionUID = -5611340150426335231L; 34 | 35 | /** 36 | * Constructs a {@code TransactionInProgressException} with the specified reason, error code 37 | * and linked exception. 38 | * 39 | * @param reason a description of the exception 40 | * @param errorCode a string specifying the vendor-specific error code 41 | * 42 | **/ 43 | public TransactionInProgressException(String reason, String errorCode, Exception linkedException) { 44 | super(reason, errorCode, linkedException); 45 | } 46 | 47 | /** 48 | * Constructs a {@code TransactionInProgressException} with the specified reason and error code. 49 | * 50 | * @param reason a description of the exception 51 | * @param errorCode a string specifying the vendor-specific error code 52 | * 53 | **/ 54 | public TransactionInProgressException(String reason, String errorCode) { 55 | super(reason, errorCode); 56 | } 57 | 58 | /** 59 | * Constructs a {@code TransactionInProgressException} with the specified reason. The error code defaults to null. 60 | * 61 | * @param reason a description of the exception 62 | **/ 63 | public TransactionInProgressException(String reason) { 64 | super(reason); 65 | } 66 | 67 | } 68 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TransactionInProgressRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception is thrown when an operation is invalid because a transaction is in progress. For instance, 21 | * an attempt to call {@code JMSContext.commit} when the context is part of a distributed transaction should throw a 22 | * {@code TransactionInProgressRuntimeException}. 23 | * 24 | * @version Jakarta Messaging 2.0 25 | * @since JMS 2.0 26 | */ 27 | public class TransactionInProgressRuntimeException extends JMSRuntimeException { 28 | 29 | /** 30 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 31 | */ 32 | private static final long serialVersionUID = -916492460069513065L; 33 | 34 | /** 35 | * Constructs a {@code TransactionInProgressRuntimeException} with the specified detail message 36 | * 37 | * @param detailMessage a description of the exception 38 | **/ 39 | public TransactionInProgressRuntimeException(String detailMessage) { 40 | super(detailMessage); 41 | } 42 | 43 | /** 44 | * Constructs a {@code TransactionInProgressRuntimeException} with the specified detail message and error code. 45 | * 46 | * @param detailMessage a description of the exception 47 | * @param errorCode a provider-specific error code 48 | **/ 49 | public TransactionInProgressRuntimeException(String detailMessage, String errorCode) { 50 | super(detailMessage, errorCode); 51 | } 52 | 53 | /** 54 | * Constructs a {@code TransactionInProgressRuntimeException} with the specified detail message, error code and cause 55 | * 56 | * @param detailMessage a description of the exception 57 | * @param errorCode a provider-specific error code 58 | * @param cause the underlying cause of this exception 59 | */ 60 | public TransactionInProgressRuntimeException(String detailMessage, String errorCode, Throwable cause) { 61 | super(detailMessage, errorCode, cause); 62 | } 63 | 64 | } 65 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TransactionRolledBackException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * Copyright (c) 2021 Contributors to the Eclipse Foundation 4 | * 5 | * This program and the accompanying materials are made available under the 6 | * terms of the Eclipse Public License v. 2.0, which is available at 7 | * http://www.eclipse.org/legal/epl-2.0. 8 | * 9 | * This Source Code may also be made available under the following Secondary 10 | * Licenses when the conditions for such availability set forth in the 11 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 12 | * version 2 with the GNU Classpath Exception, which is available at 13 | * https://www.gnu.org/software/classpath/license.html. 14 | * 15 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 16 | */ 17 | 18 | package jakarta.jms; 19 | 20 | /** 21 | * This exception must be thrown when a call to {@code Session.commit} results in a rollback of the current transaction. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 1.0 25 | */ 26 | public class TransactionRolledBackException extends JMSException { 27 | 28 | /** 29 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Java Message Service 1.1 version 30 | */ 31 | private static final long serialVersionUID = 9157976009672865857L; 32 | 33 | /** 34 | * Constructs a {@code TransactionRolledBackException} with the specified reason, error code 35 | * and linked exception. 36 | * 37 | * @param reason a description of the exception 38 | * @param errorCode a string specifying the vendor-specific error code 39 | * @param linkedException a linked exception 40 | * 41 | **/ 42 | public TransactionRolledBackException(String reason, String errorCode, Exception linkedException) { 43 | super(reason, errorCode, linkedException); 44 | } 45 | 46 | /** 47 | * Constructs a {@code TransactionRolledBackException} with the specified reason and error code. 48 | * 49 | * @param reason a description of the exception 50 | * @param errorCode a string specifying the vendor-specific error code 51 | * 52 | **/ 53 | public TransactionRolledBackException(String reason, String errorCode) { 54 | super(reason, errorCode); 55 | } 56 | 57 | /** 58 | * Constructs a {@code TransactionRolledBackException} with the specified reason. The error code defaults to null. 59 | * 60 | * @param reason a description of the exception 61 | **/ 62 | public TransactionRolledBackException(String reason) { 63 | super(reason); 64 | } 65 | 66 | } 67 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/TransactionRolledBackRuntimeException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * This unchecked exception must be thrown when a call to {@code JMSContext.commit} results in a rollback of the current 21 | * transaction. 22 | * 23 | * @version Jakarta Messaging 2.0 24 | * @since JMS 2.0 25 | */ 26 | public class TransactionRolledBackRuntimeException extends JMSRuntimeException { 27 | 28 | /** 29 | * Explicitly set serialVersionUID to be the same as the implicit serialVersionUID of the Jakarta Messaging 2.0 version 30 | */ 31 | private static final long serialVersionUID = 2157965166257651703L; 32 | 33 | /** 34 | * Constructs a {@code TransactionRolledBackRuntimeException} with the specified detail message 35 | * 36 | * @param detailMessage a description of the exception 37 | **/ 38 | public TransactionRolledBackRuntimeException(String detailMessage) { 39 | super(detailMessage); 40 | } 41 | 42 | /** 43 | * Constructs a {@code TransactionRolledBackRuntimeException} with the specified detail message and error code. 44 | * 45 | * @param detailMessage a description of the exception 46 | * @param errorCode a provider-specific error code 47 | **/ 48 | public TransactionRolledBackRuntimeException(String detailMessage, String errorCode) { 49 | super(detailMessage, errorCode); 50 | } 51 | 52 | /** 53 | * Constructs a {@code TransactionRolledBackRuntimeException} with the specified detail message, error code and cause 54 | * 55 | * @param detailMessage a description of the exception 56 | * @param errorCode a provider-specific error code 57 | * @param cause the underlying cause of this exception 58 | */ 59 | public TransactionRolledBackRuntimeException(String detailMessage, String errorCode, Throwable cause) { 60 | super(detailMessage, errorCode, cause); 61 | } 62 | 63 | } 64 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAConnection.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * The {@code XAConnection} interface extends the capability of {@code Connection} by providing an {@code XASession} 21 | * (optional). 22 | * 23 | *
24 | * The {@code XAConnection} interface is optional. Jakarta Messaging providers are not required to support this interface. This 25 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 26 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 27 | * 28 | * @see jakarta.jms.XAQueueConnection 29 | * @see jakarta.jms.XATopicConnection 30 | * 31 | * @version Jakarta Messaging 2.0 32 | * @since JMS 1.0 33 | */ 34 | public interface XAConnection extends Connection { 35 | 36 | /** 37 | * Creates an {@code XASession} object. 38 | * 39 | * @return a newly created {@code XASession} 40 | * 41 | * @exception JMSException if the {@code XAConnection} object fails to create an {@code XASession} due to some internal 42 | * error. 43 | * 44 | * @since JMS 1.1 45 | */ 46 | XASession createXASession() throws JMSException; 47 | 48 | /** 49 | * Creates an {@code Session} object. 50 | * 51 | * @param transacted usage undefined 52 | * @param acknowledgeMode usage undefined 53 | * 54 | * @return a newly created {@code Session} 55 | * 56 | * @exception JMSException if the {@code XAConnection} object fails to create a {@code Session} due to some internal 57 | * error. 58 | * 59 | * @since JMS 1.1 60 | */ 61 | @Override 62 | Session createSession(boolean transacted, int acknowledgeMode) throws JMSException; 63 | } 64 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * The {@code XAConnectionFactory} interface is a base interface for the {@code XAQueueConnectionFactory} and 21 | * {@code XATopicConnectionFactory} interfaces. 22 | * 23 | *
24 | * Some application servers provide support for grouping JTA capable resource use into a distributed transaction 25 | * (optional). To include Jakarta Messaging API transactions in a JTA transaction, an application server requires a JTA aware JMS 26 | * provider. A Jakarta Messaging provider exposes its JTA support using an {@code XAConnectionFactory} object, which an application 27 | * server uses to create {@code XAConnection} objects. 28 | * 29 | *
30 | * {@code XAConnectionFactory} objects are Jakarta Messaging administered objects, just like {@code ConnectionFactory} objects. It is 31 | * expected that application servers will find them using the Java Naming and Directory Interface (JNDI) API. 32 | * 33 | *
34 | * The {@code XAConnectionFactory} interface is optional. Jakarta Messaging providers are not required to support this interface. This 35 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 36 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 37 | * 38 | * @version Jakarta Messaging 2.0 39 | * @since JMS 1.0 40 | */ 41 | public interface XAConnectionFactory { 42 | 43 | /** 44 | * Creates an {@code XAConnection} with the default user identity. The connection is created in stopped mode. No 45 | * messages will be delivered until the {@code Connection.start} method is explicitly called. 46 | * 47 | * @return a newly created {@code XAConnection} 48 | * 49 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA connection due to some internal error. 50 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 51 | * 52 | * @since JMS 1.1 53 | */ 54 | XAConnection createXAConnection() throws JMSException; 55 | 56 | /** 57 | * Creates an {@code XAConnection} with the specified user identity. The connection is created in stopped mode. No 58 | * messages will be delivered until the {@code Connection.start} method is explicitly called. 59 | * 60 | * @param userName the caller's user name 61 | * @param password the caller's password 62 | * 63 | * @return a newly created {@code XAConnection} 64 | * 65 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA connection due to some internal error. 66 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 67 | * 68 | * @since JMS 1.1 69 | */ 70 | XAConnection createXAConnection(String userName, String password) throws JMSException; 71 | 72 | /** 73 | * Creates a {@code XAJMSContext} with the default user identity 74 | * 75 | *
76 | * A connection and session are created for use by the new {@code XAJMSContext}. The connection is created in stopped 77 | * mode but will be automatically started when a {@code JMSConsumer} is created. 78 | * 79 | * @return a newly created {@code XAJMSContext} 80 | * 81 | * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create the {@code XAJMSContext} due to some internal 82 | * error. 83 | * @exception JMSSecurityRuntimeException if client authentication fails due to an invalid user name or password. 84 | * 85 | * @since JMS 2.0 86 | */ 87 | XAJMSContext createXAContext(); 88 | 89 | /** 90 | * Creates a JMSContext with the specified user identity 91 | * 92 | *
93 | * A connection and session are created for use by the new {@code XAJMSContext}. The connection is created in stopped 94 | * mode but will be automatically started when a {@code JMSConsumer} is created. 95 | * 96 | * @param userName the caller's user name 97 | * @param password the caller's password 98 | * 99 | * @return a newly created JMSContext 100 | * 101 | * @exception JMSRuntimeException if the Jakarta Messaging provider fails to create the JMSContext due to some internal error. 102 | * @exception JMSSecurityRuntimeException if client authentication fails due to an invalid user name or password. 103 | * 104 | * @since JMS 2.0 105 | */ 106 | XAJMSContext createXAContext(String userName, String password); 107 | 108 | } 109 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAJMSContext.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import javax.transaction.xa.XAResource; 20 | 21 | /** 22 | * The {@code XAJMSContext} interface extends the capability of {@code JMSContext} by adding access to a Jakarta Messaging provider's 23 | * support for the Java Transaction API (JTA) (optional). This support takes the form of a 24 | * {@code javax.transaction.xa.XAResource} object. The functionality of this object closely resembles that defined by 25 | * the standard X/Open XA Resource interface. 26 | * 27 | *
28 | * An application server controls the transactional assignment of an {@code XASession} by obtaining its 29 | * {@code XAResource}. It uses the {@code XAResource} to assign the session to a transaction, prepare and commit work on 30 | * the transaction, and so on. 31 | * 32 | *
33 | * An {@code XAResource} provides some fairly sophisticated facilities for interleaving work on multiple transactions, 34 | * recovering a list of transactions in progress, and so on. A JTA aware Jakarta Messaging provider must fully implement this 35 | * functionality. This could be done by using the services of a database that supports XA, or a Jakarta Messaging provider may choose 36 | * to implement this functionality from scratch. 37 | * 38 | *
39 | * A client of the application server is given what it thinks is an ordinary {@code JMSContext}. Behind the scenes, the 40 | * application server controls the transaction management of the underlying {@code XAJMSContext}. 41 | * 42 | *
43 | * The {@code XAJMSContext} interface is optional. Jakarta Messaging providers are not required to support this interface. This 44 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 45 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 46 | * 47 | * @version Jakarta Messaging 2.0 48 | * @since JMS 2.0 49 | */ 50 | public interface XAJMSContext extends JMSContext { 51 | 52 | /** 53 | * Returns the {@code JMSContext} object associated with this {@code XAJMSContext}. 54 | * 55 | * @return the {@code JMSContext} object associated with this {@code XAJMSContext} 56 | */ 57 | JMSContext getContext(); 58 | 59 | /** 60 | * Returns an {@code XAResource} to the caller. 61 | * 62 | * @return an {@code XAResource} 63 | */ 64 | XAResource getXAResource(); 65 | 66 | /** 67 | * Returns whether the session is in transacted mode; this method always returns true. 68 | * 69 | * @return true 70 | */ 71 | @Override 72 | boolean getTransacted(); 73 | 74 | /** 75 | * Throws a {@code TransactionInProgressRuntimeException}, since it should not be called for an {@code XAJMSContext} 76 | * object. 77 | * 78 | * @exception TransactionInProgressRuntimeException if the method is called on an {@code XAJMSContext}. 79 | */ 80 | @Override 81 | void commit(); 82 | 83 | /** 84 | * Throws a {@code TransactionInProgressRuntimeException}, since it should not be called for an {@code XAJMSContext} 85 | * object. 86 | * 87 | * @exception TransactionInProgressRuntimeException if the method is called on an {@code XAJMSContext}. 88 | */ 89 | @Override 90 | void rollback(); 91 | 92 | } 93 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAQueueConnection.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XAQueueConnection} provides the same create options as {@code QueueConnection} (optional). The only 21 | * difference is that an {@code XAConnection} is by definition transacted. 22 | * 23 | *
24 | * The {@code XAQueueConnection} interface is optional. Jakarta Messaging providers are not required to support this interface. This 25 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 26 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 27 | * 28 | * @see jakarta.jms.XAConnection 29 | * 30 | * @version Jakarta Messaging 2.0 31 | * @since JMS 1.0 32 | */ 33 | public interface XAQueueConnection extends XAConnection, QueueConnection { 34 | 35 | /** 36 | * Creates an {@code XAQueueSession} object. 37 | * 38 | * @return a newly created {@code XAQueueSession} 39 | * 40 | * @exception JMSException if the {@code XAQueueConnection} object fails to create an {@code XAQueueSession} due to some 41 | * internal error. 42 | */ 43 | XAQueueSession createXAQueueSession() throws JMSException; 44 | 45 | /** 46 | * Creates a {@code QueueSession} object. 47 | * 48 | * @param transacted usage undefined 49 | * @param acknowledgeMode usage undefined 50 | * 51 | * @return a newly created {@code QueueSession} 52 | * 53 | * @exception JMSException if the {@code XAQueueConnection} object fails to create a {@code QueueSession} due to some 54 | * internal error. 55 | */ 56 | @Override 57 | QueueSession createQueueSession(boolean transacted, int acknowledgeMode) throws JMSException; 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAQueueConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XAQueueConnectionFactory} provides the same create options as a {@code QueueConnectionFactory} (optional). 21 | * 22 | *
23 | * The {@code XATopicConnectionFactory} interface is optional. Jakarta Messaging providers are not required to support this interface. 24 | * This interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly 25 | * encouraged to use the transactional support available in their environment, rather than use these XA interfaces 26 | * directly. 27 | * 28 | * @see jakarta.jms.QueueConnectionFactory 29 | * @see jakarta.jms.XAConnectionFactory 30 | * 31 | * @version Jakarta Messaging 2.0 32 | * @since JMS 1.0 33 | */ 34 | public interface XAQueueConnectionFactory extends XAConnectionFactory, QueueConnectionFactory { 35 | 36 | /** 37 | * Creates an XA queue connection with the default user identity. The connection is created in stopped mode. No messages 38 | * will be delivered until the {@code Connection.start} method is explicitly called. 39 | * 40 | * @return a newly created XA queue connection 41 | * 42 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA queue connection due to some internal error. 43 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 44 | */ 45 | XAQueueConnection createXAQueueConnection() throws JMSException; 46 | 47 | /** 48 | * Creates an XA queue connection with the specified user identity. The connection is created in stopped mode. No 49 | * messages will be delivered until the {@code Connection.start} method is explicitly called. 50 | * 51 | * @param userName the caller's user name 52 | * @param password the caller's password 53 | * 54 | * @return a newly created XA queue connection 55 | * 56 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA queue connection due to some internal error. 57 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 58 | */ 59 | XAQueueConnection createXAQueueConnection(String userName, String password) throws JMSException; 60 | } 61 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XAQueueSession.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XAQueueSession} provides a regular {@code QueueSession}, which can be used to create {@code QueueReceiver}, 21 | * {@code QueueSender}, and {@code QueueBrowser} objects (optional). 22 | * 23 | *
24 | * The {@code XAQueueSession} interface is optional. Jakarta Messaging providers are not required to support this interface. This 25 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 26 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 27 | * 28 | * @see jakarta.jms.XASession 29 | * 30 | * @version Jakarta Messaging 2.0 31 | * @since JMS 1.0 32 | */ 33 | public interface XAQueueSession extends XASession { 34 | 35 | /** 36 | * Gets the queue session associated with this {@code XAQueueSession}. 37 | * 38 | * @return the queue session object 39 | * 40 | * @exception JMSException if an internal error occurs. 41 | */ 42 | QueueSession getQueueSession() throws JMSException; 43 | } 44 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XASession.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | import javax.transaction.xa.XAResource; 20 | 21 | /** 22 | * The {@code XASession} interface extends the capability of {@code Session} by adding access to a Jakarta Messaging provider's 23 | * support for the Java Transaction API (JTA) (optional). This support takes the form of a 24 | * {@code javax.transaction.xa.XAResource} object. The functionality of this object closely resembles that defined by 25 | * the standard X/Open XA Resource interface. 26 | * 27 | *
28 | * An application server controls the transactional assignment of an {@code XASession} by obtaining its 29 | * {@code XAResource}. It uses the {@code XAResource} to assign the session to a transaction, prepare and commit work on 30 | * the transaction, and so on. 31 | * 32 | *
33 | * An {@code XAResource} provides some fairly sophisticated facilities for interleaving work on multiple transactions, 34 | * recovering a list of transactions in progress, and so on. A JTA aware Jakarta Messaging provider must fully implement this 35 | * functionality. This could be done by using the services of a database that supports XA, or a Jakarta Messaging provider may choose 36 | * to implement this functionality from scratch. 37 | * 38 | *
39 | * A client of the application server is given what it thinks is a regular Jakarta Messaging {@code Session}. Behind the scenes, the 40 | * application server controls the transaction management of the underlying {@code XASession}. 41 | * 42 | *
43 | * The {@code XASession} interface is optional. Jakarta Messaging providers are not required to support this interface. This interface 44 | * is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged to use the 45 | * transactional support available in their environment, rather than use these XA interfaces directly. 46 | * 47 | * @see jakarta.jms.Session 48 | * 49 | * @version Jakarta Messaging 2.0 50 | * @since JMS 1.0 51 | */ 52 | public interface XASession extends Session { 53 | 54 | /** 55 | * Gets the session associated with this {@code XASession}. 56 | * 57 | * @return the session object 58 | * 59 | * @exception JMSException if an internal error occurs. 60 | * 61 | * @since JMS 1.1 62 | */ 63 | Session getSession() throws JMSException; 64 | 65 | /** 66 | * Returns an XA resource to the caller. 67 | * 68 | * @return an XA resource to the caller 69 | */ 70 | XAResource getXAResource(); 71 | 72 | /** 73 | * Indicates whether the session is in transacted mode. 74 | * 75 | * @return true 76 | * 77 | * @exception JMSException if the Jakarta Messaging provider fails to return the transaction mode due to some internal error. 78 | */ 79 | @Override 80 | boolean getTransacted() throws JMSException; 81 | 82 | /** 83 | * Throws a {@code TransactionInProgressException}, since it should not be called for an {@code XASession} object. 84 | * 85 | * @exception TransactionInProgressException if the method is called on an {@code XASession}. 86 | */ 87 | @Override 88 | void commit() throws JMSException; 89 | 90 | /** 91 | * Throws a {@code TransactionInProgressException}, since it should not be called for an {@code XASession} object. 92 | * 93 | * @exception TransactionInProgressException if the method is called on an {@code XASession}. 94 | */ 95 | @Override 96 | void rollback() throws JMSException; 97 | } 98 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XATopicConnection.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XATopicConnection} provides the same create options as {@code TopicConnection} (optional). The Topic 21 | * connections created are transactional. 22 | * 23 | *
24 | * The {@code XATopicConnection} interface is optional. Jakarta Messaging providers are not required to support this interface. This 25 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 26 | * to use the transactional support available in their environment, rather than use these XA interfaces directly. 27 | * 28 | * @see jakarta.jms.XAConnection 29 | * 30 | * @version Jakarta Messaging 2.0 31 | * @since JMS 1.0 32 | */ 33 | public interface XATopicConnection extends XAConnection, TopicConnection { 34 | 35 | /** 36 | * Creates an {@code XATopicSession} object. 37 | * 38 | * @return a newly created {@code XATopicSession} 39 | * 40 | * @exception JMSException if the {@code XATopicConnection} object fails to create an {@code XATopicSession} due to some 41 | * internal error. 42 | */ 43 | XATopicSession createXATopicSession() throws JMSException; 44 | 45 | /** 46 | * Creates a {@code TopicSession} object. 47 | * 48 | * @param transacted usage undefined 49 | * @param acknowledgeMode usage undefined 50 | * 51 | * @return a newly created {@code TopicSession} 52 | * 53 | * @exception JMSException if the {@code XATopicConnection} object fails to create a {@code TopicSession} due to some 54 | * internal error. 55 | */ 56 | @Override 57 | TopicSession createTopicSession(boolean transacted, int acknowledgeMode) throws JMSException; 58 | } 59 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XATopicConnectionFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XATopicConnectionFactory} provides the same create options as a {@code TopicConnectionFactory} (optional). 21 | * 22 | *
23 | * The {@code XATopicConnectionFactory} interface is optional. Jakarta Messaging providers are not required to support this interface. 24 | * This interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly 25 | * encouraged to use the transactional support available in their environment, rather than use these XA interfaces 26 | * directly. 27 | * 28 | * @see jakarta.jms.TopicConnectionFactory 29 | * @see jakarta.jms.XAConnectionFactory 30 | * 31 | * @version Jakarta Messaging 2.0 32 | * @since JMS 1.0 33 | */ 34 | public interface XATopicConnectionFactory extends XAConnectionFactory, TopicConnectionFactory { 35 | 36 | /** 37 | * Creates an XA topic connection with the default user identity. The connection is created in stopped mode. No messages 38 | * will be delivered until the {@code Connection.start} method is explicitly called. 39 | * 40 | * @return a newly created XA topic connection 41 | * 42 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA topic connection due to some internal error. 43 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 44 | */ 45 | XATopicConnection createXATopicConnection() throws JMSException; 46 | 47 | /** 48 | * Creates an XA topic connection with the specified user identity. The connection is created in stopped mode. No 49 | * messages will be delivered until the {@code Connection.start} method is explicitly called. 50 | * 51 | * @param userName the caller's user name 52 | * @param password the caller's password 53 | * 54 | * @return a newly created XA topic connection 55 | * 56 | * @exception JMSException if the Jakarta Messaging provider fails to create an XA topic connection due to some internal error. 57 | * @exception JMSSecurityException if client authentication fails due to an invalid user name or password. 58 | */ 59 | XATopicConnection createXATopicConnection(String userName, String password) throws JMSException; 60 | } 61 | -------------------------------------------------------------------------------- /api/src/main/java/jakarta/jms/XATopicSession.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved. 3 | * 4 | * This program and the accompanying materials are made available under the 5 | * terms of the Eclipse Public License v. 2.0, which is available at 6 | * http://www.eclipse.org/legal/epl-2.0. 7 | * 8 | * This Source Code may also be made available under the following Secondary 9 | * Licenses when the conditions for such availability set forth in the 10 | * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, 11 | * version 2 with the GNU Classpath Exception, which is available at 12 | * https://www.gnu.org/software/classpath/license.html. 13 | * 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 15 | */ 16 | 17 | package jakarta.jms; 18 | 19 | /** 20 | * An {@code XATopicSession} provides a regular {@code TopicSession}. which can be used to create 21 | * {@code TopicSubscriber} and {@code TopicPublisher} objects (optional). 22 | * 23 | *
24 | * The {@code XATopicSession} interface is optional. Jakarta Messaging providers are not required to support this interface. This 25 | * interface is for use by Jakarta Messaging providers to support transactional environments. Client programs are strongly encouraged 26 | * to use the transactional support available in their environment, rather than using these XA interfaces directly. 27 | * 28 | * @see jakarta.jms.XASession 29 | * @see jakarta.jms.TopicSession 30 | * 31 | * @version Jakarta Messaging 2.0 32 | * @since JMS 1.0 33 | */ 34 | public interface XATopicSession extends XASession { 35 | 36 | /** 37 | * Gets the topic session associated with this {@code XATopicSession}. 38 | * 39 | * @return the topic session object 40 | * 41 | * @exception JMSException if an internal error occurs. 42 | */ 43 | TopicSession getTopicSession() throws JMSException; 44 | } 45 | -------------------------------------------------------------------------------- /api/src/main/java/module-info.java: -------------------------------------------------------------------------------- 1 | module jakarta.messaging { 2 | // Optional for jakarta.annotation.Resource javadoc refs 3 | requires static jakarta.annotation; 4 | // Optional for XA* classes 5 | requires static transitive java.transaction.xa; 6 | 7 | exports jakarta.jms; 8 | } -------------------------------------------------------------------------------- /api/src/main/javadoc/doc-files/speclicense.html: -------------------------------------------------------------------------------- 1 | 2 |
3 |By using and/or copying this document, or the Eclipse Foundation 8 | document from which this statement is linked, you (the licensee) agree 9 | that you have read, understood, and will comply with the following 10 | terms and conditions:
11 | 12 |Permission to copy, and distribute the contents of this document, or 13 | the Eclipse Foundation document from which this statement is linked, in 14 | any medium for any purpose and without fee or royalty is hereby 15 | granted, provided that you include the following on ALL copies of the 16 | document, or portions thereof, that you use:
17 | 18 |Inclusion of the full text of this NOTICE must be provided. We 29 | request that authorship attribution be provided in any software, 30 | documents, or other items or products that you create pursuant to the 31 | implementation of the contents of this document, or any portion 32 | thereof.
33 | 34 |No right to create modifications or derivatives of Eclipse Foundation 35 | documents is granted pursuant to this license, except anyone may 36 | prepare and distribute derivative works and portions of this document 37 | in software that implements the specification, in supporting materials 38 | accompanying such software, and in documentation of such software, 39 | PROVIDED that all such works include the notice below. HOWEVER, the 40 | publication of derivative works of this document for use as a technical 41 | specification is expressly prohibited.
42 | 43 |The notice is:
44 | 45 |"Copyright © [$date-of-document] Eclipse Foundation. This software or 46 | document includes material copied from or derived from [title and URI 47 | of the Eclipse Foundation specification document]."
48 | 49 |THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT 52 | HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR 53 | WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 54 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 55 | NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE 56 | SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS 57 | WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR 58 | OTHER RIGHTS.
59 | 60 |THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE 61 | FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT 62 | OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE 63 | CONTENTS THEREOF.
64 | 65 |The name and trademarks of the copyright holders or the Eclipse 66 | Foundation may NOT be used in advertising or publicity pertaining to 67 | this document or its contents without specific, written prior 68 | permission. Title to copyright in this document will at all times 69 | remain with copyright holders.
70 | 71 | 72 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 20 | 21 |