org.jboss.mq
Class Connection

java.lang.Object
  org.jboss.mq.Connection

All Implemented Interfaces:

Connection (src) , java.io.Serializable

Direct Known Subclasses:

SpyConnection (src)

public abstract class Connection

extends java.lang.Object

implements java.io.Serializable, Connection (src)

This class implements javax.jms.Connection.

It is also the gateway through wich all calls to the JMS server is done. To do its work it needs a ServerIL to invoke (@see org.jboss.mq.server.ServerIL).

The (new from february 2002) logic for clientID is the following: if logging in with a user and passwork a preconfigured clientID may be automatically delivered from the server.

If the client wants to set it's own clientID it must do so on a connection wich does not have a prefonfigured clientID and it must do so before it calls any other methods on the connection (even getClientID()). It is not allowable to use a clientID that either looks like JBossMQ internal one (beginning with ID) or a clientID that is allready in use by someone, or a clientID that is already preconfigured in the server.

If a preconfigured ID is not get, or a valid one is not set, the server will set an internal ID. This ID is NEVER possible to use for durable subscriptions. If a prefconfigured ID or one manually set is possible to use to create a durable subscriptions is governed by the security configuration of JBossMQ. In the default setup, only preconfigured clientID's are possible to use. If using a SecurityManager, permissions to create a surable subscriptions is * the resiult of a combination of the following:

- The clientID is not one of JBossMQ's internal.

- The user is authenticated and has a role that has create set to true in the security config of the destination.

Notes for JBossMQ developers: All calls, except close(), that is possible to do on a connection must call checkClientID()

See Also:

Serialized Form

clockDaemon

protected static ClockDaemon clockDaemon

Manages the thread that pings the connection to see if it is 'alive'

destinationSubscriptions

public java.util.HashMap destinationSubscriptions

Maps a destination to a LinkedList of Subscriptions

subscriptions

public java.util.HashMap subscriptions

Maps a a subsction id to a Subscription

modeStop

public boolean modeStop

Is the connection stopped ?

serverIL

protected ServerIL (src)  serverIL

This is our connection to the JMS server

clientID

protected java.lang.String clientID

This is the clientID

connectionToken

protected ConnectionToken (src)  connectionToken

The connection token is used to identify our connection to the server.

clientILService

protected ClientILService (src)  clientILService

The object that sets up the client IL

pingPeriod

protected long pingPeriod

How often to ping the connection

ponged

protected boolean ponged

This feild is reset when a ping is sent, set when ponged.

closing

protected volatile boolean closing

Set a soon as close() is called on the connection.

temps

protected java.util.HashSet temps

Temporary destinations created by this connection

getThreadGroup

public static java.lang.ThreadGroup getThreadGroup()

getServerIL

public ServerIL (src)  getServerIL()

Gets the ServerIL attribute of the Connection object

Returns:

The ServerIL value

asynchClose

public void asynchClose()

Notification from the server that the connection is closed

asynchDeleteTemporaryDestination

public void asynchDeleteTemporaryDestination(SpyDestination (src)  dest)

Called by a TemporaryDestination which is going to be deleted()

Parameters:

dest - the temporary destination

asynchDeliver

public void asynchDeliver(ReceiveRequest (src) [] requests)

Gets the first consumer that is listening to a destination.

Parameters:

requests - the receive requests

asynchFailure

public void asynchFailure(java.lang.String reason,
                          java.lang.Throwable t)

Notification of a failure on this connection

Parameters:

reason - the reason for the failure

t - the throwable

asynchPong

public void asynchPong(long serverTime)

Invoked when the server pong us

Parameters:

serverTime - the server time

deleteTemporaryDestination

public void deleteTemporaryDestination(SpyDestination (src)  dest)
                                throws JMSException (src) 

Called by a TemporaryDestination which is going to be deleted

Parameters:

dest - the temporary destination

Throws:

JMSException (src) - for any error

setClientID

public void setClientID(java.lang.String cID)
                 throws JMSException (src) 

Description copied from interface: Connection (src)

Sets the client identifier for this connection.

The preferred way to assign a JMS client's client identifier is for it to be configured in a client-specific ConnectionFactory object and transparently assigned to the Connection object it creates.

Alternatively, a client can set a connection's client identifier using a provider-specific value. The facility to set a connection's client identifier explicitly is not a mechanism for overriding the identifier that has been administratively configured. It is provided for the case where no administratively specified identifier exists. If one does exist, an attempt to change it by setting it must throw an IllegalStateException. If a client sets the client identifier explicitly, it must do so immediately after it creates the connection and before any other action on the connection is taken. After this point, setting the client identifier is a programming error that should throw an IllegalStateException.

The purpose of the client identifier is to associate a connection and its objects with a state maintained on behalf of the client by a provider. The only such state identified by the JMS API is that required to support durable subscriptions.

If another connection with the same clientID is already running when this method is called, the JMS provider should detect the duplicate ID and throw an InvalidClientIDException.

Specified by:

setClientID in interface Connection (src)

Parameters:

cID - the unique client identifier

Throws:

JMSException (src) - if the JMS provider fails to set the client ID for this connection due to some internal error.

getClientID

public java.lang.String getClientID()
                             throws JMSException (src) 

Description copied from interface: Connection (src)

Gets the client identifier for this connection.

This value is specific to the JMS provider. It is either preconfigured by an administrator in a ConnectionFactory object or assigned dynamically by the application by calling the setClientID method.

Specified by:

getClientID in interface Connection (src)

Returns:

the unique client identifier

Throws:

JMSException (src) - if the JMS provider fails to return the client ID for this connection due to some internal error.

