fulmine.distribution.connection
Class AbstractConnectionDiscoverer

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.distribution.connection.AbstractConnectionDiscoverer

All Implemented Interfaces:

IConnectionDiscoverer, IHeartbeatMonitor, IDestroyable, ILifeCycle

Direct Known Subclasses:

TcpConnectionDiscoverer

public abstract class AbstractConnectionDiscoverer
extends AbstractLifeCycle
implements IConnectionDiscoverer

A base-class for IConnectionDiscoverer instances. The implementation uses a UDP discovery process.

This discoverer sends out a heartbeat pulse message at a period specified by the heartbeatPeriod variable. This period can be changed dynamically at runtime using setNetworkHeartbeatPeriod(long). The pulse message encapsulates the parameters to make a connection to this local context. Once a pulse message is received by a remote context, the heartbeat pulses are expected periodically by the remote context. The expected period for receiving heartbeat pulses is determined by the remote context; it equals the remote context's heartbeat period multiplied by an allowed heartbeat miss counter. The count of missed heartbeats can also be set dynamically at runtime using setAllowableNetworkHeartbeatMissCount(int). This mechanism allows for a difference in the heartbeat periods between contexts but with a certain tolerance.

The following events are raised by this:

• ContextDiscoveredEvent when a new heartbeat pulse is received.
• ContextNotAvailableEvent when the heartbeat pulse from a previously found context is not received for more than the allowed number of missed pulses multiplied by this discoverer's heartbeat period

The discoverer uses an IContextWatchdog component to determine if heartbeat pulses should be sent out. The IContextWatchdog component is also informed if the discoverer encounters any delay between sending out consecutive pulses; this would generally indicate some form of CPU time starvation for the heartbeat generator thread.

The parameters for the UDP network and port can be configured by setting system properties UDP_DISCOVERY_NETWORK and UDP_DISCOVERY_PORT. These have defaults of DEFAULT_UDP_DISCOVERY_NETWORK and DEFAULT_UDP_DISCOVERY_PORT respectively. The network interface to bind to can be specified using the system property NETWORK_INTERFACE_NAME. This must specify the name of the NIC to bind to.

Author:

Ramon Servadei

Field Summary

static int	DEFAULT_DUPLICATE_PING_WINDOW The default time window to use to ignore duplicate pulse messages; 5sec
static String	DEFAULT_UDP_DISCOVERY_NETWORK The default UDP multicast network for discovery
static String	DEFAULT_UDP_DISCOVERY_PORT The default UDP multicast port for discovery
protected String	description The string description
protected fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatGenerator	heartbeatGenerator Handles sending out heartbeats and listening for heartbeats from other contexts
protected Thread	heartbeatGeneratorThread The thread running the heartbeatGenerator
protected fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatListener	heartbeatListener Listens for heartbeats messages from other contexts
protected Thread	heartbeatListenerThread The thread running the heartbeatListener
protected fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatProcessor	heartbeatProcessor Processes heartbeats from other contexts
protected Thread	heartbeatProcessorThread The thread running the heartbeatProcessor
protected InetAddress	network The UDP discovery network
static String	NETWORK_INTERFACE_NAME The system property to use to set the NIC.
protected int	port The UDP discovery port
protected String	pulse The pulse message this context sends out.
protected MulticastSocket	socket The multicast socket to use for discovering other connections
static String	UDP_DISCOVERY_NETWORK The system property to override the default UDP multicast network for discovery.
static String	UDP_DISCOVERY_PORT The system property to override the default UDP multicast port for discovery.

Fields inherited from interface fulmine.distribution.IHeartbeatMonitor

DEFAULT_ALLOWED_MISSED_COUNT, DEFAULT_HEARTBEAT_PERIOD

Constructor Summary

AbstractConnectionDiscoverer(IFrameworkContext context)
Constructor that retrieves network values from system properties or use default values if no system properties are set.

AbstractConnectionDiscoverer(IFrameworkContext context, String udpNetwork, int udpPort, String udpNic)
Constructor that uses parameters for the network values.

Method Summary

