com.rabbitmq.client.impl
Class AMQConnection

java.lang.Object
  com.rabbitmq.client.impl.ShutdownNotifierComponent
      com.rabbitmq.client.impl.AMQConnection

All Implemented Interfaces:

Connection, ShutdownNotifier

public class AMQConnection
extends ShutdownNotifierComponent
implements Connection

Concrete class representing and managing an AMQP connection to a broker.

To connect to a broker,

 AMQConnection conn = new AMQConnection(hostName, portNumber);
 conn.open(userName, portNumber, virtualHost);
 

 ChannelN ch1 = conn.createChannel(1);
 ch1.open("");
 

Field Summary

BlockingCell<java.lang.Object>	_appContinuation Object used for blocking main application thread when doing all the necessary connection shutdown operations
boolean	_brokerInitiatedShutdown Flag indicating whether the client received Connection.Close message from the broker
AMQChannel	_channel0 The special channel 0
ChannelManager	_channelManager Object that manages a set of channels
ExceptionHandler	_exceptionHandler Handler for (otherwise-unhandled) exceptions that crop up in the mainloop.
FrameHandler	_frameHandler Frame source/sink
int	_frameMax Maximum frame length, or zero if no limit is set
int	_heartbeat Currently-configured heartbeat interval, in seconds.
Address[]	_knownHosts Hosts retrieved from the connection.open-ok
long	_lastActivityTime Timestamp of last time we wrote a frame - used for deciding when to send a heartbeat
int	_missedHeartbeats Count of socket-timeouts that have happened without any incoming frames
ConnectionParameters	_params Initialization parameters
boolean	_running Flag controlling the main driver loop's termination
static int	CONNECTION_CLOSING_TIMEOUT Timeout used while waiting for a connection.close-ok (milliseconds)
static int	HANDSHAKE_TIMEOUT Timeout used while waiting for AMQP handshaking to complete (milliseconds)

Fields inherited from class com.rabbitmq.client.impl.ShutdownNotifierComponent

_shutdownCause, listeners

Constructor Summary

AMQConnection(ConnectionParameters params, FrameHandler frameHandler)
Construct a new connection to a broker.

AMQConnection(ConnectionParameters params, FrameHandler frameHandler, ExceptionHandler exceptionHandler)
Construct a new connection to a broker.

Method Summary

void	abort() Public API - Abort this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'.
void	abort(int timeout) Public API - Abort this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'.
void	abort(int closeCode, java.lang.String closeMessage) Public API - Abort this connection and all its channels.
void	abort(int closeCode, java.lang.String closeMessage, int timeout) Public API - Abort this connection and all its channels.
java.util.Map<java.lang.String,java.lang.Object>	buildClientPropertiesTable()
void	checkPreconditions() Private API - check required preconditions and protocol invariants
void	close() Public API - Close this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'.
void	close(int timeout) Public API - Close this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'.
void	close(int closeCode, java.lang.String closeMessage) Public API - Close this connection and all its channels.
void	close(int closeCode, java.lang.String closeMessage, boolean initiatedByApplication, java.lang.Throwable cause) Protected API - Delegates to the six-argument close method, passing 0 for the timeout, and false for the abort flag.
void	close(int closeCode, java.lang.String closeMessage, boolean initiatedByApplication, java.lang.Throwable cause, int timeout, boolean abort) Protected API - Close this connection with the given code, message, source and timeout value for all the close operations to complete.
void	close(int closeCode, java.lang.String closeMessage, int timeout) Public API - Close this connection and all its channels.
Channel	createChannel() Public API - Create a new channel, using an internally allocated channel number.
Channel	createChannel(int channelNumber) Public API - Create a new channel, using the specified channel number if possible.
void	disconnectChannel(int channelNumber) Protected API - respond, in the driver thread, to a ShutdownSignal.
void	ensureIsOpen()
int	getChannelMax() Get the negotiated maximum channel number.
ExceptionHandler	getExceptionHandler() Protected API - retrieve the current ExceptionHandler
int	getFrameMax() Get the negotiated maximum frame size.
int	getHeartbeat() Get the negotiated heartbeat interval.
java.lang.String	getHost() Retrieve the host.
Address[]	getKnownHosts() Retrieve the known hosts.
ConnectionParameters	getParameters() Retrieve the connection parameters.
int	getPort() Retrieve the port number.
void	handleConnectionClose(Command closeCommand)
void	handleSocketTimeout() Private API - Called when a frame-read operation times out.
void	maybeSendHeartbeat() Private API - Checks lastActivityTime and heartbeat, sending a heartbeat frame if conditions are right.
boolean	processControlCommand(Command c) Handles incoming control commands on channel zero.
Frame	readFrame() Private API - reads a single frame from the connection to the broker, or returns null if the read times out.
void	setFrameMax(int value) Protected API - set the max frame size.
void	setHeartbeat(int heartbeat) Protected API - set the heartbeat timeout.
ShutdownSignalException	shutdown(java.lang.Object reason, boolean initiatedByApplication, java.lang.Throwable cause, boolean notifyRpc) Protected API - causes all attached channels to terminate with a ShutdownSignal built from the argument, and stops this connection from accepting further work from the application.
void	start(boolean insist) Start up the connection, including the MainLoop thread.
java.lang.String	toString()
void	writeFrame(Frame f) Public API - sends a frame directly to the broker.

