fulmine.model.container
Class AbstractContainer

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.model.component.AbstractComponent
          fulmine.model.container.AbstractContainer

All Implemented Interfaces:

IEvent, IEventFrame, IEventSource, IAddressable, IDescriptor, IDestroyable, ILifeCycle, IComponent, IContainer, IRemoteSubscribable, IWireState, Cloneable

Direct Known Subclasses:

AbstractEventProcessingContainer

public abstract class AbstractContainer
extends AbstractComponent
implements IContainer, Cloneable

The base class for containers.

This implementation is thread safe. The the add(IField) and remove(IField) methods perform copy-on-write operations. The Collection for the fields uses the 'cheap read-write lock'

This implementation can read and write itself from and to a wire frame. However, when writing, it writes a complete image of itself (i.e. all its internal IField objects are written, regardless of any changes that have occurred). Sub-classes may override this to in a more efficient mechanism that only writes changed internal fields (deltas).

Author:

Ramon Servadei

Nested Class Summary

protected class

AbstractContainer.ReaderTask The reader task executed by the FieldReader when reading messages

Nested classes/interfaces inherited from interface fulmine.model.container.IContainer

IContainer.DataState

Constructor Summary

AbstractContainer(String nativeContextIdentity, String identity, IType type, IDomain domain, IFrameworkContext hostContext, boolean local)
Standard constructor.

Method Summary

void	add(IField field) Add the field to this container.
protected void	afterAdd(IField field) Called after the field is added and the copy-on-write operation has completed.
protected void	afterRemove(IField field, IField removed) Called after the field is removed and the copy-on-write operation has completed.
protected void	beforeAdd(IField field) Called before the field is added.
protected void	beforeRemove(IField field) Called before the field is removed.
void	beginFrame(IEventFrameExecution frame) An event frame life-cycle control method to start an event frame.
Object	clone() Clone this.
boolean	contains(String key) Determines if there is an IField instance with an identity equal to the key argument.
protected void	doCommitEvents() Perform the operation to commit all events
protected void	doComponentDestroy() The destroy method that is invoked on a non-cloned version of this.
protected void	doPostAddListener(IEventListener listener) Hook to allow sub-classes to perform any post processing after an IEventListener has been added via AbstractComponent.addListener(IEventListener)
protected void	doPostRemoveListener(IEventListener listener) Hook to allow sub-classes to perform any post processing after an IEventListener has been removed via AbstractComponent.removeListener(IEventListener)
protected boolean	doReadState(IOperationScope scope, byte[] buffer, int start, int numberOfBytes) Update the component state from the wire format state in the buffer.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
protected void	doStateChangeOp(IContainer.DataState oldState) Perform the operation when the dataState changes.
protected boolean	doWriteState(IOperationScope scope, IWireIdentity wireId, byte[][] headerBuffer, int[] headerBufferPosition, byte[][] dataBuffer, int[] dataBufferPosition, boolean completeState) Write the component state in its wire form to the buffer.
void	endFrame() An event frame life-cycle control method to commit all events within an event frame.
boolean	equals(Object obj)
void	flushFrame() A convenience method to perform the event frame life-cycle methods at once.
<T extends IField> T	get(String identity) Find the field in the container with the identity equal to the string argument.
BooleanField	getBooleanField(String identity) Get the BooleanField identified by the identity
String[]	getComponentIdentities() Get all the identities of the fields in this container.
IFrameworkContext	getContext() Get the host context for the container instance.
IContainer.DataState	getDataState() Get the container's data state.
protected IContainerDefinitionField	getDefinition() Get the definition for this container.
DoubleField	getDoubleField(String identity) Get the DoubleField identified by the identity
protected Map<String,IField>	getFields()
protected Collection<IField>	getFieldsToWrite(boolean completeState) Get the fields to write to a frame.
FloatField	getFloatField(String identity) Get the FloatField identified by the identity
protected ThreadLocal<IEventFrameExecution>	getFrameIdentifier()
IntegerField	getIntegerField(String identity) Get the IntegerField identified by the identity
protected AsyncLog	getLog() Get the log to use for the object hierarchy
LongField	getLongField(String identity) Get the LongField identified by the identity
String	getNativeContextIdentity() Get the identity of the context this container is native to; this is its local context identity.
int	getRemoteSubscriptionCount() Get the number of remote subscriptions this.
StringField	getStringField(String identity) Get the StringField identified by the identity
int	hashCode()
boolean	isDynamic() Identify if the container is dynamic or static.
boolean	isEmpty() Determines if this container empty.
protected boolean	isEventFrameThread() Is the executing thread the event frame thread.
boolean	isFrameActive() Identifies if an event frame is currently active.
boolean	isLocal() Is the container local to the host context returned by IContainer.getContext()
boolean	isRemote()
protected void	lockFrame() Lock the event frame.
protected void	logNotTheEventFrameThread() Logs an exception and the current event frame thread.
int	markForRemoteSubscription() Mark this for remote subscription.
protected AbstractContainer.ReaderTask	newReaderTask() Get the reader task to use during the doReadState(IOperationScope, byte[], int, int) method.
<T extends IField> T	remove(T field) Remove the field from this container.
void	setState(IContainer.DataState stateCode) Set the container state.
int	size() Determine the number of IField instances held in this container
String	toDetailedString() Provides a formatted string describing this object in detail.
String	toString()
int	unmarkForRemoteSubscription() Unmark this from remote subscriptions.

