fulmine.model.component
Class AbstractComponent

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

All Implemented Interfaces:

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

Direct Known Subclasses:

AbstractContainer, AbstractField, EventSource, ImageEvent

public abstract class AbstractComponent
extends AbstractLifeCycle
implements IComponent, Cloneable

A base component class that implements many common functions. Each component has an identity that is provided during construction. A component is not explicitly related with a context.

The abstract component implements the IAddressable interface. This is an implementation detail and provides the context with the unique identity of this component as an entity.

The addListener(IEventListener) and removeListener(IEventListener) methods use copy-on-write for the collection of listeners.

Author:

Ramon Servadei

Constructor Summary

protected	AbstractComponent(String identity, IType type, IDomain domain) Construct the component with an identity and type.
protected	AbstractComponent(String identity, IType type, IDomain domain, byte eventGroupId) Construct the component with an identity, type and event group id.

Method Summary

void	addEvent(IEvent event) A synchronous notification implementation
boolean	addListener(IEventListener listener) Add the listener to the end of the list of listeners registered against this.
protected void	checkClone() Check if this instance is a clone.
Object	clone() Clone this.
protected String	createIdentityString() Utility method to create the system identity string for a component.
protected void	doComponentDestroy() The destroy method that is invoked on a non-cloned version of this.
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doPostAddListener(IEventListener listener) Hook to allow sub-classes to perform any post processing after an IEventListener has been added via addListener(IEventListener)
protected void	doPostRemoveListener(IEventListener listener) Hook to allow sub-classes to perform any post processing after an IEventListener has been removed via removeListener(IEventListener)
protected abstract 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 abstract 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.
boolean	equals(Object obj)
String	getAddress() Get the unique address for this.
IAddressable	getAddressable()
IDomain	getDomain() Get the domain attribute of this object.
IEventFrameExecution	getDrivingFrame() Get the event frame execution that directly caused this event to occur.
byte	getEventSourceGroupId() A byte identifying the event source group id.
IEventFrameExecution	getFrame() Get the event frame of this event.
String	getIdentity() Get the identification string for this entity.
protected StringBuilder	getIdentityString() Helper method to return the component's identity and whether it is a clone or not
List<IEventListener>	getListeners() Get the list of IEventListener instances observing this.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
IEventSource	getSource() Get the event source that generated this event
IEvent	getTriggerEvent() Get the 'trigger event'.
IType	getType() Get the type attribute of this object.
int	hashCode()
boolean	isClone() Determine if this instance is the original or a clone
void	readState(IOperationScope scope, byte[] dataBuffer, int start, int numberOfBytes) Update this object's internal state from the fulmine delta (FD) wire format state encapsulated in the byte buffer.
boolean	removeListener(IEventListener listener) Remove the listener from the list of listeners registered against this.
List<IEventListener>	removeListeners() Remove all listeners registered for receiving IEvent events originating from this.
protected void	setDrivingFrame(IEventFrameExecution drivingFrame) Set the driving frame that caused the change in this component
void	setFrame(IEventFrameExecution frame) Set the event frame identifier for this cloneable component.
void	setTriggerEvent(IEvent triggerEvent) Set the 'trigger event'.
String	toDetailedString() Provides a formatted string describing this object in detail.
String	toIdentityString() Get a string that provides the identification for this object.
String	toString()
void	writeState(IOperationScope scope, IWireIdentity wireId, byte[][] headerBuffer, int[] headerBufferPosition, byte[][] dataBuffer, int[] dataBufferPosition, boolean completeState) Write the state of this object in fulmine delta (FD) wire format to the byte buffers.

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

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Constructor Detail

AbstractComponent

protected AbstractComponent(String identity,
                            IType type,
                            IDomain domain)

Construct the component with an identity and type. This assigns a 0 event group id

Parameters:

identity - the identity of the component

type - the type of the component

domain - the domain of the component

AbstractComponent

protected AbstractComponent(String identity,
                            IType type,
                            IDomain domain,
                            byte eventGroupId)

Construct the component with an identity, type and event group id.

Parameters:

identity - the identity of the component

type - the type of the component

domain - the domain of the component

eventGroupId - the event group id

Method Detail

getEventSourceGroupId

public final byte getEventSourceGroupId()

Description copied from interface: IEventSource

A byte identifying the event source group id. This will be the id of the EventProcessor that will distribute the events from this source.

Specified by:

getEventSourceGroupId in interface IEventSource

Returns:

a byte for the EventProcessor servicing this.

getIdentity

public final String getIdentity()

Description copied from interface: IAddressable

Get the identification string for this entity. This is unique within the type and domain.

Specified by:

getIdentity in interface IAddressable

Returns:

a String identity providing an identification for this entity within its type and domain.

See Also:

IAddressable.getType(), IAddressable.getDomain()

getType

public final IType getType()

Description copied from interface: IAddressable

Get the type attribute of this object. The type is orthogonal to the domain.

Specified by:

getType in interface IAddressable

Returns:

the type of this object

See Also:

IAddressable.getDomain()

getDomain

public final IDomain getDomain()

Description copied from interface: IAddressable

Get the domain attribute of this object. The domain is orthogonal to the type.

Specified by:

getDomain in interface IAddressable

Returns:

the domain of this object

See Also:

IAddressable.getType()

getAddress

public final String getAddress()

Description copied from interface: IAddressable

Get the unique address for this. The address is composed of the identity, domain and type.

Specified by:

getAddress in interface IAddressable

Returns:

the unique address for this

getSource

public final IEventSource getSource()

Description copied from interface: IEvent

Get the event source that generated this event

Specified by:

getSource in interface IEvent

Returns:

the source that generated the event

getDrivingFrame

public final IEventFrameExecution getDrivingFrame()

Description copied from interface: IEvent

Get the event frame execution that directly caused this event to occur.

An event occurs in its own event frame but it may have been caused by an event from another frame. This other frame is known as the 'driving' frame and directly causes this event. In this paradigm, where one event can cause another event to occur but in a separate event frame execution, it is sometimes necessary to know the frame of the first event so that the 2 events can be linked together.

Specified by:

getDrivingFrame in interface IEvent

Returns:

an IEventFrameExecution that is the event frame execution of the event that caused this event to occur.

getFrame

public final IEventFrameExecution getFrame()

Description copied from interface: IEvent

Get the event frame of this event.

Specified by:

getFrame in interface IEvent

Returns:

the IEventFrameExecution that identifies the frame this event occurred in.

setFrame

public final void setFrame(IEventFrameExecution frame)

Set the event frame identifier for this cloneable component. This method is useful to set the frame for an event so that it matches up with the event frame of an event that generated this event. This allows an IEventListener to process these events as a single work unit even though they are generated in separate frames.

Parameters:

frame - the event frame to associate this IEvent with.

setDrivingFrame

protected final void setDrivingFrame(IEventFrameExecution drivingFrame)

Set the driving frame that caused the change in this component

Parameters:

drivingFrame - the driving frame

readState

public final void readState(IOperationScope scope,
                            byte[] dataBuffer,
                            int start,
                            int numberOfBytes)

Description copied from interface: IWireState

Update this object's internal state from the fulmine delta (FD) wire format state encapsulated in the byte buffer.

The wire format state includes the fields of the object that have changed. The logic to read the component state should be delegated to the individual component.

Specified by:

readState in interface IWireState

Parameters:

scope - the scope of the read state operation

dataBuffer - the byte buffer that holds the contiguous wire format state to read, at some position

start - where the wire format state begins in the byte buffer

numberOfBytes - the number of bytes in the byte buffer to read the wire format state

writeState

public final void writeState(IOperationScope scope,
                             IWireIdentity wireId,
                             byte[][] headerBuffer,
                             int[] headerBufferPosition,
                             byte[][] dataBuffer,
                             int[] dataBufferPosition,
                             boolean completeState)

Description copied from interface: IWireState

Write the state of this object in fulmine delta (FD) wire format to the byte buffers. This operation can write the entire state or just changes.

The object fields are written into headerBuffer[0] starting at headerBufferPosition[0]. The fields are written in 'component spec' format. The diagram below illustrates the IWF component spec for a single component:

 -------------------------------------------------------
 |   1 byte        |   component bytes   |   data bytes    |
 -------------------------------------------------------
 | 7 6 5 4 3 2 1 0 |                 |                 |
 -------------------------------------------------------
 |   fbc  |   dbc  |     component       |  data position  |
 -------------------------------------------------------
 

• fbc - the number of bytes for the component portion
• dbc - the number of bytes for the data position portion
• component - the bytes for the component. This is the wire format for the component and will differ depending on the component type.
• data position - the position in the data buffer where the data is written

An SWF component spec is slightly different:

 -------------------------------------------------------
 | 1 byte | 1 byte |   component bytes   |   data bytes    |
 -------------------------------------------------------
 |   fbc  |   dbc  |     component       |  data position  |
 -------------------------------------------------------
 

The data is written into dataBuffer[0] starting at dataBufferPosition[0].

Specified by:

writeState in interface IWireState

Parameters:

scope - the scope of the write state operation

wireId - the wire identity, expresses if this is an IWF or SWF component spec

