fulmine.context
Class FTContext

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.context.FTContext

All Implemented Interfaces:

IFrameworkContext, IFulmineContext, IDistributionManager, IRetransmissionManager, IEventManager, IDestroyable, ILifeCycle, IModelManager, IRpcManager, IRpcPublishOperations, IRpcTransmissionManager

public class FTContext
extends AbstractLifeCycle
implements IFrameworkContext

A context that exists within a cluster of peer contexts. These all exist to provide fault tolerance for a single logical application context identity. An FT cluster is identified by a 'cluster identity'. Each FT context within the cluster has the same logical application context identity but a unique FT context identity. The FT context identity always starts with the cluster identity. Only one FT context within the cluster will be 'active'. This active context is the context servicing all remote subscriptions for the logical application context. The other contexts will be in a standby mode.

The FT context actually hosts a second context that is the application context; both the FT context and application contexts are separate IFrameworkContext instances. The FT context has a separate network for its FT activities. When the FT context determines it should be active, it activates the application context; the application context is always started at the same time as the FT context but has its network set to 'listening mode' (INetwork.setListeningOnlyMode(boolean)). When the application context is activated, its network IConnectionDiscoverer is also activated (IConnectionDiscoverer.enablePulsing()); this will then cause the application context to be discovered by other application contexts. Should the FT context go into standby mode after this, the application context will have its network IConnectionDiscoverer disabled ( IConnectionDiscoverer.disablePulsing()).

Fault tolerance algorithm

Each context is constructed with a fault tolerant number. This indicates the ordering, relative to the other contexts in the FT cluster, for becoming active. The context with the lowest FT number in the cluster is the active context, unless there is already an active context in the cluster. This numbering also provides the mechanism for all contexts to organise themselves on startup so that there is only 1 active context.

A context has 4 states;

1. Startup - The initial state of the context.
2. Provisional active - the period when a context marks itself as 'provisionally active' and awaits any conflicts. This phase is used to marshal conflicts between contexts and ensure only 1 progresses to the active state.
3. Active - the period when the context becomes the active context in the cluster. This phase is when the context can start servicing remote subscriptions for the cluster as a logical application context.
4. Standby - the context is in a waiting state, prepared for if the current active context leaves the cluster. The standby state is a 'warm' state.

Startup

On startup, an FT context uses its FT network IConnectionDiscoverer to find any other FT contexts within the same cluster. When an FT context finds another within the cluster, each subscribes for a 'context info' record from the other. This record contains the following attributes:

• FT canonical ID (string)
• FT number (int)
• start time (long)
• provisionally active (boolean)
• active (boolean)

If the context finds any other active context, it switches to standby. Otherwise, it updates its context info record to indicate it is provisionally active and waits for a period of time to allow discovery of other contexts. If no contexts are found it switches to the provisional active state.

Provisional active

In this state it checks that there are no other active FT contexts and if none are found, it switches to the active state. Should there be more than one provisionally active FT context discovered in this state, a conflict resolution protocol ensues;

1. The FT context with the lesser context number assumes priority, the greater numbered context should yield to the lesser one.
2. Should both contexts have the same number, then the context with the greater FT canonical ID (as per string comparison) assumes active state, the other will yield and go into stand-by mode.

Active

Once an FT context has confirmed it is the active context for the cluster, it activates its hosted application contexts IConnectionDiscoverer that will broadcast the identity of the logical application context to other contexts (outside the FT cluster).

Loss of active FT context

If the active FT context is lost, all remaining FT contexts compare their number with each other. The lowest becomes the new active FT context and enters the provisional active state and following that (assuming no conflicts arise) the active state.

Application code can supply an IFTContextStateListener to react to whether the FT context is active or stand-by.

FT standby scope

An FT context only has a standby scope of 'warm'. In this state, the FT context is running but does not replicate the state of the current active FT context. If a standby FT context becomes active it will need to perform all necessary work to create the expected records to service any existing remote subscriptions (the subscriptions will be received when the context broadcasts its logical context identity).

From a 'client' perspective, whenever an FT context takes over as being the active context in a cluster, the client will experience a network interrupt. When the new FT context is re-discovered, the client will re-connect and re-subscribe for the containers.

Author:

Ramon Servadei

Field Summary

static long

HEARTBEAT_MULTIPLIER The number of heartbeats that the FTContext activation period should be.

Fields inherited from interface fulmine.context.IFrameworkContext

NAME

Fields inherited from interface fulmine.rpc.IRpcManager

DEFAULT_RPC_TIMEOUT, RPC_TIMEOUT

Constructor Summary

FTContext(IFrameworkContext appContext, IFTContextStateListener stateListener, INetwork ftNetwork, int number, long activationDelayMillis)
Standard constructor for an FT context that provides FT capability to a hosted application context.

Method Summary

protected void	activate() Invoked by the Confirmed state and encapsulates the logic the FTContext needs to perform to go into the active state.
void	addContainer(IContainer container) Add a container to this context.
boolean	addRpcPublicationListener(String remoteContextIdentity, IRpcPublicationListener listener) Add a listener for RPC publication events.
boolean	addSubscriptionListener(ISubscriptionListener listener) Add a container subscription listener.
boolean	containsLocalContainer(String identityRegularExpression, IType type, IDomain domain) Identify if the local container exists in this context
boolean	containsRemoteContainer(String remoteContextIdentity, String containerIdentity, IType type, IDomain domain) Identify if the remote container exists in this context
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doStandby(IFrameworkContext context, INetwork network, IConnectionDiscoverer discoverer, IConnectionBroker connectionBroker) Standard operation for standby that stops heartbeat pulsing and recreates the IConnectionBroker
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
void	execute(Runnable task) Add the task to a queue to be executed by a single worker thread.
protected IFrameworkContext	getAppContext()
IChannel[]	getConnectedChannels() Get all the currently connected channels
IConnectionBroker	getConnectionBroker() Get the connection broker for the context.
IConnectionDiscoverer	getConnectionDiscoverer() Get the connection discoverer in use by this context.
IContainerFactory	getContainerFactory() Get the container factory for the context.
int	getContextHashCode() Get a unique integer for this context.
IContextWatchdog	getContextWatchdog() Get the component that will report on the state of this context
IDistributionManager	getDistributionManager() Get the distribution manager assigned to the context
int	getEventProcessorCount() Get the number of EventProcessor instances in this context
String	getEventProcessorIdentityPrefix() Get the event processor identity prefix.
ThreadGroup	getEventProcessorThreadGroup() Get the ThreadGroup for the event processors.
IFrameReader	getFrameReader() Get the frame reader for this context
IFrameWriter	getFrameWriter() Get the frame writer for this context
String	getIdentity() Get the unique identity of this context.
IContainer	getLocalContainer(String identity, IType type, IDomain domain) Get the identified local container.
Collection<IContainer>	getLocalContainers() Get a copy of the collection of local containers in this context.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
INetwork	getNetwork() Get the network
IPermissionProfile	getPermissionProfile() Get the permission profile for the context.
IContainer	getRemoteContainer(String remoteContextIdentity, String containerIdentity, IType type, IDomain domain) Get the identified remote container.
Collection<IContainer>	getRemoteContainers(String remoteContextIdentity) Get a copy of the collection of remote containers in this context.
ISystemEventSource	getSystemEventSource(Class<? extends ISystemEvent> type) Get an ISystemEventSource that is used to propagate a single specific type of ISystemEvent.
IContainer	getSystemInfo() Get the 'system info' record that is used to encapsulate any system level information about the context.
IRpcMarker	invoke(IRpcResultHandler resultHandler, String remoteContextIdentity, String procedure, IField... args) Asynchronously invoke the RPC in the named remote context.
IRpcResult	invoke(String remoteContextIdentity, String procedure, IField... args) Synchronously invoke the RPC in the named remote context.
void	invokeRpc(String remoteContextIdentity, byte[] rpcData) Send the RPC invocation to the remote context.
boolean	isFTContextActive() Determine if this FT context is active.
protected void	prepareAppContextForStart() Prepare the application context before calling start.
boolean	publishProdedure(IRpcHandler handler, IRpcDefinition rpcDefinition) Publish the named procedure to all known remote contexts.
boolean	publishRpcs(Class<?> definition, Object handler) Allows application code to remotely enable all methods in a handler object that are implementations of methods in an interface definition.
void	queueEvent(IEvent event) Add the event to a queue for distribution to registered IEventListener instances for the event's IEventSource.
void	queueEvents(Collection<IEvent> events) Bulk operation for queueing events.
boolean	removeContainer(IContainer container) Remove a container from the context.
boolean	removeRpcPublicationListener(String remoteContextIdentity, IRpcPublicationListener listener) Remove an RPC publication listener.
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.
void	schedule(TimerTask task, long delay, long period) Schedule a timer task to be executed by a single worker thread.
void	setConnectionBroker(IConnectionBroker broker) Set the connection broker for the context.
void	setConnectionDiscoverer(IConnectionDiscoverer discoverer) Set the discover for the context.
void	setContextWatchdog(IContextWatchdog watchdog) Set the component that will report on the state of this context
void	setDistributionManager(IDistributionManager distributionManager) Provide a different implementation of the distribution manager.
void	setNetwork(INetwork network) Set the INetwork for the context.
void	setPermissionProfile(IPermissionProfile profile) Set the permission profile for the context.
void	setRemoteUpdateHandler(IRemoteUpdateHandler handler) Set the object that will handle updates to local records from remote contexts via RPC calls.
protected void	standby() Invoked by the Standby state and encapsulates the logic the FTContext needs to perform to go into standby state.
boolean	subscribe(String contextIdentity, String identityRegularExpression, 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.
String	toString()
boolean	unpublishProdedure(IRpcDefinition rpcDefinition) Unpublish the procedure from all connected remote contexts.
boolean	unpublishRpcs(Class<?> definition, Object handler) Allows application code to remove any previously remotely enabled methods published via IRpcPublishOperations.publishRpcs(Class, Object)
boolean	unsubscribe(String contextIdentity, String identityRegularExpression, 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

Methods inherited from class java.lang.Object

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

Methods inherited from interface fulmine.context.IFulmineContext

start

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Field Detail

HEARTBEAT_MULTIPLIER

public static final long HEARTBEAT_MULTIPLIER

The number of heartbeats that the FTContext activation period should be.

See Also:

Constant Field Values

Constructor Detail

FTContext

public FTContext(IFrameworkContext appContext,
                 IFTContextStateListener stateListener,
                 INetwork ftNetwork,
                 int number,
                 long activationDelayMillis)

Standard constructor for an FT context that provides FT capability to a hosted application context.

Parameters:

appContext - the application context instance that is hosted by the clustering ability of this FT context. The FT cluster identity comes from the IFulmineContext.getIdentity() of the context argument.

stateListener - the listener that will react to the FT context being active or stand-by

ftNetwork - the network that is used for FT activities; other FTContexts joining the same network will coordinate between themselves to identify which one should be the active context

number - the FT number for the context within the cluster; determines relative priority for becoming active between all peer FT contexts within the same cluster

activationDelayMillis - the delay to wait between start and provisional activation states. This provides time for other FT context instances to be discovered prior to entering the ProvisionalActive state. The value must be at least equal to the ftNetwork's heartbeat period multiplied by HEARTBEAT_MULTIPLIER. Choosing a number too low can result in newly started contexts assuming confirmed active state before detecting any other confirmed active instances.

Method Detail

getContextWatchdog

public IContextWatchdog getContextWatchdog()

Description copied from interface: IFrameworkContext

Get the component that will report on the state of this context

Specified by:

getContextWatchdog in interface IFrameworkContext

Returns:

a component that can report on the state of this context

setContextWatchdog

public void setContextWatchdog(IContextWatchdog watchdog)

Description copied from interface: IFulmineContext

Set the component that will report on the state of this context

Specified by:

setContextWatchdog in interface IFulmineContext

Parameters:

watchdog - a component that can report on the state of this context

doStart

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

prepareAppContextForStart

protected void prepareAppContextForStart()

Prepare the application context before calling start. Default implementation sets the application context network into listen-only mode.

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

standby

protected void standby()

Invoked by the Standby state and encapsulates the logic the FTContext needs to perform to go into standby state.

doStandby

protected final void doStandby(IFrameworkContext context,
                               INetwork network,
                               IConnectionDiscoverer discoverer,
                               IConnectionBroker connectionBroker)

Standard operation for standby that stops heartbeat pulsing and recreates the IConnectionBroker

Parameters:

context - the context for the connection broker

network - the network instance for the new connection broker

discoverer - the discoverer to stop heartbeats for

connectionBroker - the connection broker to stop

activate

protected void activate()

Invoked by the Confirmed state and encapsulates the logic the FTContext needs to perform to go into the active state.

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

getAppContext

protected IFrameworkContext getAppContext()

Returns:

the application context this FTContext hosts

isFTContextActive

public boolean isFTContextActive()

Determine if this FT context is active. This examines the confirmed active state.

Returns:

true if this FT context is active

See Also:

setFTContextState(String, boolean)

addContainer

public void addContainer(IContainer container)

Description copied from interface: IModelManager

Add a container to this context.

Specified by:

addContainer in interface IModelManager

Parameters:

container - the container to add to this context

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

containsLocalContainer

public boolean containsLocalContainer(String identityRegularExpression,
                                      IType type,
                                      IDomain domain)

Description copied from interface: IModelManager

Identify if the local container exists in this context

Specified by:

containsLocalContainer in interface IModelManager

type - the type of the container to find

domain - the domain of the container

Returns:

true if the local container exists

containsRemoteContainer

public boolean containsRemoteContainer(String remoteContextIdentity,
                                       String containerIdentity,
                                       IType type,
                                       IDomain domain)

Description copied from interface: IModelManager

Identify if the remote container exists in this context

Specified by:

containsRemoteContainer in interface IModelManager

Parameters:

remoteContextIdentity - the identity of the remote context where the remote container originated from

type - the type of the container to find

domain - the domain of the container

Returns:

true if the remote container exists

execute

public void execute(Runnable task)

Description copied from interface: IEventManager

Add the task to a queue to be executed by a single worker thread. This is provided as a utility to execute a "one-shot" asynchronous task.

Specified by:

execute in interface IEventManager

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

getConnectionBroker

public IConnectionBroker getConnectionBroker()

Description copied from interface: IFrameworkContext

Get the connection broker for the context.

Specified by:

getConnectionBroker in interface IFrameworkContext

Returns:

the broker for this context, null if there is no broker in the context

See Also:

IFrameworkContext.setConnectionBroker(IConnectionBroker)

getConnectionDiscoverer

public IConnectionDiscoverer getConnectionDiscoverer()

Description copied from interface: IFrameworkContext

Get the connection discoverer in use by this context.

Specified by:

getConnectionDiscoverer in interface IFrameworkContext

Returns:

the connection discoverer in use, null if there is not one allocated.

getContainerFactory

public IContainerFactory getContainerFactory()

Description copied from interface: IModelManager

Get the container factory for the context. This factory is bound to this context.

Specified by:

getContainerFactory in interface IModelManager

Returns:

the container factory for the context

getContextHashCode

public int getContextHashCode()

Description copied from interface: IFulmineContext

Get a unique integer for this context. This must be completely unique across all distributed context instances in the network, regardless of the context identity. This integer can be used to uniquely identify this context instance within the network.

Specified by:

getContextHashCode in interface IFulmineContext

Returns:

a unique integer for the context

getEventProcessorCount

public int getEventProcessorCount()

Description copied from interface: IEventManager

Get the number of EventProcessor instances in this context

Specified by:

getEventProcessorCount in interface IEventManager

Returns:

the number of event processors in this context

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

getIdentity

public String getIdentity()

Description copied from interface: IFulmineContext

Get the unique identity of this context. In a network of contexts, the identity must by unique.

Specified by:

getIdentity in interface IFulmineContext

Returns:

the identity for this context

getLocalContainer

public IContainer getLocalContainer(String identity,
                                    IType type,
                                    IDomain domain)

Description copied from interface: IModelManager

Get the identified local container. This container is native to this context. If it does not exist, it is created using the ContainerFactory.

If the ContainerFactory does not have a IContainerFactory.IContainerBuilder registered for the type argument, a standard container is created.

This operation does not support any wildcards for the attributes (it does not have the same contract for the identity, type and domain as IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener) .

Specified by:

getLocalContainer in interface IModelManager

Parameters:

identity - the identity of the local container

type - the type of the local container

domain - the domain of the local container

Returns:

a IContainer native to this context and hosted in this context

getLocalContainers

public Collection<IContainer> getLocalContainers()

Description copied from interface: IModelManager

Get a copy of the collection of local containers in this context.

Specified by:

getLocalContainers in interface IModelManager

Returns:

a copy of the collection of all the local containers in this context

getNetwork

public INetwork getNetwork()

Description copied from interface: IFrameworkContext

Get the network

Specified by:

getNetwork in interface IFrameworkContext

Returns:

the network for this context

getEventProcessorThreadGroup

public ThreadGroup getEventProcessorThreadGroup()

Description copied from interface: IEventManager

Get the ThreadGroup for the event processors.

Specified by:

getEventProcessorThreadGroup in interface IEventManager

Returns:

the thread group for the event processors

getRemoteContainer

public IContainer getRemoteContainer(String remoteContextIdentity,
                                     String containerIdentity,
                                     IType type,
                                     IDomain domain)

Description copied from interface: IModelManager

Get the identified remote container. This container is not native to this context. If it does not exist, it is created using the ContainerFactory and its state is set to be IContainer#STALE until it receives an update.

This method just creates the 'proxy shell' for the remote events to be applied to. Use the IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener) method to start receiving events for the container.

This operation does not support any wildcards for the attributes (it does not have the same contract for the identity, type and domain as IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener) .

Specified by:

getRemoteContainer in interface IModelManager

Parameters:

remoteContextIdentity - the identity of the remote context where the remote container originates from - this is only required if the remote container will be created. Use IModelManager.containsRemoteContainer(String, String, IType, IDomain) to determine if the remote container exists.

type - the type of the remote container

domain - the domain of the remote container

Returns:

a IContainer native to the specified remote context and hosted in this context

getRemoteContainers

public Collection<IContainer> getRemoteContainers(String remoteContextIdentity)

Description copied from interface: IModelManager

Get a copy of the collection of remote containers in this context.

Specified by:

getRemoteContainers in interface IModelManager

Parameters:

remoteContextIdentity - the remote context identity that the remote containers originated from

Returns:

a copy of the collection of all the remote containers in this context

getSystemEventSource

public ISystemEventSource getSystemEventSource(Class<? extends ISystemEvent> type)

Description copied from interface: IEventManager

Get an ISystemEventSource that is used to propagate a single specific type of ISystemEvent. The system event source will be created on the first invocation. The system event source is associated with the zeroth EventProcessor.

Specified by:

getSystemEventSource in interface IEventManager

Parameters:

type - the type of the system events the system event source generates

Returns:

the ISystemEventSource for the type of system event

queueEvent

public void queueEvent(IEvent event)

Description copied from interface: IEventManager

Add the event to a queue for distribution to registered IEventListener instances for the event's IEventSource.

Specified by:

queueEvent in interface IEventManager

Parameters:

event - the event to queue

queueEvents

public void queueEvents(Collection<IEvent> events)

Description copied from interface: IEventManager

Bulk operation for queueing events.

Specified by:

queueEvents in interface IEventManager

See Also:

IEventManager.queueEvent(IEvent)

removeContainer

public boolean removeContainer(IContainer container)

Description copied from interface: IModelManager

Remove a container from the context. This does not destroy the container but may leave the container with no references to it and thus it may be garbage collected.

Specified by:

removeContainer in interface IModelManager

Parameters:

container - the container to remove

Returns:

true if the container was removed, false if the container was not found

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

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

setConnectionBroker

public void setConnectionBroker(IConnectionBroker broker)

Description copied from interface: IFrameworkContext

Set the connection broker for the context. This allows the context to create connections to remote contexts. This must be called before IFulmineContext.start().

Specified by:

setConnectionBroker in interface IFrameworkContext

Parameters:

broker - the broker to use to create connections to remote contexts

setConnectionDiscoverer

public void setConnectionDiscoverer(IConnectionDiscoverer discoverer)

Description copied from interface: IFrameworkContext

Set the discover for the context. This allows the context to discover connections to remote contexts. This must be called before IFulmineContext.start().

Specified by:

setConnectionDiscoverer in interface IFrameworkContext

Parameters:

discoverer - the discoverer to use to find connections to other remote contexts

setDistributionManager

public void setDistributionManager(IDistributionManager distributionManager)

Description copied from interface: IFrameworkContext

Provide a different implementation of the distribution manager.

Specified by:

setDistributionManager in interface IFrameworkContext

Parameters:

distributionManager - the distribution manager to use

getDistributionManager

public IDistributionManager getDistributionManager()

Description copied from interface: IFrameworkContext

Get the distribution manager assigned to the context

Specified by:

getDistributionManager in interface IFrameworkContext

Returns:

the distribution manager assigned to this context

setNetwork

public void setNetwork(INetwork network)

Description copied from interface: IFulmineContext

Set the INetwork for the context. This allows the context to communicate with other contexts that use the same network transport. This must be called before IFulmineContext.start().

Specified by:

setNetwork in interface IFulmineContext

Parameters:

network - the network

subscribe

public boolean subscribe(String contextIdentity,
                         String identityRegularExpression,
                         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

identityRegularExpression - 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 identityRegularExpression,
                           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

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

getEventProcessorIdentityPrefix

public String getEventProcessorIdentityPrefix()

Description copied from interface: IFrameworkContext

Get the event processor identity prefix. This appears as the prefix for all event processor threads in this context.

Specified by:

getEventProcessorIdentityPrefix in interface IFrameworkContext

Returns:

the event processor identity prefix

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

addRpcPublicationListener

public boolean addRpcPublicationListener(String remoteContextIdentity,
                                         IRpcPublicationListener listener)

Description copied from interface: IRpcManager

Add a listener for RPC publication events. This will be activated when an RPC publication event is received from any connected remote context.

This is an idempotent operation.

Specified by:

addRpcPublicationListener in interface IRpcManager

Parameters:

remoteContextIdentity - the remote context to monitor for RPC publish/unpublish events

listener - a listener to receive the RPC publish/unpublish events.

Returns:

true if the listener was added, false otherwise

unpublishRpcs

public boolean unpublishRpcs(Class<?> definition,
                             Object handler)

Description copied from interface: IRpcPublishOperations

Allows application code to remove any previously remotely enabled methods published via IRpcPublishOperations.publishRpcs(Class, Object)

Specified by:

unpublishRpcs in interface IRpcPublishOperations

Parameters:

definition - an interface that defines all the methods in the handler that should be remotely disabled. This includes all methods in the super-interfaces, if any.

handler - the object that implements the methods declared in the definition interface. These methods will no longer be available for remote invocation.

Returns:

true if all methods were successfully unpublished

publishRpcs

public boolean publishRpcs(Class<?> definition,
                           Object handler)

Description copied from interface: IRpcPublishOperations

Allows application code to remotely enable all methods in a handler object that are implementations of methods in an interface definition. This essentially publishes these methods as RPCs for other contexts to invoke.

There are some caveats to methods that can be remotely enabled; the method arguments and return types must be scalar and only the following types are supported:

• integer
• long
• float
• double
• boolean
• String

This is a convenience method in-lieu of calling IRpcPublishOperations.publishProdedure(IRpcHandler, IRpcDefinition).

Specified by:

publishRpcs in interface IRpcPublishOperations

Parameters:

definition - an interface that defines all the methods in the handler that should be remotely enabled. This includes all methods in the super-interfaces, if any.

handler - the object that implements the methods declared in the definition interface. The handler does not necessarily have to be an instance of the interface (i.e. does not need to explicitly implement the interface, it only needs to implement all the methods). All remote invocations of these methods will be handled by this object. The remotely enabled methods must be thread safe.

Returns:

true if all methods were successfully published

invoke

public IRpcResult invoke(String remoteContextIdentity,
                         String procedure,
                         IField... args)

Description copied from interface: IRpcManager

Synchronously invoke the RPC in the named remote context. This method will block until a result is returned or a timeout occurs.

It is assumed that this method is called after an RPC publication event is received by an IRpcPublicationListener.

Specified by:

invoke in interface IRpcManager

Parameters:

remoteContextIdentity - the remote context to invoke the RPC in

procedure - the RPC name

args - the arguments for the RPC

Returns:

the result from the RPC

See Also:

IRpcManager.RPC_TIMEOUT

invoke

public IRpcMarker invoke(IRpcResultHandler resultHandler,
                         String remoteContextIdentity,
                         String procedure,
                         IField... args)

Description copied from interface: IRpcManager

Asynchronously invoke the RPC in the named remote context. It is assumed that this method is called after an RPC publication event is received by an IRpcPublicationListener

Specified by:

invoke in interface IRpcManager

Parameters:

resultHandler - the handler to process the asynchronous result

remoteContextIdentity - the remote context to invoke the RPC in

procedure - the RPC name

args - the arguments for the RPC

Returns:

a marker that allows the resultHandler to tie up the result from this specific RPC invocation

removeRpcPublicationListener

public boolean removeRpcPublicationListener(String remoteContextIdentity,
                                            IRpcPublicationListener listener)

Description copied from interface: IRpcManager

Remove an RPC publication listener. The listener will no longer receive notifications when RPC publish/unpublish events occur. *

This is an idempotent operation.

Specified by:

removeRpcPublicationListener in interface IRpcManager

Parameters:

remoteContextIdentity - the remote context that the listener was monitoring for RPC publish/unpublish events

listener - the listener to remove

Returns:

true if the listener was found and removed, false otherwise

publishProdedure

public boolean publishProdedure(IRpcHandler handler,
                                IRpcDefinition rpcDefinition)

Description copied from interface: IRpcPublishOperations

Publish the named procedure to all known remote contexts.

There can only be one handler per procedure instance. Different handlers can be used for overloaded procedures. RPC definitions cannot overload the result type, if this method is called with a definition that attempts to overload the result type, the operation is ignored and no publish happens.

After this method has completed, remote contexts will be able to invoke the RPC.

Specified by:

publishProdedure in interface IRpcPublishOperations

Parameters:

handler - the object that will handle any RPC invocations for this RPC definition. This object must be thread safe.

rpcDefinition - the RPC definition

Returns:

true if the procedure was published, false if has already been published

unpublishProdedure

public boolean unpublishProdedure(IRpcDefinition rpcDefinition)

Description copied from interface: IRpcPublishOperations

Unpublish the procedure from all connected remote contexts.

Specified by:

unpublishProdedure in interface IRpcPublishOperations

Parameters:

rpcDefinition - the RPC definition to unpublish

Returns:

true if the procedure was unpublished

getPermissionProfile

public IPermissionProfile getPermissionProfile()

Description copied from interface: IFulmineContext

Get the permission profile for the context. This defines all the IFields that this context is allowed to view. If a profile has not been set by application code, a default one should be provided.

Specified by:

getPermissionProfile in interface IFulmineContext

Returns:

the permission profile for this context

setPermissionProfile

public void setPermissionProfile(IPermissionProfile profile)

Description copied from interface: IFulmineContext

Set the permission profile for the context. This will define all the IFields that this context will be allowed to view.

Specified by:

setPermissionProfile in interface IFulmineContext

Parameters:

profile - the permission profile

setRemoteUpdateHandler

public void setRemoteUpdateHandler(IRemoteUpdateHandler handler)

Description copied from interface: IFulmineContext

Set the object that will handle updates to local records from remote contexts via RPC calls. By default a vetoing updater is used that prevents remote contexts from updating local records via RPC calls.

Specified by:

setRemoteUpdateHandler in interface IFulmineContext

Parameters:

handler - the handler to use

See Also:

IDistributionManager.updateRemoteContainer(String, String, IType, IDomain, String, String)

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)

getSystemInfo

public IContainer getSystemInfo()

Description copied from interface: IFrameworkContext

Get the 'system info' record that is used to encapsulate any system level information about the context. This is typically used by remote subscribers to inspect the state of the context.

Bespoke attributes can be attached to this record by application code.

Specified by:

getSystemInfo in interface IFrameworkContext

schedule

public void schedule(TimerTask task,
                     long delay,
                     long period)

Description copied from interface: IEventManager

Schedule a timer task to be executed by a single worker thread.

Specified by:

schedule in interface IEventManager

Parameters:

task - task to be scheduled.

delay - delay in milliseconds before task is to be executed.

period - time in milliseconds between successive task executions.