void	connectionDestroyed(String remoteContextIdentity) This removes the connection details in the ConnectionDestroyedEvent from the current map of known connections.
void	disablePulsing() Disable the discoverer from sending out pulses.
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
void	enablePulsing() Enable the discoverer to send out pulses.
int	getAllowableNetworkHeartbeatMissCount() Get the number of allowed missed heartbeats before a remote context is deemed to be not available.
protected abstract IConnectionParameters	getConnectionParameters(String data) Template method for sub-classes to provide the implementation of how to handle the 'pulse' message received from a peer IConnectionDiscoverer.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
InetAddress	getNetwork() Get the UDP network for connection discovery
long	getNetworkHeartbeatPeriod() Get the heartbeat period in milliseconds.
int	getPort() Get the UDP port used for connection discovery
protected abstract String	getProtocolConnectionParameters() Overridden by subclasses to provide the protocol specific parameters for connecting to the connection broker of this context.
String	getPulse() Get the pulse message sent out to other IConnectionDiscoverer instances over the discovery network
MulticastSocket	getSocket() Get the multicast socket used for connection discovery
protected boolean	isPulseFromContext(String contextIdentity, String pulseMessage) Determine if the pulse message is from the named context
protected boolean	isPulsingEnabled()
void	pulse() Send out a pulse on the discovery network.
protected void	send(String msg) Send the message to the multicast socket
void	setAllowableNetworkHeartbeatMissCount(int allowedHeartbeatMissCount) Set the allowable number of missed heartbeats from other contexts on the network before that context is deemed to be not available anymore.
void	setNetworkHeartbeatPeriod(long periodInMillis) Set the network heartbeat period.
String	toString()

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, isActive, start

Methods inherited from class java.lang.Object

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

Methods inherited from interface fulmine.distribution.connection.IConnectionDiscoverer

start

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Field Detail

UDP_DISCOVERY_NETWORK

public static final String UDP_DISCOVERY_NETWORK

The system property to override the default UDP multicast network for discovery.

See Also:

DEFAULT_UDP_DISCOVERY_NETWORK, Constant Field Values

DEFAULT_UDP_DISCOVERY_NETWORK

public static final String DEFAULT_UDP_DISCOVERY_NETWORK

The default UDP multicast network for discovery

See Also:

Constant Field Values

NETWORK_INTERFACE_NAME

public static final String NETWORK_INTERFACE_NAME

The system property to use to set the NIC. This is an optional setting overriding the default. The value must be the NIC name.

See Also:

Constant Field Values

UDP_DISCOVERY_PORT

public static final String UDP_DISCOVERY_PORT

The system property to override the default UDP multicast port for discovery.

See Also:

DEFAULT_UDP_DISCOVERY_PORT, Constant Field Values

DEFAULT_UDP_DISCOVERY_PORT

public static final String DEFAULT_UDP_DISCOVERY_PORT

The default UDP multicast port for discovery

See Also:

Constant Field Values

DEFAULT_DUPLICATE_PING_WINDOW

public static final int DEFAULT_DUPLICATE_PING_WINDOW

The default time window to use to ignore duplicate pulse messages; 5sec

See Also:

Constant Field Values

socket

protected MulticastSocket socket

The multicast socket to use for discovering other connections

heartbeatListener

protected final fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatListener heartbeatListener

Listens for heartbeats messages from other contexts

heartbeatListenerThread

protected final Thread heartbeatListenerThread

The thread running the heartbeatListener

heartbeatProcessor

protected final fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatProcessor heartbeatProcessor

Processes heartbeats from other contexts

heartbeatProcessorThread

protected final Thread heartbeatProcessorThread

The thread running the heartbeatProcessor

heartbeatGenerator

protected final fulmine.distribution.connection.AbstractConnectionDiscoverer.HeartbeatGenerator heartbeatGenerator

Handles sending out heartbeats and listening for heartbeats from other contexts

heartbeatGeneratorThread

protected final Thread heartbeatGeneratorThread

The thread running the heartbeatGenerator

pulse

protected String pulse

The pulse message this context sends out.

port

protected final int port

The UDP discovery port

network

protected final InetAddress network

The UDP discovery network

description

protected String description

The string description

Constructor Detail

AbstractConnectionDiscoverer

public AbstractConnectionDiscoverer(IFrameworkContext context)

Constructor that retrieves network values from system properties or use default values if no system properties are set.

Parameters:

context - the local context

AbstractConnectionDiscoverer

public AbstractConnectionDiscoverer(IFrameworkContext context,
                                    String udpNetwork,
                                    int udpPort,
                                    String udpNic)

Constructor that uses parameters for the network values.

Parameters:

context - the local context

udpNetwork - the UDP network

udpPort - the UDP port

udpNic - the network interface card name to bind to, null for default

Method Detail

getPort

public final int getPort()

Get the UDP port used for connection discovery

Returns:

the UDP port for connection discovery

getNetwork

public final InetAddress getNetwork()

Get the UDP network for connection discovery

Returns:

the UDP network for connection discovery

getSocket

public final MulticastSocket getSocket()

Get the multicast socket used for connection discovery

Returns:

the multicast socket used for connection discovery

getPulse

public final String getPulse()

Get the pulse message sent out to other IConnectionDiscoverer instances over the discovery network

Returns:

the pulse message sent

connectionDestroyed

public final void connectionDestroyed(String remoteContextIdentity)

This removes the connection details in the ConnectionDestroyedEvent from the current map of known connections.

Specified by:

connectionDestroyed in interface IConnectionDiscoverer

Parameters:

remoteContextIdentity - the remote context that has had a connection destroyed

getNetworkHeartbeatPeriod

