com.rabbitmq.client.impl
Class AMQConnection

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

All Implemented Interfaces:

Connection

public class AMQConnection
extends java.lang.Object
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);
 

Then open a channel and retrieve an access ticket:

 ChannelN ch1 = conn.createChannel(1);
 ch1.open("");
 int ticket = ch1.accessRequest(realmName);
 

Field Summary

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
ShutdownSignalException	_shutdownCause When this value is null, the connection is in an "open" state.
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)

Constructor Summary

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

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

Method Summary

java.util.Map<java.lang.String,java.lang.Object>	buildClientPropertiesTable()
void	checkPreconditions() Private API - check required preconditions and protocol invariants
void	close(int closeCode, java.lang.String closeMessage) Public API - Close this connection with the given code and message.
void	close(int closeCode, java.lang.String closeMessage, boolean initiatedByApplication, java.lang.Throwable cause) Protected API - Close this connection with the given code, message and source.
Channel	createChannel() Public API - creates a new channel using an internally allocated channel number.
Channel	createChannel(int channelNumber) Public API - creates a new channel using the specified channel number.
void	disconnectChannel(int channelNumber) Protected API - respond, in the driver thread, to a ShutdownSignal.
void	ensureIsOpen()
int	getChannelMax() Get the negotiated maximum number of channels allowed.
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.
boolean	isOpen()
void	maybeSendHeartbeat() Private API - Checks lastActivityTime and heartbeat, sending a heartbeat frame if conditions are right.
Address[]	open(ConnectionParameters params, boolean insist) Called by the connection's constructor.
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	setChannelMax(int value) Protected API - set the max number of channels available
void	setFrameMax(int value) Protected API - set the max frame size.
void	setHeartbeat(int heartbeat) Protected API - set the heartbeat timeout.
void	shutdown(java.lang.Object reason, boolean initiatedByApplication, java.lang.Throwable cause) 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.
java.lang.String	toString()
void	writeFrame(Frame f) Public API - sends a frame directly to the broker.

Methods inherited from class java.lang.Object

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

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 final 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

_shutdownCause

public volatile ShutdownSignalException _shutdownCause

When this value is null, the connection is in an "open" state. When non-null, the connection is in "closed" state, and this value indicates the circumstances of the shutdown.

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

_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,
                     boolean insist,
                     FrameHandler frameHandler)
              throws RedirectException,
                     java.io.IOException

Construct a new connection to a broker.

Parameters:

params - the initialization parameters for a connection

insist - true if broker redirects are disallowed

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

Throws:

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

java.io.IOException - if an error is encountered

AMQConnection

public AMQConnection(ConnectionParameters params,
                     boolean insist,
                     FrameHandler frameHandler,
                     ExceptionHandler exceptionHandler)
              throws RedirectException,
                     java.io.IOException

Construct a new connection to a broker.

Parameters:

params - the initialization parameters for a connection

insist - true if broker redirects are disallowed

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

Throws:

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

java.io.IOException - if an error is encountered

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

isOpen

public boolean isOpen()

ensureIsOpen

public void ensureIsOpen()
                  throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

getHost

public java.lang.String getHost()

Description copied from interface: Connection

Retrieve the host.

Specified by:

getHost in interface Connection

Returns:

the hostname of the peer we're connected to.

getPort

public int getPort()

Description copied from interface: Connection

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()

Description copied from interface: Connection

Retrieve the connection parameters.

Specified by:

getParameters in interface Connection

Returns:

the initialization parameters used to open this connection.

getKnownHosts

public Address[] getKnownHosts()

Description copied from interface: Connection

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

checkPreconditions

public void checkPreconditions()

Private API - check required preconditions and protocol invariants

getChannelMax

public int getChannelMax()

Description copied from interface: Connection

Get the negotiated maximum number of channels allowed. 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 number of simultaneously-open channels permitted for this connection.

See Also:

Connection.getChannelMax()

setChannelMax

public void setChannelMax(int value)

Protected API - set the max number of channels available

getFrameMax

public int getFrameMax()

Description copied from interface: Connection

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

See Also:

Connection.getFrameMax()

setFrameMax

public void setFrameMax(int value)

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

getHeartbeat

public int getHeartbeat()

Description copied from interface: Connection

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

See Also:

Connection.getHeartbeat()

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 - creates a new channel using the specified channel number.

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 - creates 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()

open

public Address[] open(ConnectionParameters params,
                      boolean insist)
               throws RedirectException,
                      java.io.IOException

Called by the connection's constructor. 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:

params - the construction parameters for a Connection

Returns:

the known hosts that came back in the connection.open-ok

Throws:

RedirectException - if the server asks us to redirect to a different host/port.

java.io.IOException - if any other I/O error occurs

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 void shutdown(java.lang.Object reason,
                     boolean initiatedByApplication,
                     java.lang.Throwable cause)

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.

close

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

Public API - Close this connection with the given code and message. See the comments in ChannelN.close() - we're very similar.

Specified by:

close in interface Connection

Parameters:

closeCode - code indicating the reason for closing the connection - see AMQP spec for a list of codes

closeMessage - optional message describing 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,
                  boolean initiatedByApplication,
                  java.lang.Throwable cause)
           throws java.io.IOException

Protected API - Close this connection with the given code, message and source.

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object