Methods inherited from class com.rabbitmq.client.impl.ShutdownNotifierComponent

addShutdownListener, getCloseReason, isOpen, notifyListeners, removeShutdownListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.rabbitmq.client.ShutdownNotifier

addShutdownListener, getCloseReason, isOpen, notifyListeners, removeShutdownListener

Field Detail

HANDSHAKE_TIMEOUT

public static final int HANDSHAKE_TIMEOUT

Timeout used while waiting for AMQP handshaking to complete (milliseconds)

See Also:

Constant Field Values

CONNECTION_CLOSING_TIMEOUT

public static final int CONNECTION_CLOSING_TIMEOUT

Timeout used while waiting for a connection.close-ok (milliseconds)

See Also:

Constant Field Values

_params

public final ConnectionParameters _params

Initialization parameters

_channel0

public final AMQChannel _channel0

The special channel 0

_channelManager

public ChannelManager _channelManager

Object that manages a set of channels

_frameHandler

public final FrameHandler _frameHandler

Frame source/sink

_running

public volatile boolean _running

Flag controlling the main driver loop's termination

_frameMax

public int _frameMax

Maximum frame length, or zero if no limit is set

_exceptionHandler

public final ExceptionHandler _exceptionHandler

Handler for (otherwise-unhandled) exceptions that crop up in the mainloop.

_appContinuation

public BlockingCell<java.lang.Object> _appContinuation

Object used for blocking main application thread when doing all the necessary connection shutdown operations

_brokerInitiatedShutdown

public boolean _brokerInitiatedShutdown

Flag indicating whether the client received Connection.Close message from the broker

_lastActivityTime

public volatile long _lastActivityTime

Timestamp of last time we wrote a frame - used for deciding when to send a heartbeat

_missedHeartbeats

public int _missedHeartbeats

Count of socket-timeouts that have happened without any incoming frames

_heartbeat

public int _heartbeat

Currently-configured heartbeat interval, in seconds. 0 meaning none.

_knownHosts

public Address[] _knownHosts

Hosts retrieved from the connection.open-ok

Constructor Detail

AMQConnection

public AMQConnection(ConnectionParameters params,
                     FrameHandler frameHandler)

Construct a new connection to a broker.

Parameters:

params - the initialization parameters for a connection

frameHandler - interface to an object that will handle the frame I/O for this connection

AMQConnection

public AMQConnection(ConnectionParameters params,
                     FrameHandler frameHandler,
                     ExceptionHandler exceptionHandler)

Construct a new connection to a broker.

Parameters:

params - the initialization parameters for a connection

frameHandler - interface to an object that will handle the frame I/O for this connection

exceptionHandler - interface to an object that will handle any special exceptions encountered while using this connection

Method Detail

disconnectChannel

public final void disconnectChannel(int channelNumber)

Protected API - respond, in the driver thread, to a ShutdownSignal.

Parameters:

channelNumber - the number of the channel to disconnect

ensureIsOpen

public void ensureIsOpen()
                  throws AlreadyClosedException

Throws:

AlreadyClosedException

getHost

public java.lang.String getHost()

Retrieve the host.

Specified by:

getHost in interface Connection

Returns:

the hostname of the peer we're connected to.

getPort

public int getPort()

Retrieve the port number.

