fulmine.context
Interface IFulmineContext

All Superinterfaces:

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

All Known Subinterfaces:

IFrameworkContext

All Known Implementing Classes:

FTContext, FulmineContext

public interface IFulmineContext
extends ILifeCycle, IModelManager, IEventManager, IDistributionManager, IRpcManager

This is the application context for fulmine, a distributed data model system (DDMS). Application code uses a context to interact with the data model, event and distribution framework.

Data model framework

The data model is composed of IContainer objects. These represent the data entities that the context manages. The context keeps track of all containers created in this context. Containers created in the context are keyed against their type and identity. Changes to the containers can be observed using the event and distribution framework (see next sections).

There are 2 types of container in the context; local and remote. A local container is an instance that is created by local user code; the container is native to this context. Local containers are created via IModelManager.getLocalContainer(String, IType, IDomain). A remote container is a 'proxy' to a local container that is native to a remote context. Any attempt by user code to alter a remote container's state will generate an exception. A remote container is created by accessing the IModelManager.getRemoteContainer(String, String, IType, IDomain) method.

Containers have a unidirectional distributed state; only changes in a local container are distributed to remote container instances. Remote containers are, to all intents and purposes, read-only in the local context.

Event framework

The event framework is based on IEventListener instances registered against IEventSource instances. The listeners receive the events generated by the sources they are registered for. This is all in a single process.

A key design principle is that an event source has an associated 'event processor' thread that never changes. The processor is mapped to the event source's type (see IAddressable.getType()). An event processor thread may service multiple sources of different types. All listeners registered against a source will be activated by the same thread when events are being notified. This does not mean the listener is inherently thread safe; if it is registered against 2 sources of 2 different types, there might be 2 threads activating the listener. The only rule is that the same thread activates the listener when notifying it with an event from the source the thread is associated with.

The events framework is accessed via the following methods:

• IEventManager.queueEvent(IEvent) to notify a listener with an event from a
• IDistributionManager.subscribe(String, String, IType, IDomain, IEventListener) to register a listener for events from a source in a context

The event framework can be used as an event distribution mechanism as demonstrated by the following code snippet.

 // create the context
 IFulmineContext context = new FulmineContext("context name");
 context.start();
 
 IEventListener listener = new CustomListener();
 // subscribe for an event source
 context.subscribe("context name", "foobar", Type.get(99), Domain.get(12),
     listener);
 
 // get the event source so we can trigger a change (a container is an event source)
 IEventSource container =
     context.getLocalContainer("foobar", Type.get(99), Domain.get(12));
 // generate an event from the event source
 // note that CustomEvent extends AbstractEvent...
 IEvent event = new CustomEvent(container);
 context.queueEvent(event);
 // the listener will receive the event in a separate thread - one of the context's event processors
 

The data model framework interacts directly with the event framework and allows user code to receive events from the data model. Containers effectively raise events that encapsulate the latest change. The event will be a clone of the container so listeners are not interacting with the actual container. The following code snippet shows how to use the event framework to listen for data model changes.

 // create the context
 IFulmineContext context = new FulmineContext("context name");
 context.start();
 
 IEventListener listener = new CustomListener();
 // subscribe for the container
 context.subscribe("context name", "foobar", Type.get(99), Domain.get(12),
     listener);
 
 // get an event source (a container is an event source)
 IEventSource container =
     context.getLocalContainer("foobar", Type.get(99), Domain.get(12));
 // alter the container 
 IntegerField field = new IntegerField("an integer component");
 field.set(1);
 container.add(field);
 container.flushFrame();
 // the listener will receive a clone of the container that has the field added
 

Distribution framework

Out-of-process event distribution is only available for data model changes (this was designed primarily as a distributed data model system). It requires collaborating objects:

• IConnectionDiscoverer - to find other remote contexts
• IConnectionBroker - to create a connection to the remote context

The context must have these injected via the setter methods prior to being started. Once started with the connection collaborators, the context is remotely available and can receive data model changes to remote containers. It can also distribute local container changes to remote contexts. The distribution is achieved by a local context subscribing for a remote container in a remote context, as demonstrated below

 IEventListener listener = new CustomListener();
 // subscribe for the remote container from the remote context
 // it is assumed that the remote context exists in this example 
 context.subscribe("a remote context", "foobar", Type.get(99), Domain.get(12),
     listener);
 // the listener will now receive changes from the remote container
 

Updating remote containers

