org.datamanager.kernel
Class Entity

java.lang.Object
  |
  +--org.datamanager.kernel.Entity

All Implemented Interfaces:

EventGenerator, Serializable

Direct Known Subclasses:

CachingProxyEntity

public abstract class Entity

extends Object

implements EventGenerator, Serializable

The major workhorse of the DataManager, Entity is an abstract class which only implements the create() method and the default, no args constructor. The addBase(), removeBase(), attach(), and detach() methods are needed to help uncouple the implementation of Entity storage and the kernel API. They are used inside the kernel by the EntityProxy. No one outside of the kernel should extend Entity so it is mostly safe to have these. Actually, since no one outside of the kernel can see Identifier it should be impossible to extend Entity outside of the kernel now.

Author:

Matthew Farrellee

, Benjamin Keil

See Also:

Serialized Form

Constructor Summary

protected

Entity() A constructor existing only for the sake of subclasses.

Method Summary

protected abstract void	addBase(org.datamanager.kernel.Identifier identifier) Add an Entity to the list of bases.
abstract void	attach(Entity attribute) Attach the given Entity as an attribute.
protected abstract void	attach(org.datamanager.kernel.Identifier identifier) Attach the Entity with the given Identifier as an attribute.
protected Entity[]	chooseEntities(EntityConstraint constraint, List candidateEntityIdentifiers) Returns an array of all the Entities in the given List that satisfy the given Constraint.
protected boolean	constraintAcceptsEntity(EntityConstraint constraint, org.datamanager.kernel.Identifier entityIdentifier) Returns true if the EntityConstraint accepts the Entity associated with the Identifier; false if not.
static Entity	create(String name) Create a new Entity with the given name.
abstract void	detach(Entity attribute) Detach the given Entity.
protected abstract void	detach(org.datamanager.kernel.Identifier identifier) Detach the Entity with the given Identifier.
abstract Entity[]	getAttributes(EntityConstraint constraint) Request a constrained set of all entities linked to the Entity.
abstract Entity[]	getBases(EntityConstraint constraint) Request a constrained set of all entities of which the Entity is an attribute.
protected Entity[]	getEntities(List entityList) Turns a List of Entities into an Array of Entities.
abstract String	getName() Request the Entity's name.
abstract EntityValue	getValue() Request the Entity's value.
protected List	makeIdentifierList(org.datamanager.kernel.Identifier[] identifierArray) Creates a list of Identifiers from the given array of Identifiers.
protected abstract void	removeBase(org.datamanager.kernel.Identifier identifier) Remove an Entity from the list of bases.
protected abstract void	setAttributes(org.datamanager.kernel.Identifier[] attributeIdentifiers) Sets the list of all attributes on this Entity.
protected abstract void	setBases(org.datamanager.kernel.Identifier[] baseIdentifiers) Sets the list of all bases on this Entity.
abstract void	setValue(EntityValue value) Request a change of the Entity's value.
abstract void	subscribe(EventHandler listener, EventConstraint constraint) Subscribe to the Entity for DataManagerEvents satisfying the given EventConstraint.
abstract String	toString() A toString() method that overrides the one in Object.
abstract void	unsubscribe(EventHandler handler) Remove all event subscriptions for which the EventHandler is subscribed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Entity

protected Entity()

A constructor existing only for the sake of subclasses.

Method Detail

create

public static Entity create(String name)
                     throws DataManagerException

Create a new Entity with the given name. Note: Names do not have to be unique.

Parameters:

name - The name of the new Entity.

Returns:

A new Entity.

Throws:

DataManagerException

attach

public abstract void attach(Entity attribute)
                     throws DataManagerException

Attach the given Entity as an attribute.

Parameters:

attribute - The Entity to attach.

Throws:

DataManagerException

detach

public abstract void detach(Entity attribute)
                     throws DataManagerException

Detach the given Entity.

Parameters:

attribute - The Entity to detach.

Throws:

DataManagerException

getName

public abstract String getName()
                        throws DataManagerException

Request the Entity's name.

Returns:

The Entity's name.

Throws:

DataManagerException

getValue

public abstract EntityValue getValue()
                              throws DataManagerException

Request the Entity's value.

Returns:

The Entity's value.

Throws:

DataManagerException

setValue

public abstract void setValue(EntityValue value)
                       throws DataManagerException

Request a change of the Entity's value.

Parameters:

value - The new EntityValue that you wish to give the Entity.

Throws:

DataManagerException

getAttributes

public abstract Entity[] getAttributes(EntityConstraint constraint)
                                throws DataManagerException