public final long getNetworkHeartbeatPeriod()

Description copied from interface: IHeartbeatMonitor

Get the heartbeat period in milliseconds.

Specified by:

getNetworkHeartbeatPeriod in interface IHeartbeatMonitor

Returns:

the heartbeat period in milliseconds

getAllowableNetworkHeartbeatMissCount

public final int getAllowableNetworkHeartbeatMissCount()

Description copied from interface: IHeartbeatMonitor

Get the number of allowed missed heartbeats before a remote context is deemed to be not available.

Specified by:

getAllowableNetworkHeartbeatMissCount in interface IHeartbeatMonitor

Returns:

the number of missed heartbeats allowed before a remote context is deemed to be not available

setAllowableNetworkHeartbeatMissCount

public final void setAllowableNetworkHeartbeatMissCount(int allowedHeartbeatMissCount)

Description copied from interface: IHeartbeatMonitor

Set the allowable number of missed heartbeats from other contexts on the network before that context is deemed to be not available anymore.

Specified by:

setAllowableNetworkHeartbeatMissCount in interface IHeartbeatMonitor

Parameters:

allowedHeartbeatMissCount - the number of missed heartbeats allowed before a remote context is deemed to be not available

See Also:

IHeartbeatMonitor.setNetworkHeartbeatPeriod(long)

setNetworkHeartbeatPeriod

public final void setNetworkHeartbeatPeriod(long periodInMillis)

Description copied from interface: IHeartbeatMonitor

Set the network heartbeat period. This local context will send out a heartbeat ping message onto the network at this rate.

As a general rule-of-thumb, the heartbeat period should be small and the allowed heartbeat miss count high. This provides more leniency for not cancelling a context if heartbeats are missed.

Specified by:

setNetworkHeartbeatPeriod in interface IHeartbeatMonitor

Parameters:

periodInMillis - the heartbeat period in milliseconds

disablePulsing

public void disablePulsing()

Description copied from interface: IConnectionDiscoverer

Disable the discoverer from sending out pulses. The discoverer will still detect other IConnectionDiscoverer instances from their pulses, it just will not send out any pulses for itself; effectively it is in listening-only mode.

Specified by:

disablePulsing in interface IConnectionDiscoverer

enablePulsing

public void enablePulsing()

Description copied from interface: IConnectionDiscoverer

Enable the discoverer to send out pulses. By default, calling IConnectionDiscoverer.start() sets the discoverer in this mode unless IConnectionDiscoverer.disablePulsing() is called before IConnectionDiscoverer.start().

Specified by:

enablePulsing in interface IConnectionDiscoverer

doDestroy

protected final void doDestroy()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on destruction. Any exceptions should be thrown as a RuntimeException or subclass thereof.

Specified by:

doDestroy in class AbstractLifeCycle

doStart

protected void doStart()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on activation. Any exceptions should be thrown as a RuntimeException or subclass thereof. When this method is called, the AbstractLifeCycle.isActive() method will return true.

Specified by:

doStart in class AbstractLifeCycle

isPulseFromContext

protected boolean isPulseFromContext(String contextIdentity,
                                     String pulseMessage)

Determine if the pulse message is from the named context

Parameters:

contextIdentity - the context to compare against the pulse message

pulseMessage - the pulse message

Returns:

true if the pulse message is from the identified context

send

protected void send(String msg)

Send the message to the multicast socket

Parameters:

msg -

toString

public String toString()

Overrides:

toString in class AbstractLifeCycle

getLog

protected AsyncLog getLog()

Description copied from class: AbstractLifeCycle

Get the log to use for the object hierarchy

Overrides:

getLog in class AbstractLifeCycle

Returns:

the log to use for the object hierarchy

pulse

public final void pulse()

Description copied from interface: IConnectionDiscoverer

Send out a pulse on the discovery network. This allows other IConnectionDiscoverer instances on the same network to detect this one.

Specified by:

pulse in interface IConnectionDiscoverer

getConnectionParameters

protected abstract IConnectionParameters getConnectionParameters(String data)

Template method for sub-classes to provide the implementation of how to handle the 'pulse' message received from a peer IConnectionDiscoverer. This method inspects the data string and creates an appropriate IConnectionParameters instance representing it.

Parameters:

data - the pulse message from a peer IConnectionDiscoverer

Returns:

the IConnectionParameters extracted from the pulse message or null if the message could not be deciphered.

isPulsingEnabled

protected boolean isPulsingEnabled()

getProtocolConnectionParameters

protected abstract String getProtocolConnectionParameters()

Overridden by subclasses to provide the protocol specific parameters for connecting to the connection broker of this context. The parameters must be delimited using ProtocolMessageConstants.DELIMITER. There is no need to prepend the delimiter.

Returns:

a string of parameters for the connection protocol of the connection broker, delimited using ProtocolMessageConstants.DELIMITER