org.apache.qpid.jms.provider.failover

Class FailoverProvider

java.lang.Object

org.apache.qpid.jms.provider.DefaultProviderListener

org.apache.qpid.jms.provider.failover.FailoverProvider

All Implemented Interfaces:

Provider, ProviderListener

public class FailoverProvider
extends DefaultProviderListener
implements Provider

A Provider Facade that provides services for detection dropped Provider connections and attempting to reconnect to a different remote peer. Upon establishment of a new connection the FailoverProvider will initiate state recovery of the active JMS framework resources.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	FailoverProvider.CreateConnectionRequest Captures the initial request to create a JmsConnectionInfo based resources and ensures that if the connection is successfully established that the connection established event is triggered once before moving on to sending only connection interrupted and restored events.
protected class	FailoverProvider.FailoverRequest For all requests that are dispatched from the FailoverProvider to a connected Provider instance an instance of FailoverRequest is used to handle errors that occur during processing of that request and trigger a reconnect.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_INITIAL_RECONNECT_DELAY
static int	DEFAULT_MAX_RECONNECT_ATTEMPTS
static long	DEFAULT_MAX_RECONNECT_DELAY
static double	DEFAULT_RECONNECT_BACKOFF_MULTIPLIER
static long	DEFAULT_RECONNECT_DELAY
static int	DEFAULT_STARTUP_MAX_RECONNECT_ATTEMPTS
static boolean	DEFAULT_USE_RECONNECT_BACKOFF
static int	DEFAULT_WARN_AFTER_RECONNECT_ATTEMPTS
static int	UNLIMITED

Constructor Summary

Constructors

Constructor and Description
FailoverProvider(List<URI> uris)
FailoverProvider(List<URI> uris, Map<String,String> nestedOptions)
FailoverProvider(Map<String,String> nestedOptions)

Method Summary

Methods

Modifier and Type	Method and Description
void	acknowledge(JmsInboundMessageDispatch envelope, ProviderConstants.ACK_TYPE ackType, AsyncResult request) Called to acknowledge a JmsMessage has been delivered, consumed, re-delivered...etc.
void	acknowledge(JmsSessionId sessionId, ProviderConstants.ACK_TYPE ackType, AsyncResult request) Called to acknowledge all messages that have been delivered in a given session.
void	add(URI uri)
protected void	checkClosed()
void	close() Closes this Provider terminating all connections and canceling any pending operations.
void	commit(JmsTransactionInfo transactionInfo, AsyncResult request) Called to commit an open transaction.
void	connect() Performs the initial low level connection for this provider such as TCP or SSL connection to a remote Broker.
void	create(JmsResource resource, AsyncResult request) Create the Provider version of the given JmsResource.
void	destroy(JmsResource resourceId, AsyncResult request) Instruct the Provider to dispose of a given JmsResource.
long	getCloseTimeout()
long	getConnectTimeout()
long	getInitialReconnectDelay()
int	getMaxReconnectAttempts()
long	getMaxReconnectDelay()
JmsMessageFactory	getMessageFactory() Gets the Provider specific Message factory for use in the JMS layer when a Session is asked to create a Message type.
Map<String,String>	getNestedOptions()
ProviderListener	getProviderListener() Gets the currently set ProdiverListener instance.
double	getReconnectBackOffMultiplier()
long	getReconnectDelay()
URI	getRemoteURI() Returns the URI used to configure this Provider and specify the remote address of the Broker it connects to.
long	getRequestTimeout()
long	getSendTimeout()
int	getStartupMaxReconnectAttempts()
int	getWarnAfterReconnectAttempts() Gets the current setting controlling how many Connect / Reconnect attempts must occur before a warn message is logged.
boolean	isRandomize()
boolean	isUseReconnectBackOff()
void	onConnectionFailure(IOException ex) Called to indicate that the underlying connection to the Broker has been lost and the Provider will not perform any reconnect.
void	onInboundMessage(JmsInboundMessageDispatch envelope) Called when a new Message has arrived for a registered consumer.
void	onProviderException(Exception ex) Called to indicate that a some client operation caused or received an error that is not considered fatal at the provider level.
void	pull(JmsConsumerId consumerId, long timeout, AsyncResult request) Request a remote peer send a Message to this client.
void	recover(JmsSessionId sessionId, AsyncResult request) Called to recover all unacknowledged messages for a Session in client Ack mode.
void	remove(URI uri)
void	rollback(JmsTransactionInfo transactionInfo, AsyncResult request) Called to roll back an open transaction.
void	send(JmsOutboundMessageDispatch envelope, AsyncResult request) Sends the JmsMessage contained in the outbound dispatch envelope.
void	setInitialReconnectDelay(long initialReconnectDelay)
void	setMaxReconnectAttempts(int maxReconnectAttempts)
void	setMaxReconnectDelay(long maxReconnectDelay)
void	setProviderListener(ProviderListener listener) Sets the listener of events from this Provider instance.
void	setRandomize(boolean value)
void	setReconnectBackOffMultiplier(double reconnectBackOffMultiplier)
void	setReconnectDelay(long reconnectDealy)
void	setStartupMaxReconnectAttempts(int startupMaxReconnectAttempts)
void	setUseReconnectBackOff(boolean useReconnectBackOff)
void	setWarnAfterReconnectAttempts(int warnAfterReconnectAttempts) Sets the number of Connect / Reconnect attempts that must occur before a warn message is logged indicating that the transport is not connected.
void	start() Starts the Provider.
void	start(JmsResource resource, AsyncResult request) Starts the Provider version of the given JmsResource.
void	stop(JmsResource resource, AsyncResult request) Stops (pauses) the Provider version of the given JmsResource, the resource would then need to be started again via a call to start() For some JMS Resources it is necessary or advantageous to have a stopped state that can be triggered to stop the resource generating new events or messages.
String	toString()
void	unsubscribe(String subscription, AsyncResult request) Remove a durable topic subscription by name.

