fulmine.distribution.channel
Class Channel

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.distribution.channel.Channel

All Implemented Interfaces:

IChannel, IChannelOperations, IRetransmitter, ISubscriptionManager, IDestroyable, ILifeCycle, IRpcTransmissionManager

public class Channel
extends AbstractLifeCycle
implements IChannel, IChannelOperations

The default channel implementation. This is thread safe. This implementation is composed of multiple collaborator objects to handle:

• subscriptions for remote containers
• subscriptions for local containers from the remote peer channel
• messages coming from the remote peer channel - see IChannel for a description of the possible messages

Subscription handling

All subscribe and unsubscribe methods are handled by two collaborating ISubscriptionManager objects; a 'transmit' and 'receive' instance. A channel passes all remote container subscription requests to its remote peer. The remote channel hands this subscription request to its 'transmit' subscription manager. This 'transmit' subscription manager handles registering for TxEvents generated by the subscribed container(s); the events are then sent to the peer channel. It also handles situations where the container(s) may not exist yet. The local channel hands the subscription request to its 'receive' subscription manager which handles adding the subscription listener to the remote container. The 'receive' subscription manager also handles situations where the remote container does not exist yet; it listens for RemoteContainerCreatedEvent.

When a channel connects to another channel, they exchange a sequence of messages to synchronise readiness with each other. A channel registers for the following system events:

• ContainerDestroyedEvent

When a channel is notified with this event it transmits it to the remote channel (if there is a subscription) and this allows remote containers to be marked as IContainer.DataState.STALE and then destroyed.

The diagram below illustrates the subscription mechanics.

          context       local_channel          remote_channel
             |               |                    |
             |               |                    |<---- subscribe for
             |               |                    |      remote container A
             |               |<--- subscribe -----|
             |               |                    |
             |               |                    |
             |               |                    |
             |               |                    |
 container A |               |                    |
  created -->|               |                    |
             |-- TxEvent --->|                    |
             | container A   |----- TxEvent ----->|
             |               |                    |----> create remote 
             |               |                    |      container A
 

When a channel is destroyed, it sends a IChannel.MSG_DESTROY_CONNECTION to the other channel so the other channel can destroy the connection. This allows messages sent by this channel to be processed by the other end and only after the messages have been processed will the connection be severed.

Author:

Ramon Servadei

Field Summary

Fields inherited from interface fulmine.distribution.channel.IChannel

DELIMITER, MSG_CONTAINER_DESTROYED, MSG_DATA, MSG_DESTROY_CONNECTION, MSG_INVOKE_RPC, MSG_RETRANSMIT, MSG_RETRANSMIT_ALL, MSG_SUBSCRIBE, MSG_SYN, MSG_SYN_ACK, MSG_UNSUBSCRIBE

Constructor Summary

protected	Channel(IChannelState state) Internally chained constructor with the state to use
	Channel(IConnection connection, IFrameworkContext context) Construct the channel

Method Summary