Methods inherited from class fulmine.model.component.AbstractComponent

addEvent, addListener, checkClone, createIdentityString, doDestroy, getAddress, getAddressable, getDomain, getDrivingFrame, getEventSourceGroupId, getFrame, getIdentity, getIdentityString, getListeners, getSource, getTriggerEvent, getType, isClone, readState, removeListener, removeListeners, setDrivingFrame, setFrame, setTriggerEvent, toIdentityString, writeState

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, isActive, start

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface fulmine.model.container.IContainer

destroy, getType, isClone, start

Methods inherited from interface fulmine.protocol.wire.IWireState

readState, writeState

Methods inherited from interface fulmine.event.IEventSource

addEvent, addListener, getEventSourceGroupId, getListeners, removeListener, removeListeners

Methods inherited from interface fulmine.IDescriptor

toIdentityString

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity

Methods inherited from interface fulmine.event.IEvent

getDrivingFrame, getFrame, getSource, getTriggerEvent, setTriggerEvent

Methods inherited from interface fulmine.IDescriptor

toIdentityString

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity

Methods inherited from interface fulmine.event.IEventFrame

addEvent

Constructor Detail

AbstractContainer

public AbstractContainer(String nativeContextIdentity,
                         String identity,
                         IType type,
                         IDomain domain,
                         IFrameworkContext hostContext,
                         boolean local)

Standard constructor. The container is marked as LIVE. If a EventThread is constructing this then the container is a remote container.

Parameters:

nativeContextIdentity - the name of the context this container is native to - the name of its local context

identity - the identity of the container

type - the type of the container

domain - the domain for the container

hostContext - the context hosting this container instance

local - true the container is local to this context

See Also:

ContainerFactory

Method Detail

getLog

protected AsyncLog getLog()

Description copied from class: AbstractLifeCycle

Get the log to use for the object hierarchy

Overrides:

getLog in class AbstractComponent

Returns:

the log to use for the object hierarchy

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.

Overrides:

doStart in class AbstractComponent

doComponentDestroy

protected void doComponentDestroy()

Description copied from class: AbstractComponent

The destroy method that is invoked on a non-cloned version of this.

Overrides:

doComponentDestroy in class AbstractComponent

isRemote

public final boolean isRemote()

getContext

public final IFrameworkContext getContext()

Description copied from interface: IContainer

Get the host context for the container instance. This may not be the native context for the container.

Specified by:

getContext in interface IContainer

Returns:

the IFrameworkContext hosting this instance

See Also:

IContainer.isLocal(), IContainer.getNativeContextIdentity()

getNativeContextIdentity

public final String getNativeContextIdentity()

Description copied from interface: IContainer

Get the identity of the context this container is native to; this is its local context identity. If this container is local to the host context, this is the same as the identity of IContainer.getContext(). If this container is a remote container, this will return the remote context identity.