Methods inherited from class org.apache.qpid.jms.provider.DefaultProviderListener

onConnectionEstablished, onConnectionInterrupted, onConnectionRecovered, onConnectionRecovery, onConnectionRestored, onResourceRemotelyClosed

Methods inherited from class java.lang.Object

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

Field Detail

UNLIMITED

public static final int UNLIMITED

See Also:

Constant Field Values

DEFAULT_MAX_RECONNECT_ATTEMPTS

public static final int DEFAULT_MAX_RECONNECT_ATTEMPTS

See Also:

Constant Field Values

DEFAULT_STARTUP_MAX_RECONNECT_ATTEMPTS

public static final int DEFAULT_STARTUP_MAX_RECONNECT_ATTEMPTS

See Also:

Constant Field Values

DEFAULT_INITIAL_RECONNECT_DELAY

public static final long DEFAULT_INITIAL_RECONNECT_DELAY

See Also:

Constant Field Values

DEFAULT_RECONNECT_DELAY

public static final long DEFAULT_RECONNECT_DELAY

See Also:

Constant Field Values

DEFAULT_MAX_RECONNECT_DELAY

public static final long DEFAULT_MAX_RECONNECT_DELAY

DEFAULT_USE_RECONNECT_BACKOFF

public static final boolean DEFAULT_USE_RECONNECT_BACKOFF

See Also:

Constant Field Values

DEFAULT_RECONNECT_BACKOFF_MULTIPLIER

public static final double DEFAULT_RECONNECT_BACKOFF_MULTIPLIER

See Also:

Constant Field Values

DEFAULT_WARN_AFTER_RECONNECT_ATTEMPTS

public static final int DEFAULT_WARN_AFTER_RECONNECT_ATTEMPTS

See Also:

Constant Field Values

Constructor Detail

FailoverProvider

public FailoverProvider(Map<String,String> nestedOptions)

FailoverProvider

public FailoverProvider(List<URI> uris)

FailoverProvider

public FailoverProvider(List<URI> uris,
                Map<String,String> nestedOptions)

Method Detail

connect

public void connect()
             throws IOException

Description copied from interface: Provider

Performs the initial low level connection for this provider such as TCP or SSL connection to a remote Broker. If this operation fails then the Provider is considered to be unusable and no further operations should be attempted using this Provider.

Specified by:

connect in interface Provider

Throws:

IOException - if the remote resource can not be contacted.

start

public void start()
           throws IOException,
                  IllegalStateException

Description copied from interface: Provider

Starts the Provider. The start method provides a place for the Provider to perform and pre-start configuration checks to ensure that the current state is valid and that all contracts have been met prior to starting.

Specified by:

start in interface Provider

Throws:

IOException - if an error occurs during start processing.

IllegalStateException - if the Provider is improperly configured.

