fulmine.model.container
Interface IContainer

All Superinterfaces:

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

All Known Implementing Classes:

AbstractContainer, AbstractDynamicContainer, AbstractEventProcessingContainer, BasicContainer, Record

public interface IContainer
extends IComponent, IEventFrame, IRemoteSubscribable

A container represents an entity with multiple properties. The properties make up the state of the entity. The properties are represented by IField objects. The IField implementations are for scalar primitive types only. Each property is addressed by its identity (a string). Non-scalar properties can be simulated by using identities with suitable namespacing.

As each field changes, it notifies its container with the IEvent that encapsulates the change. These events are marshaled into an event frame by the container.

A container may be static or dynamic; static container types have an immutable IField population. The definition of the fields is held in a IContainerDefinitionField that will be keyed against the container's type. If the field definition changes for the container type, it must be changed in all contexts. If not, then the container type will not be read correctly by receiving contexts that have an incorrect static definition for the type.

Dynamic containers have a variable (mutable) population with no constraints of the container's type.

Author:

Ramon Servadei

See Also:

IComponent, IContainerDefinitionField, IContainerFactory.IContainerBuilder

Nested Class Summary

static class

IContainer.DataState The enumeration of data states for an IContainer.

Method Summary

void	add(IField field) Add the field to this container.
boolean	contains(String key) Determines if there is an IField instance with an identity equal to the key argument.
void	destroy() This is a life-cycle method of a container to release all resources and perform cleaning up prior to being made redundant.
<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.
DoubleField	getDoubleField(String identity) Get the DoubleField identified by the identity
FloatField	getFloatField(String identity) Get the FloatField identified by the identity
IntegerField	getIntegerField(String identity) Get the IntegerField identified by the identity
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.
StringField	getStringField(String identity) Get the StringField identified by the identity
IType	getType() Get the type of the container.
boolean	isClone() Determine if this instance is the original or a clone.
boolean	isDynamic() Identify if the container is dynamic or static.
boolean	isEmpty() Determines if this container empty.
boolean	isLocal() Is the container local to the host context returned by getContext()
<T extends IField> T	remove(T field) Remove the field from this container.
void	setState(IContainer.DataState dataState) Set the container state.
int	size() Determine the number of IField instances held in this container
void	start() A life-cycle method of a container to initialise all resources.

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

toDetailedString, toIdentityString

Methods inherited from interface fulmine.ILifeCycle

isActive

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity

Methods inherited from interface fulmine.event.IEvent

clone, getDrivingFrame, getFrame, getSource, getTriggerEvent, setTriggerEvent

Methods inherited from interface fulmine.IDescriptor

toDetailedString, toIdentityString

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity

Methods inherited from interface fulmine.event.IEventFrame

addEvent, beginFrame, endFrame, flushFrame, isFrameActive

Methods inherited from interface fulmine.model.container.subscription.remote.IRemoteSubscribable

getRemoteSubscriptionCount, markForRemoteSubscription, unmarkForRemoteSubscription

Method Detail

add

void add(IField field)

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

Parameters:

field - the field to add to this container.

remove

<T extends IField> T remove(T field)

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

Parameters:

field - the field to remove from this container.

Returns:

the removed field

get

<T extends IField> T get(String identity)

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

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

String[] getComponentIdentities()

Get all the identities of the fields in this container.

Returns:

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

start

void start()

A life-cycle method of a container to initialise all resources. Failure to call this method results in a container with an unusable state. Implementations may throw a RuntimeException if a container is accessed without being initialised.

The proper way to retrieve a container is via the ContainerFactory#createContainer(String, int). This will automatically invoke this method.

Idempotent operation.

Specified by:

start in interface ILifeCycle

See Also:

destroy()

destroy

void destroy()

This is a life-cycle method of a container to release all resources and perform cleaning up prior to being made redundant.

Idempotent operation.

Specified by:

destroy in interface IDestroyable

See Also:

start()

setState

void setState(IContainer.DataState dataState)

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.

Parameters:

dataState - the new business state.

See Also:

for a description of the states.

size

int size()

Determine the number of IField instances held in this container

Returns:

the number of IField instances held in this container

getDataState

IContainer.DataState getDataState()

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

Returns:

the current data state

See Also:

DataState for a description of the states.

getType

IType getType()

Get the type of the container. A container type represents a family of related container instances. This is synonymous with a class in an object oriented language.

Specified by:

getType in interface IAddressable

Returns:

a byte describing the type of container.

See Also:

IAddressable.getDomain()

isEmpty

boolean isEmpty()

Determines if this container empty.

Returns:

true if there are no fields in this container.

contains

boolean contains(String key)

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

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.

isDynamic

boolean isDynamic()

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

Returns:

true if the definition is dynamic

isLocal

boolean isLocal()

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

Returns:

true if the container is local

getContext

IFrameworkContext getContext()

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

Returns:

the IFrameworkContext hosting this instance

See Also:

isLocal(), getNativeContextIdentity()

getBooleanField

BooleanField getBooleanField(String identity)

Get the BooleanField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the BooleanField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getStringField

StringField getStringField(String identity)

Get the StringField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the StringField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getIntegerField

IntegerField getIntegerField(String identity)

Get the IntegerField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the IntegerField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getLongField

LongField getLongField(String identity)

Get the LongField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the LongField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getFloatField

FloatField getFloatField(String identity)

Get the FloatField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the FloatField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getDoubleField

DoubleField getDoubleField(String identity)

Get the DoubleField identified by the identity

Parameters:

identity - the identity of the field to get

Returns:

the DoubleField for the identity, null if not found

Throws:

ClassCastException - if the field is not of this type

getNativeContextIdentity

String getNativeContextIdentity()

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

Returns:

the identity of this container's local context

See Also:

isLocal(), getContext()

isClone

boolean isClone()

Determine if this instance is the original or a clone. Any IEventListener instances processing IContainer instances as IEvent instances will receive the container instance as a clone. In this way, the container changes are broadcast as a logically immutable instance.

Returns:

true if this is a clone of the original