A context can update a remote container only by invoking the IDistributionManager.updateRemoteContainer(String, String, IType, IDomain, String, String) method. However, by default, a context will veto any attempt by a remote context to update one of its local containers. To override this, application code needs to provide a IRemoteUpdateHandler via the setRemoteUpdateHandler(IRemoteUpdateHandler) method. The permission profile of the updating context is passed to the remote context during the operation; if the permissions of the updating context are not compatible with the field being updated, the operation will fail. The IDistributionManager.updateRemoteContainer(String, String, IType, IDomain, String, String) method is in fact an RPC. RPC and permissions are described in the following sections.

RPC framework

Remote procedures can be invoked on remote contexts. In the remote context, application code must first register a procedure with the context. After this, the procedure is published to any contexts that have subscribed for registered RPCs.

The arguments for any RPC are limited to the 'native' types; IntegerField, StringField, LongField, DoubleField, FloatField, BooleanField. The return type for an RPC is also limited to the above types. The 'void' return type is not supported.

See RpcManager for a more detailed description of the RPC fundamentals. The following code snippet demonstrates invoking a RPC:

 // local context registers for RPCs from the remote context
 context.addRpcPublicationListener(remoteContextIdentity, listener);
 
 // ... assume an RPC has been picked up by the publication listener
 // the RPC signature published is 'boolean helloWorld(String name)'
 // note that the name of the StringField (or any args during the 
 // invocation) are purely arbitrary
 context.invoke(remoteContextIdentity, "helloWorld", new StringField("name",
     "lasers"));
 

Permissions

All data fields of a container include a permission profile. This allows the context to control visibility of the data for other remote contexts. Further information on the permissions is described in IPermissionProfile.

Author:

Ramon Servadei

Field Summary

static String

NAME

Fields inherited from interface fulmine.rpc.IRpcManager

DEFAULT_RPC_TIMEOUT, RPC_TIMEOUT

Method Summary

int	getContextHashCode() Get a unique integer for this context.
String	getIdentity() Get the unique identity of this context.
IPermissionProfile	getPermissionProfile() Get the permission profile for the context.
void	setContextWatchdog(IContextWatchdog watchdog) Set the component that will report on the state of this context
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.
void	start() Start the context.

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.model.IModelManager

addContainer, containsLocalContainer, containsRemoteContainer, getContainerFactory, getLocalContainer, getLocalContainers, getRemoteContainer, getRemoteContainers, removeContainer

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.event.IEventManager

execute, getEventProcessorCount, getEventProcessorThreadGroup, getSystemEventSource, queueEvent, queueEvents, schedule

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.distribution.IDistributionManager

addSubscriptionListener, getConnectedChannels, getFrameReader, getFrameWriter, removeSubscriptionListener, subscribe, unsubscribe, updateRemoteContainer

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.distribution.IRetransmissionManager

requestRetransmit, requestRetransmitAll, retransmit, retransmitAll, retransmitAllToAll, retransmitToAll

Methods inherited from interface fulmine.rpc.IRpcTransmissionManager

invokeRpc

Methods inherited from interface fulmine.rpc.IRpcManager

addRpcPublicationListener, invoke, invoke, removeRpcPublicationListener

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.rpc.IRpcPublishOperations

publishProdedure, publishRpcs, unpublishProdedure, unpublishRpcs

Field Detail

NAME

static final String NAME

See Also:

Constant Field Values

Method Detail

start

void start()

Start the context. The context becomes active and usable after this method completes. If a IConnectionBroker and IConnectionDiscoverer have been provided via the relevant setter methods, this context becomes remotely available.

Specified by:

start in interface ILifeCycle

setNetwork

void setNetwork(INetwork network)

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 start().

Parameters:

network - the network

setContextWatchdog

void setContextWatchdog(IContextWatchdog watchdog)

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

Parameters:

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

setPermissionProfile

void setPermissionProfile(IPermissionProfile profile)

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

Parameters:

profile - the permission profile

getPermissionProfile

IPermissionProfile getPermissionProfile()

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.

Returns:

the permission profile for this context

getIdentity

String getIdentity()

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

Returns:

the identity for this context

getContextHashCode

int getContextHashCode()

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.

Returns:

a unique integer for the context

setRemoteUpdateHandler

void setRemoteUpdateHandler(IRemoteUpdateHandler handler)

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.

Parameters:

handler - the handler to use

See Also:

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