Package org.objectweb.joram.client.jms

Class Connection

  • All Implemented Interfaces:
    AutoCloseable, Connection, ConnectionMBean
    Direct Known Subclasses:
    QueueConnection, TopicConnection, XAConnection
    public class Connection
extends Object
implements Connection, ConnectionMBean
    Implements the javax.jms.Connection interface.

    A Connection object allows the client's active connection to the Joram server. Connections support concurrent use, it serves several purposes:

    • It encapsulates the real connection with the Joram server (for example an open TCP/IP socket between the client and the server).
    • It needs the client authentication.
    • It specifies a unique client identifier.
    • It supports the ExceptionListener object.
    A Joram client typically creates a connection, one or more sessions, and a number of message producers and consumers.
    When a connection is created, it is in stopped mode that means that no messages are being delivered. In order to minimize any client confusion that may result from asynchronous message delivery during setup, it is typical to leave the connection in stopped mode until setup is complete. A message producer can send messages while a connection is stopped.

    • Field Detail

      • logger

        public static org.objectweb.util.monolog.api.Logger logger

      • tracker

        public static org.objectweb.util.monolog.api.Logger tracker

      • mtpx

        private RequestMultiplexer mtpx
        The request multiplexer used to communicate with the user proxy.

      • requestor

        private Requestor requestor
        The requestor used to communicate with the user proxy.

      • proxyId

        private String proxyId
        Client's agent proxy identifier.

      • key

        private int key
        Connection key.

      • factoryParameters

        private FactoryParameters factoryParameters
        The factory's parameters.

      • status

        private int status
        Status of the connection. STOP, START, CLOSE

      • sessions

        private Vector<Session> sessions
        Vector of the connection's sessions.

      • stringImage

        private String stringImage

      • hashCode

        private int hashCode

      • identity

        private org.objectweb.joram.shared.security.Identity identity

      • clientID

        private String clientID
        Client's identifier.

      • lockClientID

        private boolean lockClientID

      • JMXBeanBaseName

        protected String JMXBeanBaseName

    • Constructor Detail

      • Connection

        public Connection()
        Creates a Connection instance.

    • Method Detail

      • checkThread

        boolean checkThread()

      • checkCLSession

        boolean checkCLSession​(Session session)

      • getProxyId

        final String getProxyId()

      • lockClientId

        public void lockClientId()

      • setJMXBeanBaseName

        public void setJMXBeanBaseName​(String JMXBeanBaseName)

      • getJMXBeanName

        public String getJMXBeanName()

      • registerMBean

        public String registerMBean​(String base)

      • unregisterMBean

        public void unregisterMBean()

      • setStatus

        private void setStatus​(int status)

      • toString

        public String toString()
        String image of the connection.
        Overrides:
        toString in class Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public boolean equals​(Object obj)
        Returns true if the parameter is a Connection instance sharing the same proxy identifier and connection key.
        Overrides:
        equals in class Object

      • getTxPendingTimer

        public final long getTxPendingTimer()
        Returns the duration in seconds during which a JMS transacted (non XA) session might be pending; above that duration the session is rolled back and closed; the 0 value means "no timer".
        Specified by:
        getTxPendingTimer in interface ConnectionMBean
        Returns:
        the duration in seconds during which a JMS transacted (non XA) session might be pending.
        See Also:
        FactoryParameters.txPendingTimer

      • getImplicitAck

        public final boolean getImplicitAck()
        Indicates whether the messages consumed are implicitly acknowledged or not. If true messages are immediately removed from queue when delivered and there is none acknowledge message from client to server.

        This attribute is inherited from FactoryParameters, by default false.

        Specified by:
        getImplicitAck in interface ConnectionMBean
        Returns:
        true if messages produced are implicitly acknowledged.
        See Also:
        FactoryParameters.implicitAck, Session.isImplicitAck()

      • getAsyncSend

        public final boolean getAsyncSend()
        Indicates whether the persistent produced messages are asynchronously sent (without acknowledge) or not. Messages sent asynchronously may be lost if a failure occurs before the message is persisted on the server.

        Non persistent messages are always sent without acknowledgment.

        This attribute is inherited from FactoryParameters, by default false, persistent messages are sent with acknowledge.

        Specified by:
        getAsyncSend in interface ConnectionMBean
        Returns:
        true if messages produced are asynchronously sent.
        See Also:
        FactoryParameters.asyncSend, Session.isAsyncSend()

      • getTopicAckBufferMax

        public final int getTopicAckBufferMax()
        Get the maximum number of acknowledgements that can be buffered when using Session.DUPS_OK_ACKNOWLEDGE mode for this Connection.

        This attribute is inherited from FactoryParameters, default value is 0.

        Specified by:
        getTopicAckBufferMax in interface ConnectionMBean
        Returns:
        The Maximum number of acknowledgements that can be buffered when using Session.DUPS_OK_ACKNOWLEDGE mode.
        See Also:
        FactoryParameters.topicAckBufferMax, Session.getTopicAckBufferMax()

      • getCompressedMinSize

        public final int getCompressedMinSize()
        Returns the minimum size beyond which the message body is compressed. The default value is 0 (no compression).
        Returns:
        the minimum size beyond which the message body is compressed
        See Also:
        FactoryParameters.compressedMinSize

      • getCompressionLevel

        public final int getCompressionLevel()
        Get the compression level (0..9) for this Connection, this attribute is inherited from FactoryParameters. The default value is 1 (Deflater.BEST_SPEED).
        Returns:
        The compression level
        See Also:
        FactoryParameters.compressionLevel

      • getOutLocalAddress

        public final String getOutLocalAddress()
        Returns the local IP address on which the TCP connection is activated.

        This attribute is inherited from FactoryParameters.

        Specified by:
        getOutLocalAddress in interface ConnectionMBean
        Returns:
        the local IP address on which the TCP connection is activated.
        See Also:
        FactoryParameters.outLocalAddress

      • getOutLocalPort

        public final int getOutLocalPort()
        Returns the local IP address port on which the TCP connection is activated

        This attribute is inherited from FactoryParameters.

        Specified by:
        getOutLocalPort in interface ConnectionMBean
        Returns:
        the local IP address port on which the TCP connection is activated.
        See Also:
        FactoryParameters.outLocalPort

      • getInInterceptors

        final List<MessageInterceptor> getInInterceptors()
        returns the list of IN message interceptors.
        Each IN message interceptor is called when receiving a message.
        The execution follows the order of the elements within the list.
        Returns:
        the list of the IN message interceptors.

      • getOutInterceptors

        final List<MessageInterceptor> getOutInterceptors()
        returns the list of OUT message interceptors.
        Each OUT message interceptor is called when sending a message.
        The execution follows the order of the elements within the list.
        Returns:
        the list of the OUT message interceptors.

      • createConnectionConsumer

        public ConnectionConsumer createConnectionConsumer​(Destination dest,
                                                   String selector,
                                                   ServerSessionPool sessionPool,
                                                   int maxMessages)
                                            throws JMSException
        API method. Creates a connection consumer for this connection, this is an expert facility needed for applications servers.
        Specified by:
        createConnectionConsumer in interface Connection
        Parameters:
        dest - the destination to access.
        selector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for this message consumer.
        sessionPool - the server session pool to associate with this connection consumer.
        maxMessages - the maximum number of messages that can be assigned to a server session at one time.
        Returns:
        The connection consumer.
        Throws:
        IllegalStateException - If the connection is closed.
        InvalidSelectorException - If the selector syntax is wrong.
        InvalidDestinationException - If the target destination does not exist.
        JMSException - If the method fails for any other reason.

      • createDurableConnectionConsumer

        public ConnectionConsumer createDurableConnectionConsumer​(Topic topic,
                                                          String subName,
                                                          String selector,
                                                          ServerSessionPool sessionPool,
                                                          int maxMessages)
                                                   throws JMSException
        API method. Create a durable connection consumer for this connection, this is an expert facility needed for applications servers.
        Specified by:
        createDurableConnectionConsumer in interface Connection
        Parameters:
        topic - the topic to access.
        subName - durable subscription name.
        selector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for this message consumer.
        sessionPool - the server session pool to associate with this connection consumer.
        maxMessages - the maximum number of messages that can be assigned to a server session at one time.
        Returns:
        The durable connection consumer.
        Throws:
        IllegalStateException - If the connection is closed.
        InvalidSelectorException - If the selector syntax is wrong.
        InvalidDestinationException - If the target topic does not exist.
        JMSException - If the method fails for any other reason.

      • createSession

        public Session createSession​(boolean transacted,
                             int acknowledgeMode)
                      throws JMSException
        API method. Creates a Session object.
        Specified by:
        createSession in interface Connection
        Parameters:
        transacted - indicates whether the session is transacted.
        acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE. Additionnaly Joram defines INDIVIDUAL_ACKNOWLEDGE: With this acknowledgment mode, the client acknowledges a consumed message by calling the message's acknowledge method. Contrary to CLIENT_ACKNOWLEDGE mode this mode allows to acknowledge only the specified message.
        Returns:
        A newly created session.
        Throws:
        IllegalStateException - If the connection is closed.
        JMSException - In case of an invalid acknowledge mode.

      • createSession

        public Session createSession()
                      throws JMSException
        Creates a session using JMS 2.O specification

        In a Java SE environment or in the Java EE application client container:

        • The session will be non-transacted and received messages will be acknowledged automatically using an acknowledgement mode of Session.AUTO_ACKNOWLEDGE For a definition of the meaning of this acknowledgement mode see the link below.

        Specified by:
        createSession in interface Connection
        Throws:
        JMSException

      • createSession

        public Session createSession​(int sessionMode)
                      throws JMSException
        Creates a session using JMS 2.O specification
        Specified by:
        createSession in interface Connection
        Parameters:
        sessionMode -

        In a Java SE environment or in the Java EE application client container:

        • If transacted is set to true then the session will use a local transaction which may subsequently be committed or rolled back by calling the session's commit or rollback methods. The argument acknowledgeMode is ignored.
        • If transacted is set to false then the session will be non-transacted. In this case the argument acknowledgeMode is used to specify how messages received by this session will be acknowledged. The permitted values are Session.CLIENT_ACKNOWLEDGE, Session.AUTO_ACKNOWLEDGE and Session.DUPS_OK_ACKNOWLEDGE. For a definition of the meaning of these acknowledgement modes see the links below.

        Throws:
        JMSException - in case of invalid session mode

      • addSession

        protected void addSession​(Session session)
        Called here and by sub-classes.

      • setExceptionListener

        public void setExceptionListener​(ExceptionListener listener)
                          throws JMSException
        API method. Sets an exception listener for this connection. When Joram detects a serious problem with a connection, it informs the connection's ExceptionListener, if one has been registered. It does this by calling the listener's onException method, passing it a JMSException object describing the problem.

        The exception listener allows a client to be notified of a problem asynchronously. Some connections only consume messages, so they would have no other way to learn their connection has failed. A connection serializes execution of its ExceptionListener.

        Specified by:
        setExceptionListener in interface Connection
        Parameters:
        listener - the exception listener.
        Throws:
        IllegalStateException - If the connection is closed.
        JMSException

      • setClientID

        public void setClientID​(String clientID)
                 throws JMSException
        API method. Sets the client identifier for this connection. Joram automatically allocates a client identifier when the connection is created, so this method always throws an IllegalStateException.
        Specified by:
        setClientID in interface Connection
        Parameters:
        clientID - the unique client identifier.
        Throws:
        IllegalStateException - if the JMS client attempts to set a connection's client ID at the wrong time or when it has been administratively configured.
        JMSException

      • start

        public void start()
           throws JMSException
        API method for starting the connection.

        Starts (or restarts) the connection's delivery of incoming messages. A call to start on a connection that has already been started is ignored.

        Specified by:
        start in interface Connection
        Specified by:
        start in interface ConnectionMBean
        Throws:
        IllegalStateException - If the connection is closed or broken.
        JMSException

      • stop

        public void stop()
          throws JMSException
        API method for stopping the connection; even if the connection appears to be broken, stops the sessions.

        Temporarily stops the connection's delivery of incoming messages. Delivery can be restarted using the connection's start method. When the connection is stopped, delivery to all the connection's message consumers is inhibited.

        Stopping a connection has no effect on its ability to send messages. A call to stop on a connection that has already been stopped is ignored. This call blocks until receives and/or message listeners in progress have completed, it must not return until delivery of messages has paused.

        Specified by:
        stop in interface Connection
        Specified by:
        stop in interface ConnectionMBean
        Throws:
        IllegalStateException - If the connection is closed or broken.
        JMSException

      • close

        public void close()
           throws JMSException
        API method for closing the connection; even if the connection appears to be broken, closes the sessions.

        In order to free significant resources allocated on behalf of a connection, clients should close connections when they are not needed. Closing a connection automatically close all related sessions, producers, and consumers and causes all temporary destinations to be deleted.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Connection
        Specified by:
        close in interface ConnectionMBean
        Throws:
        JMSException - Actually never thrown.

      • doClose

        void doClose()

      • cleanup

        public void cleanup​(boolean close)
        Used by OutboundConnection in the connector layer. When a connection is put back in a pool, it must be cleaned up.
        Parameters:
        close - If true close underlying sessions.

      • nextSessionId

        String nextSessionId()
        Returns a new session identifier.

      • nextMessageId

        String nextMessageId()
        Returns a new message identifier.

      • nextSubName

        String nextSubName()
        Returns a new subscription name.

      • closeSession

        void closeSession​(Session session)
        Called by Session.

      • closeConnectionConsumer

        void closeConnectionConsumer​(MultiSessionConsumer cc)
        Called by MultiSessionConsumer. Synchronized with run().

      • syncRequest

        org.objectweb.joram.shared.client.AbstractJmsReply syncRequest​(org.objectweb.joram.shared.client.AbstractJmsRequest request)
                                                        throws JMSException
        Throws:
        JMSException

      • openMessageConsumer

        void openMessageConsumer​(String targetName)

      • isOpenMessageConsumer

        boolean isOpenMessageConsumer​(String targetName)

      • closeMessageConsumer

        boolean closeMessageConsumer​(String targetName)