Specified by:

getPort in interface Connection

Returns:

the port number of the peer we're connected to.

getParameters

public ConnectionParameters getParameters()

Retrieve the connection parameters.

Specified by:

getParameters in interface Connection

Returns:

the initialization parameters used to open this connection.

getKnownHosts

public Address[] getKnownHosts()

Retrieve the known hosts.

Specified by:

getKnownHosts in interface Connection

Returns:

an array of addresses for all hosts that came back in the initial AMQP.Connection.OpenOk open-ok method

start

public void start(boolean insist)
           throws java.io.IOException,
                  RedirectException

Start up the connection, including the MainLoop thread. Sends the protocol version negotiation header, and runs through Connection.Start/.StartOk, Connection.Tune/.TuneOk, and then calls Connection.Open and waits for the OpenOk. Sets heartbeat and frame max values after tuning has taken place.

Parameters:

insist - true if broker redirects are disallowed

Throws:

RedirectException - if the server is redirecting us to a different host/port

java.io.IOException - if an error is encountered

checkPreconditions

public void checkPreconditions()

Private API - check required preconditions and protocol invariants

getChannelMax

public int getChannelMax()

Get the negotiated maximum channel number. Usable channel numbers range from 1 to this number, inclusive. Note that this is the current setting, as opposed to the initially-requested setting available from Connection.getParameters().ConnectionParameters.getRequestedChannelMax().

Specified by:

getChannelMax in interface Connection

Returns:

the maximum channel number permitted for this connection.

getFrameMax

public int getFrameMax()

Get the negotiated maximum frame size. Note that this is the current setting, as opposed to the initially-requested setting available from Connection.getParameters().ConnectionParameters.getRequestedFrameMax().

Specified by:

getFrameMax in interface Connection

Returns:

the maximum frame size, in octets; zero if unlimited

setFrameMax

public void setFrameMax(int value)

Protected API - set the max frame size. Should only be called during tuning.

getHeartbeat

public int getHeartbeat()

Get the negotiated heartbeat interval. Note that this is the current setting, as opposed to the initially-requested setting available from Connection.getParameters().ConnectionParameters.getRequestedHeartbeat().

Specified by:

getHeartbeat in interface Connection

Returns:

the heartbeat interval, in seconds; zero if none

setHeartbeat

public void setHeartbeat(int heartbeat)

Protected API - set the heartbeat timeout. Should only be called during tuning.

getExceptionHandler

public ExceptionHandler getExceptionHandler()

Protected API - retrieve the current ExceptionHandler

createChannel

public Channel createChannel(int channelNumber)
                      throws java.io.IOException

Public API - Create a new channel, using the specified channel number if possible.

Specified by:

createChannel in interface Connection

Parameters:

channelNumber - the channel number to allocate

Returns:

a new channel descriptor, or null if this channel number is already in use

Throws:

java.io.IOException - if an I/O problem is encountered

createChannel

public Channel createChannel()
                      throws java.io.IOException

Public API - Create a new channel, using an internally allocated channel number.

Specified by:

createChannel in interface Connection

Returns:

a new channel descriptor, or null if none is available

Throws:

java.io.IOException - if an I/O problem is encountered

readFrame

public Frame readFrame()
                throws java.io.IOException

Private API - reads a single frame from the connection to the broker, or returns null if the read times out.

Throws:

java.io.IOException

writeFrame

public void writeFrame(Frame f)
                throws java.io.IOException

Public API - sends a frame directly to the broker.

Throws:

java.io.IOException

buildClientPropertiesTable

public java.util.Map<java.lang.String,java.lang.Object> buildClientPropertiesTable()

maybeSendHeartbeat

public void maybeSendHeartbeat()
                        throws java.io.IOException

Private API - Checks lastActivityTime and heartbeat, sending a heartbeat frame if conditions are right.

Throws:

java.io.IOException

handleSocketTimeout

public void handleSocketTimeout()
                         throws MissedHeartbeatException

Private API - Called when a frame-read operation times out. Checks to see if too many heartbeats have been missed, and if so, throws MissedHeartbeatException.

Throws:

MissedHeartbeatException - if too many silent timeouts have gone by

processControlCommand

public boolean processControlCommand(Command c)
                              throws java.io.IOException

Handles incoming control commands on channel zero.

Throws:

java.io.IOException