boolean	addListener(ISubscriptionParameters parameters, IEventListener listener) Add the listener to the IEventListener instances associated with the ISubscription represented by the parameters.
protected void	doChannelDestroyedOperation(IEventSource eventSource, boolean last) Perform the operation required on the remote IEventSource that originated from the remote context this channel connects to, when the channel is destroyed.
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
protected void	doSubscribeOperation(ISubscriptionParameters parameters) Perform any operation required when a subscription occurs.
protected void	doUnsubscribeOperation(ISubscriptionParameters parameters) Perform any operation required when an unsubscription occurs.
void	eventSourceCreated(IAddressable identity) Method to invoke when a new IEventSource is created.
void	eventSourceDestroyed(IAddressable identity) Method to invoke when an IEventSource is destroyed.
IConnection	getConnection() Get the channel's connection
byte[]	getContainerDestroyedMessage(ContainerDestroyedEvent event) Get the byte[] to represent the container destroyed event
List<IEventListener>	getListeners(ISubscriptionParameters parameters) Get a copy of the IEventListener instances that have been added to the subscription identified by the parameters.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
String	getRemoteContextIdentity() Get the identity of the remote context this channel connects to
Collection<IEventSource>	getSubscribedSources() Get a copy of the Collection of all the event sources that are currently subscribed for.
Collection<IEventSource>	getSubscribedSources(ISubscriptionParameters parameters) Get a copy of the Collection of the currently subscribed event sources that are matched by the subscription parameters.
boolean	includes(IAddressable parameters) Determine if there is at least one ISubscription instance whose subscription parameters include the parameters passed in.
void	invokeRpc(String remoteContextIdentity, byte[] rpcData) Send the RPC invocation to the remote context.
boolean	isConnectionSyn() Find out if the connection to the peer channel synchronized
boolean	isSubscribed(IEventSource source) Determine if there is at least one ISubscription that has a match reference for the event source.
boolean	removeListener(ISubscriptionParameters parameters, IEventListener listener) Remove the listener from the IEventListener instances associated with the ISubscription represented by the parameters.
void	requestRetransmit(String identityRegularExpression, IType type, IDomain domain) Send a request to the connected remote context to retransmit the complete state of the subscribed IContainer instances with matching type and identity.
void	requestRetransmitAll() Send a request to the connected remote context to retransmit the complete state of all the IContainer instances subscribed for by the local context.
void	retransmit(String identityRegularExpression, IType type, IDomain domain) Retransmit the complete state of the IContainer instances with matching type and identity to the connected remote context.
void	retransmitAll() Retransmit the complete state of all the IContainer instances that the connected remote context has subscribed for.
void	send(byte[] bytes) Send a message to the connected channel.
void	setConnectionSyn() Mark the connection to the peer channel as synchronized.
boolean	subscribe(ISubscriptionParameters parameters) Create an ISubscription for the event source(s) represented in the subscription parameters.
String	toString()
boolean	unsubscribe(ISubscriptionParameters parameters) Remove the subscription represented by the parameters.

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

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Constructor Detail

Channel

public Channel(IConnection connection,
               IFrameworkContext context)

Construct the channel

Parameters:

connection - the connection to the remote context

context - the local context for the channel

Channel

protected Channel(IChannelState state)

Internally chained constructor with the state to use

Parameters:

state - the state for the channel

Method Detail

subscribe

