fulmine.context
Class FTDistributionManager

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.context.FTDistributionManager

All Implemented Interfaces:

IDistributionManager, IRetransmissionManager, IDestroyable, ILifeCycle, IRpcTransmissionManager

public class FTDistributionManager
extends AbstractLifeCycle

A DistributionManager for an FTContext. This takes over the subscription and unsubscription implementations and only issues remote subscriptions if the FT context is not active, otherwise normal behaviour continues.

Author:

Ramon Servadei

Constructor Summary

FTDistributionManager(IFrameworkContext context, FTContext ftContext)

Method Summary

boolean	addSubscriptionListener(ISubscriptionListener listener) Add a container subscription listener.
protected boolean	applicationListenersExist(List<IEventListener> listeners) Identify if there are any application listeners in the list of listeners.
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected boolean	doRemoteSubscribe(String remoteContextIdentity, ISubscriptionParameters parameters, IEventListener listener) Performs the actions to service a remote subscription
protected boolean	doRemoteUnsubscribe(String remoteContextIdentity, ISubscriptionParameters parameters, IEventListener listener) Performs the actions to service an unsubscribe operation for a remote container.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
IChannel[]	getConnectedChannels() Get all the currently connected channels
IFrameReader	getFrameReader() Get the frame reader for this context
IFrameWriter	getFrameWriter() Get the frame writer for this context
protected AsyncLog	getLog() Get the log to use for the object hierarchy
void	invokeRpc(String remoteContextIdentity, byte[] rpcData) Send the RPC invocation to the remote context.
void	logConnectedChannels() Log the current connected channels
boolean	removeSubscriptionListener(ISubscriptionListener listener) Remove a container subscription listener.
void	requestRetransmit(String contextIdentity, String identityRegularExpression, IType type, IDomain domain) Send a request to the named remote context to retransmit the complete state of the IContainer instances with matching type and identity subscribe for by the local context.
void	requestRetransmitAll(String contextIdentity) Send a request to the named remote context to retransmit the complete state of all IContainer instances subscribed for by the local context.
void	retransmit(String contextIdentity, 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(String contextIdentity) Retransmit the complete state of all the IContainer instances that the (connected) remote context has subscribed for.
void	retransmitAllToAll() Retransmit the complete state of all the IContainer instances to all (connected) remote contexts that have a subscription for the container instances.
void	retransmitToAll(String identityRegularExpression, IType type, IDomain domain) Retransmit the complete state of the IContainer instances with matching type and identity to all (connected) remote contexts that have a subscription for the matching container.
boolean	subscribe(String contextIdentity, String identityRegex, IType type, IDomain domain, IEventListener listener) Subscribe the listener for the events generated by the IContainer instance(s) in the identified context that match the type, domain and identity regular expression.
boolean	unsubscribe(String contextIdentity, String identityRegex, IType type, IDomain domain, IEventListener listener) Unsubscribe the listener from the IContainer instance(s) identified by the type, domain and identity regular expression in the specified context.
String	updateRemoteContainer(String remoteContextIdentity, String identity, IType type, IDomain domain, String fieldName, String fieldValueAsString) Update a named field with a new value in a container in a remote context.

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, isActive, start, toString

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

FTDistributionManager

public FTDistributionManager(IFrameworkContext context,
                             FTContext ftContext)

Method Detail

subscribe

public boolean subscribe(String contextIdentity,
                         String identityRegex,
                         IType type,
                         IDomain domain,
                         IEventListener listener)

Description copied from interface: IDistributionManager

Subscribe the listener for the events generated by the IContainer instance(s) in the identified context that match the type, domain and identity regular expression. The supplied listener will be registered against the matching container instance(s). Events (changes to the container instance(s)) will be received by the listener.

The container type and domain is matched exactly. However, a 'wildcard' match for the type or domain can be specified using ISubscription.WILDCARD_TYPE and ISubscription.WILDCARD_DOMAIN. The identity regular expression can identify an exact container identity or it can identify multiple container identities (it is a regular expression matched against container identities).

All subscription operations occur indefinitely; the operation examines all current containers and then future created containers for an identity match. The listener is registered against any matching container. The subscription exists until either the context terminates or the IDistributionManager.unsubscribe(String, String, IType, IDomain, IEventListener) method is invoked with the same arguments. Using a regular expression matching subscription allows a listener to receive updates for containers whose identities are currently unknown or do not yet exist.

When the subscription is for a remote context (the contextIdentity does not match the local context identity), the subscription request is transmitted to the named remote context. The remote context handles the subscription using the same contract as for a local subscription. If the remote context has not yet come online, the subscription is saved until the identified remote context becomes available, at which point the subscription is transmitted.

Calling this method multiple times with the same arguments has no effect; it is idempotent.

Specified by:

subscribe in interface IDistributionManager

Parameters:

contextIdentity - the identity of context where the container(s) exist

identityRegex - the identity regular expression that will be matched against a container's identity

type - the type of the container

domain - the domain of the container

listener - the listener that will be registered for receiving events from the matching container(s)

Returns:

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

See Also:

IDistributionManager.unsubscribe(String, String, IType, IDomain, IEventListener)

unsubscribe

public boolean unsubscribe(String contextIdentity,
                           String identityRegex,
                           IType type,
                           IDomain domain,
                           IEventListener listener)

Description copied from interface: IDistributionManager

Unsubscribe the listener from the IContainer instance(s) identified by the type, domain and identity regular expression in the specified context.

The IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener) method is idempotent so if it is called multiple times with the same arguments, one call to IDistributionManager.unsubscribe(String, String, IType, IDomain, IEventListener) will remove it.