handleConnectionClose

public void handleConnectionClose(Command closeCommand)

shutdown

public ShutdownSignalException shutdown(java.lang.Object reason,
                                        boolean initiatedByApplication,
                                        java.lang.Throwable cause,
                                        boolean notifyRpc)

Protected API - causes all attached channels to terminate with a ShutdownSignal built from the argument, and stops this connection from accepting further work from the application.

Returns:

a shutdown signal built using the given arguments

close

public void close()
           throws java.io.IOException

Public API - Close this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'. Waits for all the close operations to complete.

Specified by:

close in interface Connection

Throws:

java.io.IOException - if an I/O problem is encountered

close

public void close(int timeout)
           throws java.io.IOException

Public API - Close this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'. This method behaves in a similar way as Connection.close(), with the only difference that it waits with a provided timeout for all the close operations to complete. When timeout is reached the socket is forced to close.

Specified by:

close in interface Connection

Parameters:

timeout - timeout (in milliseconds) for completing all the close-related operations, use -1 for infinity

Throws:

java.io.IOException - if an I/O problem is encountered

close

public void close(int closeCode,
                  java.lang.String closeMessage)
           throws java.io.IOException

Public API - Close this connection and all its channels. Waits for all the close operations to complete.

Specified by:

close in interface Connection

Parameters:

closeCode - the close code (See under "Reply Codes" in the AMQP specification)

closeMessage - a message indicating the reason for closing the connection

Throws:

java.io.IOException - if an I/O problem is encountered

close

public void close(int closeCode,
                  java.lang.String closeMessage,
                  int timeout)
           throws java.io.IOException

Public API - Close this connection and all its channels. Waits with the given timeout for all the close operations to complete. When timeout is reached the socket is forced to close.

Specified by:

close in interface Connection

Parameters:

closeCode - the close code (See under "Reply Codes" in the AMQP specification)

closeMessage - a message indicating the reason for closing the connection

timeout - timeout (in milliseconds) for completing all the close-related operations, use -1 for infinity

Throws:

java.io.IOException - if an I/O problem is encountered

abort

public void abort()

Public API - Abort this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'. Forces the connection to close. Any encountered exceptions in the close operations are silently discarded.

Specified by:

abort in interface Connection

abort

public void abort(int closeCode,
                  java.lang.String closeMessage)

Public API - Abort this connection and all its channels. Forces the connection to close and waits for all the close operations to complete. Any encountered exceptions in the close operations are silently discarded.

Specified by:

abort in interface Connection

Parameters:

closeCode - the close code (See under "Reply Codes" in the AMQP specification)

closeMessage - a message indicating the reason for closing the connection

abort

public void abort(int timeout)

Public API - Abort this connection and all its channels with the AMQP.REPLY_SUCCESS close code and message 'OK'. This method behaves in a similar way as Connection.abort(), with the only difference that it waits with a provided timeout for all the close operations to complete. When timeout is reached the socket is forced to close.

Specified by:

abort in interface Connection

Parameters:

timeout - timeout (in milliseconds) for completing all the close-related operations, use -1 for infinity

abort

public void abort(int closeCode,
                  java.lang.String closeMessage,
                  int timeout)

Public API - Abort this connection and all its channels. Forces the connection to close and waits with the given timeout for all the close operations to complete. When timeout is reached the socket is forced to close. Any encountered exceptions in the close operations are silently discarded.

Specified by:

abort in interface Connection

Parameters:

closeCode - the close code (See under "Reply Codes" in the AMQP specification)

closeMessage - a message indicating the reason for closing the connection

timeout - timeout (in milliseconds) for completing all the close-related operations, use -1 for infinity

close

public void close(int closeCode,
                  java.lang.String closeMessage,
                  boolean initiatedByApplication,
                  java.lang.Throwable cause)
           throws java.io.IOException

Protected API - Delegates to the six-argument close method, passing 0 for the timeout, and false for the abort flag.

Throws:

java.io.IOException

close

public void close(int closeCode,
                  java.lang.String closeMessage,
                  boolean initiatedByApplication,
                  java.lang.Throwable cause,
                  int timeout,
                  boolean abort)
           throws java.io.IOException

Protected API - Close this connection with the given code, message, source and timeout value for all the close operations to complete. Specifies if any encountered exceptions should be ignored.

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object