public final boolean subscribe(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

Create an ISubscription for the event source(s) represented in the subscription parameters. The created subscription is keyed against the parameters argument.

This is an idempotent operation.

Specified by:

subscribe in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

true if the subscription was created, false if it already existed

See Also:

ISubscriptionManager.getSubscribedSources(ISubscriptionParameters), ISubscriptionManager.unsubscribe(ISubscriptionParameters)

doSubscribeOperation

protected void doSubscribeOperation(ISubscriptionParameters parameters)

Perform any operation required when a subscription occurs.

Parameters:

parameters - the parameters identifying the subscription

unsubscribe

public final boolean unsubscribe(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

Remove the subscription represented by the parameters. The subscription is found by looking it up against the parameters as its key.

This unregisters the listener(s) associated with the subscription from the event source(s) that the subscription matched and destroys the associated ISubscription instance.

This is an idempotent operation.

Specified by:

unsubscribe in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

true if a subscription was found, false otherwise

See Also:

ISubscriptionManager.getSubscribedSources(ISubscriptionParameters), ISubscriptionManager.subscribe(ISubscriptionParameters)

doUnsubscribeOperation

protected void doUnsubscribeOperation(ISubscriptionParameters parameters)

Perform any operation required when an unsubscription occurs.

Parameters:

parameters - the parameters identifying subscription

send

public final void send(byte[] bytes)

Description copied from interface: IChannelOperations

Send a message to the connected channel.

Specified by:

send in interface IChannelOperations

Parameters:

bytes - the byte[] encapsulating the message to send

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

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

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

doChannelDestroyedOperation

protected void doChannelDestroyedOperation(IEventSource eventSource,
                                           boolean last)

Perform the operation required on the remote IEventSource that originated from the remote context this channel connects to, when the channel is destroyed.

Parameters:

eventSource - a remote event source that is associated with the remote context this channel connects to

last - signals if this is the last event source

getRemoteContextIdentity

public final String getRemoteContextIdentity()

Description copied from interface: IChannel

Get the identity of the remote context this channel connects to

Specified by:

getRemoteContextIdentity in interface IChannel

Returns:

a string for the identity of the remote IFrameworkContext

toString

public final String toString()

Overrides:

toString in class AbstractLifeCycle

isConnectionSyn

public final boolean isConnectionSyn()

Description copied from interface: IChannelOperations

Find out if the connection to the peer channel synchronized

Specified by:

isConnectionSyn in interface IChannelOperations

Returns:

true if the connection to the peer channel is synchronized.

setConnectionSyn

public final void setConnectionSyn()

Description copied from interface: IChannelOperations

Mark the connection to the peer channel as synchronized.

Specified by:

setConnectionSyn in interface IChannelOperations

requestRetransmit

public final void requestRetransmit(String identityRegularExpression,
                                    IType type,
                                    IDomain domain)

Description copied from interface: IRetransmitter

Send a request to the connected remote context to retransmit the complete state of the subscribed IContainer instances with matching type and identity.

Wildcards are not supported with this operation.

Specified by:

requestRetransmit in interface IRetransmitter

Parameters:

identityRegularExpression - the identity regular expression to match against containers currently subscribed for by the local context

type - the type of the container

domain - the domain of the container

requestRetransmitAll

public final void requestRetransmitAll()

Description copied from interface: IRetransmitter

Send a request to the connected remote context to retransmit the complete state of all the IContainer instances subscribed for by the local context.

Specified by:

requestRetransmitAll in interface IRetransmitter

retransmitAll

public final void retransmitAll()

Description copied from interface: IRetransmitter

Retransmit the complete state of all the IContainer instances that the connected remote context has subscribed for.

Specified by:

retransmitAll in interface IRetransmitter

retransmit

public final void retransmit(String identityRegularExpression,
                             IType type,
                             IDomain domain)

Description copied from interface: IRetransmitter

Retransmit the complete state of the IContainer instances with matching type and identity to the connected remote context. The container must also currently be subscribed for by the remote context.

Wildcards are not supported with this operation.

Specified by:

retransmit in interface IRetransmitter

Parameters:

identityRegularExpression - the identity regular expression to match against containers currently subscribed for by the remote context

type - the type of the container

domain - the domain of the container

getConnection

public final IConnection getConnection()

Description copied from interface: IChannel

Get the channel's connection

Specified by:

getConnection in interface IChannel

Returns:

the IConnection used by the channel

addListener

public final boolean addListener(ISubscriptionParameters parameters,
                                 IEventListener listener)

Description copied from interface: ISubscriptionManager

Add the listener to the IEventListener instances associated with the ISubscription represented by the parameters. The subscription is found using the same lookup semantics as #getSubscription(ISubscriptionParameters).

On adding, the subscription will register the listener with any currently matched IEventSource instances.

This is an idempotent operation.

Specified by:

addListener in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

listener - the listener to add to the subscription's list of listeners

Returns:

true if the listener was added, false if it already existed

eventSourceCreated

public final void eventSourceCreated(IAddressable identity)

Description copied from interface: ISubscriptionManager

Method to invoke when a new IEventSource is created. This provides the manager with the mechanism to be notified when event sources are created and go through existing subscriptions to identify if the new event source should be subscribed for.

Specified by:

eventSourceCreated in interface ISubscriptionManager

Parameters:

identity - identifies the attributes of the created event source

eventSourceDestroyed

public final void eventSourceDestroyed(IAddressable identity)

Description copied from interface: ISubscriptionManager

Method to invoke when an IEventSource is destroyed. Complimentary to ISubscriptionManager.eventSourceCreated(IAddressable).

Specified by:

eventSourceDestroyed in interface ISubscriptionManager

Parameters:

identity - identifies the attributes of the destroyed event source

getSubscribedSources

public final Collection<IEventSource> getSubscribedSources()

Description copied from interface: ISubscriptionManager

Get a copy of the Collection of all the event sources that are currently subscribed for.

Specified by:

getSubscribedSources in interface ISubscriptionManager

Returns:

a copy of the Collection of all the event source instances that are currently subscribed for

getSubscribedSources

public final Collection<IEventSource> getSubscribedSources(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

Get a copy of the Collection of the currently subscribed event sources that are matched by the subscription parameters.

This does a matching operation to find any other ISubscriptions that would include these parameters and then adds the IEventSources to the collection to return.

This is not a key lookup operation.

Specified by:

getSubscribedSources in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters to match against event sources currently subscribed for

Returns:

a copy of the Collection of the event sources currently subscribed for and that are matched by the subscription parameters argument

isSubscribed

public final boolean isSubscribed(IEventSource source)

Description copied from interface: ISubscriptionManager

Determine if there is at least one ISubscription that has a match reference for the event source.

This checks if the event source is already subscribed. To find out if this source would be subscribed, use #includes(ISubscriptionParameters).

Specified by:

isSubscribed in interface ISubscriptionManager

Parameters:

source - the event source to check for at least one subscription within this manager

Returns:

true if the source is found in at least one subscription within this manager

removeListener

public final boolean removeListener(ISubscriptionParameters parameters,
                                    IEventListener listener)

Description copied from interface: ISubscriptionManager

Remove the listener from the IEventListener instances associated with the ISubscription represented by the parameters. The subscription is found using the same lookup semantics as #getSubscription(ISubscriptionParameters).

On removal, the subscription will unregister the listener from any currently matched IEventSource instances.

This is an idempotent operation.

Specified by:

removeListener in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

listener - the listener to remove from the subscription's list of listeners

Returns:

true if the listener was removed, false if it was not found

includes

public final boolean includes(IAddressable parameters)

Description copied from interface: ISubscriptionManager

Determine if there is at least one ISubscription instance whose subscription parameters include the parameters passed in.

This operation is not a key lookup and will search through all subscriptions until one is found that would include the parameters.

Specified by:

includes in interface ISubscriptionManager

Parameters:

parameters - the parameters to check

Returns:

true if there is at least one subscription instance that includes the parameters

See Also:

ISubscriptionParameters.includes(IAddressable)

getListeners

public List<IEventListener> getListeners(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

Get a copy of the IEventListener instances that have been added to the subscription identified by the parameters. The subscription is found using a key lookup operation; the subscription is found by association with the parameters.

This operation performs no semantic matching with wildcards, it is a key lookup operation.

Specified by:

getListeners in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

the list of IEventListener instances for the identified subscription or Collections.emptyList()

getContainerDestroyedMessage

public final byte[] getContainerDestroyedMessage(ContainerDestroyedEvent event)

Description copied from interface: IChannelOperations

Get the byte[] to represent the container destroyed event

Specified by:

getContainerDestroyedMessage in interface IChannelOperations

Parameters:

event - the container destroyed event to convert into byte[] form

Returns:

a byte[] representing the container destroyed event

invokeRpc

public void invokeRpc(String remoteContextIdentity,
                      byte[] rpcData)

Description copied from interface: IRpcTransmissionManager

Send the RPC invocation to the remote context. This should only be accessed by non-application code.

Specified by:

invokeRpc in interface IRpcTransmissionManager

Parameters:

remoteContextIdentity - the identity of the remote context that the RPC should be sent to

rpcData - the RPC in its byte[] form

See Also:

IRpcManager