close

public void close()

Description copied from interface: Provider

Closes this Provider terminating all connections and canceling any pending operations. The Provider is considered unusable after this call. This call is a blocking call and will not return until the Provider has closed or an error occurs.

Specified by:

close in interface Provider

create

public void create(JmsResource resource,
          AsyncResult request)
            throws IOException,
                   javax.jms.JMSException,
                   UnsupportedOperationException

Description copied from interface: Provider

Create the Provider version of the given JmsResource. For each JMS Resource type the Provider implementation must create it's own internal representation and upon successful creation provide the caller with a response. The Provider should examine the given JmsResource to determine if the given configuration is supported or can be simulated, or is not supported in which case an exception should be thrown. It is possible for a Provider to indicate that it cannot complete a requested create either due to some mis-configuration such as bad login credentials on connection create by throwing a JMSException. If the Provider does not support creating of the indicated resource such as a Temporary Queue etc the provider may throw an UnsupportedOperationException to indicate this.

Specified by:

create in interface Provider

Parameters:

resource - The JmsResouce instance that indicates what is being created.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as bad credentials.

UnsupportedOperationException

start

public void start(JmsResource resource,
         AsyncResult request)
           throws IOException,
                  javax.jms.JMSException

Description copied from interface: Provider

Starts the Provider version of the given JmsResource. For some JMS Resources it is necessary or advantageous to have a started state that must be triggered prior to it's normal use. An example of this would be a MessageConsumer which should not receive any incoming messages until the JMS layer is in a state to handle them. One such time would be after connection recovery. A JMS consumer should normally recover with it's prefetch value set to zero, or an AMQP link credit of zero and only open up the credit window once all Connection resources are restored. The provider is required to implement this method and not throw any error other than an IOException if a communication error occurs. The start operation is not required to have any effect on the provider resource but must not throw UnsupportedOperation etc.

Specified by:

start in interface Provider

Parameters:

resource - The JmsResouce instance that indicates what is being started.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as already closed resource.

stop

public void stop(JmsResource resource,
        AsyncResult request)
          throws IOException,
                 javax.jms.JMSException

Description copied from interface: Provider

Stops (pauses) the Provider version of the given JmsResource, the resource would then need to be started again via a call to start() For some JMS Resources it is necessary or advantageous to have a stopped state that can be triggered to stop the resource generating new events or messages. An example of this would be a JMS Session which should not receive any incoming messages for any consumers until the JMS layer is in a state to handle them. One such time would be during a transaction rollback. A JMS Session should normally ensure that messages received in a transaction are set to be redelivered prior to any new deliveries on a transaction rollback. The provider is required to implement this method and not throw any error other than an IOException if a communication error occurs. The stop operation is not required to have any effect on the provider resource but must not throw UnsupportedOperation etc.

Specified by:

stop in interface Provider

Parameters:

resource - The JmsResouce instance that indicates what is being stopped.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as already closed resource.

destroy

public void destroy(JmsResource resourceId,
           AsyncResult request)
             throws IOException,
                    javax.jms.JMSException,
                    UnsupportedOperationException

Description copied from interface: Provider

Instruct the Provider to dispose of a given JmsResource. The provider is given a JmsResource which it should use to remove any associated resources and inform the remote Broker instance of the removal of this resource. If the Provider cannot destroy the resource due to a non-communication error such as the logged in user not have role access to destroy the given resource it may throw an instance of JMSException to indicate such an error.

Specified by:

destroy in interface Provider

Parameters:

resourceId - The JmsResouce that identifies a previously created JmsResource.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as not authorized.

UnsupportedOperationException

send

public void send(JmsOutboundMessageDispatch envelope,
        AsyncResult request)
          throws IOException,
                 javax.jms.JMSException

Description copied from interface: Provider

Sends the JmsMessage contained in the outbound dispatch envelope.

Specified by:

send in interface Provider

Parameters:

envelope - the message envelope containing the JmsMessage to send.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error that maps to JMS occurs such as not authorized.

acknowledge

public void acknowledge(JmsSessionId sessionId,
               ProviderConstants.ACK_TYPE ackType,
               AsyncResult request)
                 throws IOException,
                        javax.jms.JMSException

Description copied from interface: Provider

Called to acknowledge all messages that have been delivered in a given session. This method is typically used by a Session that is configured for client acknowledge mode. The acknowledgement should only be applied to Messages that have been marked as delivered and not those still awaiting dispatch.