getExceptionListener

public ExceptionListener (src)  getExceptionListener()
                                       throws JMSException (src) 

Description copied from interface: Connection (src)

Gets the ExceptionListener object for this connection. Not every Connection has an ExceptionListener associated with it.

Specified by:

getExceptionListener in interface Connection (src)

Returns:

the ExceptionListener for this connection, or null. if no ExceptionListener is associated with this connection.

Throws:

JMSException (src) - if the JMS provider fails to get the ExceptionListener for this connection.

See Also:

Connection.setExceptionListener(javax.jms.ExceptionListener)

setExceptionListener

public void setExceptionListener(ExceptionListener (src)  listener)
                          throws JMSException (src) 

Description copied from interface: Connection (src)

Sets an exception listener for this connection.

If a JMS provider 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.

An 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.

A JMS provider should attempt to resolve connection problems itself before it notifies the client of them.

Specified by:

setExceptionListener in interface Connection (src)

Parameters:

listener - the exception listener

Throws:

JMSException (src) - if the JMS provider fails to set the exception listener for this connection.

getMetaData

public ConnectionMetaData (src)  getMetaData()
                               throws JMSException (src) 

Description copied from interface: Connection (src)

Gets the metadata for this connection.

Specified by:

getMetaData in interface Connection (src)

Returns:

the connection metadata

Throws:

JMSException (src) - if the JMS provider fails to get the connection metadata for this connection.

See Also:

ConnectionMetaData (src)

close

public void close()
           throws JMSException (src) 

Description copied from interface: Connection (src)

Closes the connection.

Since a provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close these resources when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

There is no need to close the sessions, producers, and consumers of a closed connection.

Closing a connection causes all temporary destinations to be deleted.

When this method is invoked, it should not return until message processing has been shut down in an orderly fashion. This means that all message listeners that may have been running have returned, and that all pending receives have returned. A close terminates all pending message receives on the connection's sessions' consumers. The receives may return with a message or with null, depending on whether there was a message available at the time of the close. If one or more of the connection's sessions' message listeners is processing a message at the time when connection close is invoked, all the facilities of the connection and its sessions must remain available to those listeners until they return control to the JMS provider.

Closing a connection causes any of its sessions' transactions in progress to be rolled back. In the case where a session's work is coordinated by an external transaction manager, a session's commit and rollback methods are not used and the result of a closed session's work is determined later by the transaction manager. Closing a connection does NOT force an acknowledgment of client-acknowledged sessions.

Invoking the acknowledge method of a received message from a closed connection's session must throw an IllegalStateException. Closing a closed connection must NOT throw an exception.

Specified by:

close in interface Connection (src)

Throws:

JMSException (src) - if the JMS provider fails to close the connection due to some internal error. For example, a failure to release resources or to close a socket connection can cause this exception to be thrown.

start

public void start()
           throws JMSException (src) 

Description copied from interface: Connection (src)

Starts (or restarts) a 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 (src)

Throws:

JMSException (src) - if the JMS provider fails to start message delivery due to some internal error.

See Also:

Connection.stop()

stop

public void stop()
          throws JMSException (src) 

Description copied from interface: Connection (src)

Temporarily stops a 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: synchronous receives block, and messages are not delivered to message listeners.

This call blocks until receives and/or message listeners in progress have completed.

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.

A call to stop must not return until delivery of messages has paused. This means that a client can rely on the fact that none of its message listeners will be called and that all threads of control waiting for receive calls to return will not return with a message until the connection is restarted. The receive timers for a stopped connection continue to advance, so receives may time out while the connection is stopped.

If message listeners are running when stop is invoked, the stop call must wait until all of them have returned before it may return. While these message listeners are completing, they must have the full services of the connection available to them.

Specified by:

stop in interface Connection (src)

Throws:

JMSException (src) - if the JMS provider fails to stop message delivery due to some internal error.

See Also:

Connection.start()

toString

public java.lang.String toString()

checkClientID

protected void checkClientID()
                      throws JMSException (src) 

Check that a clientID exists. If not get one from server. Also sets the setClientIdAllowed to false. Check clientId, must be called by all public methods on the jacax.jmx.Connection interface and its children.

Throws:

JMSException (src) - if clientID is null as post condition

askForAnID

protected void askForAnID()
                   throws JMSException (src) 

Ask the server for an id

Throws:

JMSException (src) - for any error

askForAnID

protected void askForAnID(java.lang.String userName,
                          java.lang.String password)
                   throws JMSException (src) 

Ask the server for an id

Parameters:

userName - the user

password - the password

Throws:

JMSException (src) - for any error

authenticate

protected void authenticate(java.lang.String userName,
                            java.lang.String password)
                     throws JMSException (src) 

Authenticate a user

Parameters:

userName - the user

password - the password

Throws:

JMSException (src) - for any error

send

protected void send(AcknowledgementRequest (src)  item)
             throws JMSException (src) 

Acknowledge/Nack a message

Parameters:

item - the acknowledgement

Throws:

JMSException (src) - for any error

send

protected void send(TransactionRequest (src)  transaction)
             throws JMSException (src) 

Commit/rollback

Parameters:

transaction - the transaction request

Throws:

JMSException (src) - for any error

startILService

protected void startILService()
                       throws JMSException (src) 

Start the il

Throws:

JMSException (src) - for any error

stopILService

protected void stopILService()
                      throws JMSException (src) 

Stop the il

Throws:

JMSException (src) - for any error

doStop

public void doStop()
            throws JMSException (src) 

Stop delivery

Throws:

JMSException (src)