headerBuffer - headerBuffer[0] holds the header buffer to write the component spec that describes the object's fields and their corresponding data positions in the dataBuffer

headerBufferPosition - headerBufferPosition[0] holds the current position in the headerBuffer[0]

dataBuffer - dataBuffer[0] holds the data buffer that component data is written to

dataBufferPosition - dataBufferPosition[0] holds the current position in the dataBuffer[0]

completeState - whether to write the complete state or only changes

addEvent

public void addEvent(IEvent event)

A synchronous notification implementation

Specified by:

addEvent in interface IEventSource

Parameters:

event - the event to pass on to the registered listeners

addListener

public final boolean addListener(IEventListener listener)

Description copied from interface: IEventSource

Add the listener to the end of the list of listeners registered against this. If the listener is an IPriorityEventListener, it is added to the beginning of the list.

Listeners are reference counted. Adding the same listener multiple times simply increments a reference count of the listener instance; if a listener is added twice, it must be removed twice for the listener instance reference to be removed from the internal list.

Specified by:

addListener in interface IEventSource

Parameters:

listener - the listener to add

Returns:

true if the listener instance was added (there were no reference counts for it), false if it already existed (the reference count was incremented)

getListeners

public final List<IEventListener> getListeners()

Description copied from interface: IEventSource

Get the list of IEventListener instances observing this. The list is the order of registration and the notification order for any IEvent raised by this event source.

The list is not modifiable.

Specified by:

getListeners in interface IEventSource

Returns:

an unmodifiable list of listeners, or null if there are no listeners

removeListener

public final boolean removeListener(IEventListener listener)

Description copied from interface: IEventSource

Remove the listener from the list of listeners registered against this. If this is the last listener being removed, the list of listeners is set to null.

Listeners are reference counted. When removing a listener, this method decrements the reference count until there are no more references, at which point the listener instance reference is actually removed.

Specified by:

removeListener in interface IEventSource

Parameters:

listener - the listener to remove

Returns:

true if the listener was found and the reference count was 0 and it was removed, false otherwise

removeListeners

public final List<IEventListener> removeListeners()

Description copied from interface: IEventSource

Remove all listeners registered for receiving IEvent events originating from this.

Specified by:

removeListeners in interface IEventSource

Returns:

the list of listeners removed

doPostAddListener

protected void doPostAddListener(IEventListener listener)

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

Parameters:

listener - the listener that has been added

doPostRemoveListener

protected void doPostRemoveListener(IEventListener listener)

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

Parameters:

listener - the listener that has been removed

doStart

protected 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

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

doComponentDestroy

protected void doComponentDestroy()

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

checkClone

protected final void checkClone()

Check if this instance is a clone.

Throws:

IllegalStateException - if this is a cloned instance.

isClone

public final boolean isClone()

Determine if this instance is the original or a clone

Returns:

true if this is a clone of the original

createIdentityString

protected final String createIdentityString()

Utility method to create the system identity string for a component.

Returns:

the system identity string

getIdentityString

protected StringBuilder getIdentityString()

Helper method to return the component's identity and whether it is a clone or not

Returns:

a string with the component's identity and whether its a clone or not

doWriteState

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

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

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

doReadState

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

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

Returns:

true if the read operation succeded.

Throws:

Exception

See Also:

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

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

Returns:

a formatted string describing this object in detail

toIdentityString

public String toIdentityString()

Description copied from interface: IDescriptor

Get a string that provides the identification for this object. This should have no more detail than the Object.toString() method.

Specified by:

toIdentityString in interface IDescriptor

Returns:

a string that provides the identification for this object

getTriggerEvent

public IEvent getTriggerEvent()

Description copied from interface: IEvent

Get the 'trigger event'. This is an event that is added to the context's IEventManager queue after this event has been processed.

Specified by:

getTriggerEvent in interface IEvent

Returns:

the trigger event to queue after this event has been processed, or null if there is not a trigger event.

setTriggerEvent

public void setTriggerEvent(IEvent triggerEvent)

Description copied from interface: IEvent

Set the 'trigger event'. This is an event that is added to the context's IEventManager queue after this event has been processed.

Specified by:

setTriggerEvent in interface IEvent

Parameters:

triggerEvent - the trigger event that will be queued after this event has been processed.

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

getAddressable

public final IAddressable getAddressable()

toString

public String toString()

Overrides:

toString in class AbstractLifeCycle

clone

public Object clone()
             throws CloneNotSupportedException

Description copied from interface: IEvent

Clone this.

Specified by:

clone in interface IEvent

Overrides:

clone in class Object

Returns:

a clone of this

Throws:

CloneNotSupportedException

See Also:

Object#clone)_

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object