fulmine.distribution
Interface IDistributionManager

All Superinterfaces:

IDestroyable, ILifeCycle, IRetransmissionManager, IRpcTransmissionManager

All Known Subinterfaces:

IFrameworkContext, IFulmineContext

All Known Implementing Classes:

FTContext, FTDistributionManager, FulmineContext

public interface IDistributionManager
extends ILifeCycle, IRetransmissionManager, IRpcTransmissionManager

Manages subscriptions for distribution of events within the local context and from remote contexts. Application code uses the subscribe method to receive distribution of events from both local and remote IContainer instances.

Author:

Ramon Servadei

See Also:

IFrameworkContext

Method Summary

boolean	addSubscriptionListener(ISubscriptionListener listener) Add a container subscription listener.
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
boolean	removeSubscriptionListener(ISubscriptionListener listener) Remove a container subscription listener.
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.
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 interface fulmine.ILifeCycle

isActive, start

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

Method Detail

subscribe

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

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:

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

unsubscribe

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.

The subscribe(String, String, IType, IDomain, IEventListener) method is idempotent so if it is called multiple times with the same arguments, one call to 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.

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:

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

addSubscriptionListener

boolean addSubscriptionListener(ISubscriptionListener listener)

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.

Parameters:

listener - a listener to add to an internal list.

Returns:

true if the listener was added, false otherwise

removeSubscriptionListener

boolean removeSubscriptionListener(ISubscriptionListener listener)

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

Parameters:

listener - the listener to remove

Returns:

true if the listener was found and removed, false otherwise

getFrameWriter

IFrameWriter getFrameWriter()

Get the frame writer for this context

Returns:

the IFrameWriter for this context

getFrameReader

IFrameReader getFrameReader()

Get the frame reader for this context

Returns:

the IFrameReader for this context

getConnectedChannels

IChannel[] getConnectedChannels()

Get all the currently connected channels

Returns:

an array of the currently connected IChannel instances

updateRemoteContainer

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

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)