Two subscriptions with equal type and domain but identity "foo.*" and "foo" are separate subscriptions and require two unsubscribe operations; the unsubscribe for "foo.*" does not unsubscribe the "foo" subscription.

Specified by:

unsubscribe in interface IDistributionManager

Parameters:

contextIdentity - the identity of the remote context

identityRegex - the identity regular expression that will be matched against a container's identity

type - the type of the container

domain - the domain of the container

listener - the listener that will be unregistered from receiving events from matching container(s)

Returns:

true if the subscription was found and removed, false otherwise

See Also:

IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener)

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

doRemoteSubscribe

protected boolean doRemoteSubscribe(String remoteContextIdentity,
                                    ISubscriptionParameters parameters,
                                    IEventListener listener)

Performs the actions to service a remote subscription

Parameters:

remoteContextIdentity - the remote context for the subscription

parameters - the parameters for the subscription

listener - the listener for the subscription

Returns:

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

applicationListenersExist

protected boolean applicationListenersExist(List<IEventListener> listeners)

Identify if there are any application listeners in the list of listeners. Any application listeners existing mean that unsubscription cannot continue.

Parameters:

listeners - the list of listeners to examine for any application listeners

Returns:

false if there are any application listeners and unsubscription should not continue

doRemoteUnsubscribe

protected boolean doRemoteUnsubscribe(String remoteContextIdentity,
                                      ISubscriptionParameters parameters,
                                      IEventListener listener)

Performs the actions to service an unsubscribe operation for a remote container.

Parameters:

remoteContextIdentity - the remote context to unsubscribe from

parameters - the subscription parameters

listener - the listener to unsubscribe

Returns:

true if the subscription was found and removed, false otherwise

doDestroy

protected 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

getFrameReader

public IFrameReader getFrameReader()

Description copied from interface: IDistributionManager

Get the frame reader for this context

Specified by:

getFrameReader in interface IDistributionManager

Returns:

the IFrameReader for this context

getFrameWriter

public IFrameWriter getFrameWriter()

Description copied from interface: IDistributionManager

Get the frame writer for this context

Specified by:

getFrameWriter in interface IDistributionManager

Returns:

the IFrameWriter for this context

requestRetransmit

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

Description copied from interface: IRetransmissionManager