Request a constrained set of all entities linked to the Entity.

Parameters:

constraint - A constraint with which to filter attributes.

Returns:

An array of entities that are attributes of the Entity and satisfy the given constraint.

Throws:

DataManagerException

setAttributes

protected abstract void setAttributes(org.datamanager.kernel.Identifier[] attributeIdentifiers)
                               throws DataManagerException

Sets the list of all attributes on this Entity.

DataManagerException

getBases

public abstract Entity[] getBases(EntityConstraint constraint)
                           throws DataManagerException

Request a constrained set of all entities of which the Entity is an attribute.

Parameters:

constraint - The EntityConstraint that you wish to apply to get the bases of the Entity.

Returns:

An array of entities that are bases of the Entity and satisfy the given constraint.

Throws:

DataManagerException

setBases

protected abstract void setBases(org.datamanager.kernel.Identifier[] baseIdentifiers)
                          throws DataManagerException

Sets the list of all bases on this Entity.

DataManagerException

subscribe

public abstract void subscribe(EventHandler listener,
                               EventConstraint constraint)
                        throws DataManagerException

Subscribe to the Entity for DataManagerEvents satisfying the given EventConstraint.

Specified by:

subscribe in interface EventGenerator

Parameters:

listener - The EventHandler that will receive the events.

constraint - The constraint used to filter events.

Throws:

DataManagerException

unsubscribe

public abstract void unsubscribe(EventHandler handler)
                          throws DataManagerException

Remove all event subscriptions for which the EventHandler is subscribed.

Specified by:

unsubscribe in interface EventGenerator

Parameters:

handler - The EventHandler to unsubscribe.

Throws:

DataManagerException

toString

public abstract String toString()

A toString() method that overrides the one in Object.

Overrides:

toString in class Object

Returns:

A String representation of this entity.

addBase

protected abstract void addBase(org.datamanager.kernel.Identifier identifier)
                         throws DataManagerException

Add an Entity to the list of bases. This should only be called when the base is adding the EntityEntity as an attribute, that is, this should only be called by attach().

Parameters:

identifier - The Identifier of the Entity that is a new base.

Throws:

DataManagerException

removeBase

protected abstract void removeBase(org.datamanager.kernel.Identifier identifier)
                            throws DataManagerException

Remove an Entity from the list of bases. This should only be called by the base as it removes the Entity as an attribute (which it does automatically), that is, this should only be called by detach().

Parameters:

identifier - The Identifier of the Entity that will no longer be a base.

Throws:

DataManagerException

attach

protected abstract void attach(org.datamanager.kernel.Identifier identifier)
                        throws DataManagerException

Attach the Entity with the given Identifier as an attribute.

Parameters:

identifier - The Identifier of the Entity to attach.

Throws:

DataManagerException

detach

protected abstract void detach(org.datamanager.kernel.Identifier identifier)
                        throws DataManagerException

Detach the Entity with the given Identifier.

Parameters:

identifier - The Identifier of the Entity to detach.

Throws:

DataManagerException

chooseEntities

protected Entity[] chooseEntities(EntityConstraint constraint,
                                  List candidateEntityIdentifiers)
                           throws DataManagerException

Returns an array of all the Entities in the given List that satisfy the given Constraint.

Parameters:

constraint - An EntityConstraint to filter the entities with.

candidateEntityIdentifiers - A List of Identifiers for candidate Entitys to chose from.

Returns:

An array of EntityProxys that were identified in the candidateEntityIdentifiers List and were accepted by the EntityConstraint.

Throws:

DataManagerException

getEntities

protected Entity[] getEntities(List entityList)

Turns a List of Entities into an Array of Entities.

Parameters:

entityList - A List of Entities to turn into an array.

Returns:

entityArray An array of Entities.

constraintAcceptsEntity

protected boolean constraintAcceptsEntity(EntityConstraint constraint,
                                          org.datamanager.kernel.Identifier entityIdentifier)
                                   throws DataManagerException

Returns true if the EntityConstraint accepts the Entity associated with the Identifier; false if not.

Parameters:

constraint - An EntityConstraint to test the Entity associated with the Identifier against.

entityIdentifier - An Identifier for the Entity that we wish to test.

Returns:

A boolean indicating whether or not the EntityConstraint accepts the Entity associated with the Identifier.

Throws:

DataManagerException

makeIdentifierList

protected List makeIdentifierList(org.datamanager.kernel.Identifier[] identifierArray)

Creates a list of Identifiers from the given array of Identifiers.