Specified by:

acknowledge in interface Provider

Parameters:

sessionId - the ID of the Session whose delivered messages should be acknowledged.

ackType - The type of acknowledgement being done.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as unmatched ack.

acknowledge

public void acknowledge(JmsInboundMessageDispatch envelope,
               ProviderConstants.ACK_TYPE ackType,
               AsyncResult request)
                 throws IOException,
                        javax.jms.JMSException

Description copied from interface: Provider

Called to acknowledge a JmsMessage has been delivered, consumed, re-delivered...etc. The provider should perform an acknowledgement for the message based on the configured mode of the consumer that it was dispatched to and the capabilities of the protocol.

Specified by:

acknowledge in interface Provider

Parameters:

envelope - The message dispatch envelope containing the Message delivery information.

ackType - The type of acknowledgement being done.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such as unmatched ack.

commit

public void commit(JmsTransactionInfo transactionInfo,
          AsyncResult request)
            throws IOException,
                   javax.jms.JMSException,
                   UnsupportedOperationException

Description copied from interface: Provider

Called to commit an open transaction. If the provider is unable to support transactions then it should throw an UnsupportedOperationException to indicate this. The Provider may also throw a JMSException to indicate a transaction was already rolled back etc.

Specified by:

commit in interface Provider

Parameters:

transactionInfo - the transaction info that describes the transaction being committed.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such not authorized.

UnsupportedOperationException

rollback

public void rollback(JmsTransactionInfo transactionInfo,
            AsyncResult request)
              throws IOException,
                     javax.jms.JMSException,
                     UnsupportedOperationException

Description copied from interface: Provider

Called to roll back an open transaction.

Specified by:

rollback in interface Provider

Parameters:

transactionInfo - the transaction info that describes the transaction being rolled back.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such not authorized.

UnsupportedOperationException

recover

public void recover(JmsSessionId sessionId,
           AsyncResult request)
             throws IOException,
                    UnsupportedOperationException

Description copied from interface: Provider

Called to recover all unacknowledged messages for a Session in client Ack mode.

Specified by:

recover in interface Provider

Parameters:

sessionId - the Id of the JmsSession that is recovering unacknowledged messages..

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

UnsupportedOperationException

unsubscribe

public void unsubscribe(String subscription,
               AsyncResult request)
                 throws IOException,
                        javax.jms.JMSException,
                        UnsupportedOperationException

Description copied from interface: Provider

Remove a durable topic subscription by name. A provider can throw an instance of JMSException to indicate that it cannot perform the un-subscribe operation due to bad security credentials etc.

Specified by:

unsubscribe in interface Provider

Parameters:

subscription - the name of the durable subscription that is to be removed.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

javax.jms.JMSException - if an error occurs due to JMS violation such not authorized.

UnsupportedOperationException

pull

public void pull(JmsConsumerId consumerId,
        long timeout,
        AsyncResult request)
          throws IOException,
                 UnsupportedOperationException

Description copied from interface: Provider

Request a remote peer send a Message to this client. A message pull request is usually only needed in the case where the client sets a zero prefetch limit on the consumer. If the consumer has a set prefetch that's greater than zero this method should just return without performing any action. timeout < 0 then it should remain open until a message is received. timeout = 0 then it returns a message or null if none available timeout > 0 then it should remain open for timeout amount of time. The timeout value when positive is given in milliseconds.

Specified by:

pull in interface Provider

Parameters:

consumerId - the ID of the Consumer instance that is attempt to pull a message from the remote.

timeout - the amount of time to tell the remote peer to keep this pull request valid.

request - The request object that should be signaled when this operation completes.

Throws:

IOException - if an error occurs or the Provider is already closed.

UnsupportedOperationException

getMessageFactory

public JmsMessageFactory getMessageFactory()

Description copied from interface: Provider

Gets the Provider specific Message factory for use in the JMS layer when a Session is asked to create a Message type. The Provider should implement it's own internal JmsMessage core to optimize read / write and marshal operations for the connection.

Specified by:

getMessageFactory in interface Provider

Returns:

a JmsMessageFactory instance for use by the JMS layer.

checkClosed

protected void checkClosed()
                    throws IOException

Throws:

IOException

onInboundMessage

public void onInboundMessage(JmsInboundMessageDispatch envelope)