Note: this is more for informational purposes, the true mechanism for determining whether a container is local to the host context or not is by checking IContainer.isLocal().

Specified by:

getNativeContextIdentity in interface IContainer

Returns:

the identity of this container's local context

See Also:

IContainer.isLocal(), IContainer.getContext()

add

public final void add(IField field)

Description copied from interface: IContainer

Add the field to this container. Any IEvent events raised by the field will reach this container via its IEventFrame interface.

Specified by:

add in interface IContainer

Parameters:

field - the field to add to this container.

beforeAdd

protected void beforeAdd(IField field)

Called before the field is added. This is called whilst holding the monitor lock for adding/removing fields.

Parameters:

field - the field to add

afterAdd

protected void afterAdd(IField field)

Called after the field is added and the copy-on-write operation has completed. This is called whilst holding the monitor lock for adding/removing fields.

Parameters:

field - the field to add

remove

public final <T extends IField> T remove(T field)

Description copied from interface: IContainer

Remove the field from this container. Any events raised by the field will no longer reach this container.

Specified by:

remove in interface IContainer

Parameters:

field - the field to remove from this container.

Returns:

the removed field

beforeRemove

protected void beforeRemove(IField field)

Called before the field is removed. This is called whilst holding the monitor lock for adding/removing fields.

Parameters:

field - the field to remove

afterRemove

protected void afterRemove(IField field,
                           IField removed)

Called after the field is removed and the copy-on-write operation has completed. This is called whilst holding the monitor lock for adding/removing fields.

Parameters:

field - the field to remove

removed - the field that has been removed - if null then the field was not removed (possibly because it was not in the fields)

isEmpty

public final boolean isEmpty()

Description copied from interface: IContainer

Determines if this container empty.

Specified by:

isEmpty in interface IContainer

Returns:

true if there are no fields in this container.

contains

public final boolean contains(String key)

Description copied from interface: IContainer

Determines if there is an IField instance with an identity equal to the key argument.

Specified by:

contains in interface IContainer

Parameters:

key - the identity of a field to find in this container.

Returns:

true if there is an IField with this identity held in this.

size

public final int size()

Description copied from interface: IContainer

Determine the number of IField instances held in this container

Specified by:

size in interface IContainer

Returns:

the number of IField instances held in this container

get

public final <T extends IField> T get(String identity)

Description copied from interface: IContainer

Find the field in the container with the identity equal to the string argument.

Specified by:

get in interface IContainer

Parameters:

identity - the string identity of the field to find

Returns:

the field in the container with the same identity or null if not found.

getComponentIdentities

public final String[] getComponentIdentities()

Description copied from interface: IContainer

Get all the identities of the fields in this container.

Specified by:

getComponentIdentities in interface IContainer

Returns:

an array of the string identities of all the IField objects in this container.

beginFrame

public final void beginFrame(IEventFrameExecution frame)

Description copied from interface: IEventFrame

An event frame life-cycle control method to start an event frame. The executing thread becomes the event frame thread and is the same thread that must execute the IEventFrame.endFrame() and #end().

If an event frame is already active in another thread, this method blocks until the other frame ends.

Specified by:

beginFrame in interface IEventFrame

Parameters:

frame - the frame identifier

endFrame

public final void endFrame()

Description copied from interface: IEventFrame

An event frame life-cycle control method to commit all events within an event frame. The executing thread must be the event frame thread (i.e. the same thread that started the event frame by executing a previous call to IEventFrame.beginFrame(IEventFrameExecution)).

Specified by:

endFrame in interface IEventFrame

flushFrame

public final void flushFrame()

Description copied from interface: IEventFrame

A convenience method to perform the event frame life-cycle methods at once. This is useful to process programmatically triggering events with one method call. This method will block if a frame is currently active and the executing thread is not the current event frame thread.

Specified by:

flushFrame in interface IEventFrame

isFrameActive

public final boolean isFrameActive()

Description copied from interface: IEventFrame

Identifies if an event frame is currently active. This is useful when determining if a new frame needs to be started or not when triggering events.

Specified by:

isFrameActive in interface IEventFrame

Returns:

true if an event frame is currently active (started)

setState

public final void setState(IContainer.DataState stateCode)

Description copied from interface: IContainer

Set the container state. The state is a logical business state and is not connected to the object lifecycle state. The business state indicates if the data is trustworthy.

Specified by:

setState in interface IContainer

Parameters:

stateCode - the new business state.

See Also:

for a description of the states.

doStateChangeOp

protected void doStateChangeOp(IContainer.DataState oldState)

Perform the operation when the dataState changes.

Parameters:

oldState - the old state

getDataState

public final IContainer.DataState getDataState()

Description copied from interface: IContainer

Get the container's data state. This represents the if the data is being updated and is trustworthy.

Specified by:

getDataState in interface IContainer

Returns:

the current data state

See Also:

DataState for a description of the states.

isDynamic

public boolean isDynamic()

Description copied from interface: IContainer

Identify if the container is dynamic or static. Static container types have an immutable IField population. Dynamic containers have a variable (mutable) population.

Specified by:

isDynamic in interface IContainer

Returns:

true if the definition is dynamic

isLocal

public final boolean isLocal()

Description copied from interface: IContainer

Is the container local to the host context returned by IContainer.getContext()

Specified by:

isLocal in interface IContainer

Returns:

true if the container is local

markForRemoteSubscription

public int markForRemoteSubscription()

Description copied from interface: IRemoteSubscribable

Mark this for remote subscription. This increments a subscription counter.

Specified by:

markForRemoteSubscription in interface IRemoteSubscribable

Returns:

the number of subscriptions for this after the marking operation completes

unmarkForRemoteSubscription

public int unmarkForRemoteSubscription()

Description copied from interface: IRemoteSubscribable

Unmark this from remote subscriptions. This decrements a subscription counter.

Specified by:

unmarkForRemoteSubscription in interface IRemoteSubscribable

Returns:

the number of subscriptions for this after the unmarking operation completes

getRemoteSubscriptionCount

public int getRemoteSubscriptionCount()

Description copied from interface: IRemoteSubscribable

Get the number of remote subscriptions this.

Specified by:

getRemoteSubscriptionCount in interface IRemoteSubscribable

Returns:

the number of remote subscriptions for this

getBooleanField

public BooleanField getBooleanField(String identity)

Get the BooleanField identified by the identity

Specified by:

getBooleanField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the BooleanField for the identity

Throws:

ClassCastException - if the field is not of this type

getStringField

public StringField getStringField(String identity)

Get the StringField identified by the identity

Specified by:

getStringField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the StringField for the identity

Throws:

ClassCastException - if the field is not of this type

getIntegerField

public IntegerField getIntegerField(String identity)

Get the IntegerField identified by the identity

Specified by:

getIntegerField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the IntegerField for the identity

Throws:

ClassCastException - if the field is not of this type

getLongField

public LongField getLongField(String identity)

Get the LongField identified by the identity

Specified by:

getLongField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the LongField for the identity

Throws:

ClassCastException - if the field is not of this type

getFloatField

public FloatField getFloatField(String identity)

Get the FloatField identified by the identity

Specified by:

getFloatField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the FloatField for the identity

Throws:

ClassCastException - if the field is not of this type

getDoubleField

public DoubleField getDoubleField(String identity)

Get the DoubleField identified by the identity

Specified by:

getDoubleField in interface IContainer

Parameters:

identity - the identity of the field to get

Returns:

the DoubleField for the identity

Throws:

ClassCastException - if the field is not of this type

doPostAddListener

protected final void doPostAddListener(IEventListener listener)

Description copied from class: AbstractComponent

Hook to allow sub-classes to perform any post processing after an IEventListener has been added via AbstractComponent.addListener(IEventListener)

Overrides:

doPostAddListener in class AbstractComponent

Parameters:

listener - the listener that has been added

doPostRemoveListener

protected final void doPostRemoveListener(IEventListener listener)

Description copied from class: AbstractComponent

Hook to allow sub-classes to perform any post processing after an IEventListener has been removed via AbstractComponent.removeListener(IEventListener)

Overrides:

doPostRemoveListener in class AbstractComponent

Parameters:

listener - the listener that has been removed

lockFrame

protected final void lockFrame()

Lock the event frame. This sets the eventFrameThread to the current thread. If there already is an event frame thread, this method loops until the frame is unlocked.

See Also:

unlockFrame()

getDefinition

protected IContainerDefinitionField getDefinition()

Get the definition for this container. This effectively provides the 'type' for the this container.

Returns:

the IContainerDefinitionField that defines the IField objects (fields) of this container.

doReadState

protected boolean doReadState(IOperationScope scope,
                              byte[] buffer,
                              int start,
                              int numberOfBytes)
                       throws Exception

Description copied from class: AbstractComponent

Update the component state from the wire format state in the buffer. Any nested fields must be read using their AbstractComponent.readState(IOperationScope, byte[], int, int) method.

Specified by:

doReadState in class AbstractComponent

Returns:

true if the read operation succeded.

Throws:

Exception

See Also:

IWireState.readState(IOperationScope, byte[], int, int)

newReaderTask

protected AbstractContainer.ReaderTask newReaderTask()

Get the reader task to use during the doReadState(IOperationScope, byte[], int, int) method. The reader task is executed for each field spec found during the read state operation. The task implementation is responsible for constructing/reading the IField expressed in the field spec.

Returns:

the AbstractContainer.ReaderTask to invoke for each field spec found during the read state operation.

doWriteState

protected boolean doWriteState(IOperationScope scope,
                               IWireIdentity wireId,
                               byte[][] headerBuffer,
                               int[] headerBufferPosition,
                               byte[][] dataBuffer,
                               int[] dataBufferPosition,
                               boolean completeState)
                        throws Exception

Description copied from class: AbstractComponent

Write the component state in its wire form to the buffer. Any nested fields must be written by calling their AbstractComponent.writeState(IOperationScope, IWireIdentity, byte[][], int[], byte[][], int[], boolean) method.

Specified by:

doWriteState in class AbstractComponent

Returns:

true if the write operation succeeded

Throws:

Exception

See Also:

IWireState.writeState(IOperationScope, IWireIdentity, byte[][], int[], byte[][], int[], boolean), for a discussion of the byte[][] usage

getFieldsToWrite

protected Collection<IField> getFieldsToWrite(boolean completeState)

Get the fields to write to a frame. This occurs whilst the event frame is locked. This method allows sub-classes to inspect and mutate the #changedFields field prior to being written to a frame.

Parameters:

completeState -

Returns:

the fields to write into a frame

isEventFrameThread

protected final boolean isEventFrameThread()

Is the executing thread the event frame thread.

Returns:

true if the executing thread is the event frame thread.

logNotTheEventFrameThread

protected void logNotTheEventFrameThread()

Logs an exception and the current event frame thread.

toDetailedString

public String toDetailedString()

Description copied from interface: IDescriptor

Provides a formatted string describing this object in detail. This has the same or more information than the standard Object.toString() method.

Specified by:

toDetailedString in interface IDescriptor

Overrides:

toDetailedString in class AbstractComponent

Returns:

a formatted string describing this object in detail

getFrameIdentifier

protected ThreadLocal<IEventFrameExecution> getFrameIdentifier()

Returns:

A thread local variable to hold the IEventFrameExecution of the current event frame. This is bound to the thread executing the event frame.

getFields

protected Map<String,IField> getFields()

Returns:

The IField objects this container holds, indexed by their String identity. Uses the 'cheap read-write lock'

clone

public Object clone()
             throws CloneNotSupportedException

Description copied from interface: IEvent

Clone this.

Specified by:

clone in interface IEvent

Overrides:

clone in class AbstractComponent

Returns:

a clone of this

Throws:

CloneNotSupportedException

See Also:

Object#clone)_

toString

public final String toString()

Overrides:

toString in class AbstractComponent

hashCode

public final int hashCode()

Overrides:

hashCode in class AbstractComponent

equals

public final boolean equals(Object obj)

Overrides:

equals in class AbstractComponent

doCommitEvents

protected void doCommitEvents()

Perform the operation to commit all events