Send a request to the named remote context to retransmit the complete state of the IContainer instances with matching type and identity subscribe for by the local context.

Specified by:

requestRetransmit in interface IRetransmissionManager

Parameters:

contextIdentity - the identity of the remote context

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 void requestRetransmitAll(String contextIdentity)

Description copied from interface: IRetransmissionManager

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

Specified by:

requestRetransmitAll in interface IRetransmissionManager

Parameters:

contextIdentity - the identity of the remote context

retransmit

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

Description copied from interface: IRetransmissionManager

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.

Specified by:

retransmit in interface IRetransmissionManager

Parameters:

contextIdentity - the identity of the remote context

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

retransmitAll

public void retransmitAll(String contextIdentity)

Description copied from interface: IRetransmissionManager

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

Specified by:

retransmitAll in interface IRetransmissionManager

Parameters:

contextIdentity - the identity of the remote context

retransmitAllToAll

public void retransmitAllToAll()

Description copied from interface: IRetransmissionManager

Retransmit the complete state of all the IContainer instances to all (connected) remote contexts that have a subscription for the container instances.

Specified by:

retransmitAllToAll in interface IRetransmissionManager

retransmitToAll

public void retransmitToAll(String identityRegularExpression,
                            IType type,
                            IDomain domain)

Description copied from interface: IRetransmissionManager

Retransmit the complete state of the IContainer instances with matching type and identity to all (connected) remote contexts that have a subscription for the matching container.

Specified by:

retransmitToAll in interface IRetransmissionManager

Parameters:

identityRegularExpression - the identity regular expression to match against containers currently subscribed for by any (connected) remote contexts.

type - the type of the container

domain - the domain of the container

getConnectedChannels

public IChannel[] getConnectedChannels()

Description copied from interface: IDistributionManager

Get all the currently connected channels

Specified by:

getConnectedChannels in interface IDistributionManager

Returns:

an array of the currently connected IChannel instances

logConnectedChannels

public void logConnectedChannels()

Log the current connected channels

addSubscriptionListener

public boolean addSubscriptionListener(ISubscriptionListener listener)

Description copied from interface: IDistributionManager

Add a container subscription listener. This will be activated when container subscription and unsubscription occurs. The listener can react to the subscription requests and perform any necessary work to create and/or maintain the targeted containers for the subscription. This is complimentary to the actual subscribe function.

The listener will be added to a list only if it does not already exist in the list. Subscription events will be notified to all listeners in the list in the order they are added.

Specified by:

addSubscriptionListener in interface IDistributionManager

Parameters:

listener - a listener to add to an internal list.

Returns:

true if the listener was added, false otherwise

removeSubscriptionListener

public boolean removeSubscriptionListener(ISubscriptionListener listener)

Description copied from interface: IDistributionManager

Remove a container subscription listener. The listener will no longer receive events when a container subscription/unsubscription occurs.

Specified by:

removeSubscriptionListener in interface IDistributionManager

Parameters:

listener - the listener to remove

Returns:

true if the listener was found and removed, false otherwise

updateRemoteContainer

public String updateRemoteContainer(String remoteContextIdentity,
                                    String identity,
                                    IType type,
                                    IDomain domain,
                                    String fieldName,
                                    String fieldValueAsString)

Description copied from interface: IDistributionManager

Update a named field with a new value in a container in a remote context. This operation passes through the permission profile of this context. The operation may not succeed in the remote context (possibly due to permission rights not being sufficient for the operation).

Note: This operation may be synchronous and may therefore block on I/O.

Specified by:

updateRemoteContainer in interface IDistributionManager

Parameters:

remoteContextIdentity - the identity of the remote context where the container is hosted

identity - the identity of the container with the field to change

type - the type of the container

domain - the domain of the container

fieldName - the field name in the container to update

fieldValueAsString - the field value (as a string) to set as the new value for the named field

Returns:

a string encapsulating the result of the operation.

See Also:

#setRemoteUpdateHandler(IRemoteUpdateHandler)

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