Description copied from interface: ProviderListener

Called when a new Message has arrived for a registered consumer.

Specified by:

onInboundMessage in interface ProviderListener

Overrides:

onInboundMessage in class DefaultProviderListener

Parameters:

envelope - The dispatch object containing the message and delivery information.

onConnectionFailure

public void onConnectionFailure(IOException ex)

Description copied from interface: ProviderListener

Called to indicate that the underlying connection to the Broker has been lost and the Provider will not perform any reconnect. Following this call the provider is in a failed state and further calls to it will throw an Exception.

Specified by:

onConnectionFailure in interface ProviderListener

Overrides:

onConnectionFailure in class DefaultProviderListener

Parameters:

ex - The exception that indicates the cause of this Provider failure.

onProviderException

public void onProviderException(Exception ex)

Description copied from interface: ProviderListener

Called to indicate that a some client operation caused or received an error that is not considered fatal at the provider level.

Specified by:

onProviderException in interface ProviderListener

Overrides:

onProviderException in class DefaultProviderListener

Parameters:

ex - the exception object that is being reported to the listener.

add

public void add(URI uri)

remove

public void remove(URI uri)

getRemoteURI

public URI getRemoteURI()

Description copied from interface: Provider

Returns the URI used to configure this Provider and specify the remote address of the Broker it connects to.

Specified by:

getRemoteURI in interface Provider

Returns:

the URI used to configure this Provider.

setProviderListener

public void setProviderListener(ProviderListener listener)

Description copied from interface: Provider

Sets the listener of events from this Provider instance.

Specified by:

setProviderListener in interface Provider

Parameters:

listener - The listener instance that will receive all event callbacks.

getProviderListener

public ProviderListener getProviderListener()

Description copied from interface: Provider

Gets the currently set ProdiverListener instance.

Specified by:

getProviderListener in interface Provider

Returns:

the currently set ProviderListener instance.

isRandomize

public boolean isRandomize()

setRandomize

public void setRandomize(boolean value)

getInitialReconnectDelay

public long getInitialReconnectDelay()

setInitialReconnectDelay

public void setInitialReconnectDelay(long initialReconnectDelay)

getReconnectDelay

public long getReconnectDelay()

setReconnectDelay

public void setReconnectDelay(long reconnectDealy)

getMaxReconnectDelay

public long getMaxReconnectDelay()

setMaxReconnectDelay

public void setMaxReconnectDelay(long maxReconnectDelay)

getMaxReconnectAttempts

public int getMaxReconnectAttempts()

setMaxReconnectAttempts

public void setMaxReconnectAttempts(int maxReconnectAttempts)

getStartupMaxReconnectAttempts

public int getStartupMaxReconnectAttempts()

setStartupMaxReconnectAttempts

public void setStartupMaxReconnectAttempts(int startupMaxReconnectAttempts)

getWarnAfterReconnectAttempts

public int getWarnAfterReconnectAttempts()

Gets the current setting controlling how many Connect / Reconnect attempts must occur before a warn message is logged. A value of <= 0 indicates that there will be no warn message logged regardless of how many reconnect attempts occur.

Returns:

the current number of connection attempts before warn logging is triggered.

setWarnAfterReconnectAttempts

public void setWarnAfterReconnectAttempts(int warnAfterReconnectAttempts)

Sets the number of Connect / Reconnect attempts that must occur before a warn message is logged indicating that the transport is not connected. This can be useful when the client is running inside some container or service as it gives an indication of some problem with the client connection that might not otherwise be visible. To disable the log messages this value should be set to a value <= 0

Parameters:

warnAfterReconnectAttempts - The number of failed connection attempts that must happen before a warning is logged.

getReconnectBackOffMultiplier

public double getReconnectBackOffMultiplier()

setReconnectBackOffMultiplier

public void setReconnectBackOffMultiplier(double reconnectBackOffMultiplier)

isUseReconnectBackOff

public boolean isUseReconnectBackOff()

setUseReconnectBackOff

public void setUseReconnectBackOff(boolean useReconnectBackOff)

getConnectTimeout

public long getConnectTimeout()

getCloseTimeout

public long getCloseTimeout()

getSendTimeout

public long getSendTimeout()

getRequestTimeout

public long getRequestTimeout()

getNestedOptions

public Map<String,String> getNestedOptions()

toString

public String toString()

Overrides:

toString in class Object