com.sas.entities
Class AggregateEntity

com.sas.entities.AggregateEntity

public class AggregateEntity

AggregateEntity is a collection of entities that function as a single Entity object. AggregateEntity is often used in visual displays (property sheets) because of its ability to map its attribute values to the underlying entities that comprise it.

Creating an AggregateEntity

           AggregateEntity ae = new AggregateEntity();

           EntityInterface entityOne = new Entity();
           entityOne.setAttribute("season", "spring");
           entityOne.setAttribute("month", "May");
           entityOne.setAttribute("foo", "someValue");

           EntityInterface entityTwo = new Entity();
           entityTwo.setAttribute("season", "summer");
           entityTwo.setAttribute("month", "July");
           entityTwo.setAttribute("year", "2002");

           ae.addEntity(entityOne, "entityOne");
           ae.addEntity(entityTwo, "entityTwo");
 

The AggregateEntity maintains an "association map" that is used to associate AttributeDescriptors to the entities that they were obtained from. The keys in the "association map" are the names of the AttributeDescriptors. The value associated with a key is a list of EntityAttrs. EntityAttr is a complex object created by specifying an EntityInterface and the name of the AttributeDescriptor (EntityAttr).

AttributeDescriptor Association Map

AttributeDescriptor

EntityInterface+ AttributeDescriptor Name (EntityAttr)

season

entityOne	+	season
entityTwo	+	season

month

entityOne	+	month
entityTwo	+	month

foo

entityOne

+

foo

year

entityTwo

+

year

Invoking "Entity Methods" on the AggregateEntity

"Entity methods" are invoked through the underlying EntityInterface which is obtained by invoking getEntityInterface():

           AggregateEntity ae = new AggregateEntity();
           EntityInterface ei = ae.getEntityInterface();
           ei.setAttribute("season", "autumn");
 

The action, setAttribute("season", autumn"), will cause all AttributeDescriptors associated with the AttributeDescriptor key, "season", to be updated with the new value of "autumn". The attribute value for "season" for both entityOne and entityTwo will now be "autumn".

Removing a Natural Association

When an Entity is added to the AggregateEntity, the entity is queried for a list of its AttributeDescriptors. Keys are created in the "association map" for each unique AttributeDescriptor name and an EntityAttr is created for the entity and is mapped to the key. This occurs automatically (no user action needed to create the association map). However, this may not be desired. A user may wish to remove an EntityAttr for a particular AttributeDescriptor key. Referring to the example in Creating an AggregateEntity, we will "disassociate" the "season" attribute for entityTwo. Setting the attribute "season" for the AggregateEntity will no longer effect the value of "season" for entityTwo:

          EntityAttr seasonAttr = new EntityAttr(entityTwo, "season");
          ae.removeFromKeyList("season",seasonAttr);
 

Creating an "Unnatural" Association

Referring to the example in Creating an AggregateEntity, we will associate the attribute, "foo" in entityOne with the AggregateEntity attribute,"year". Any change to the AggregateEntity attribute, "year", is automatically reflected in the attribute, "year", of entityOne (assuming that it was not explicitly removed through removeFromKeyList( String key, EntityAttr item ) ). To associate the attribute, "foo", of entityOne to the AggregateEntity attribute, "year", we need to add an entry for "foo" to the association map:

          EntityAttr fooAttr = new EntityAttr(entityOne, "foo");
          ae.addToKeyList("year", fooAttr, -1);
 

Any changes to the value of the AggregateEntity attribute, "year" will be reflected in the value of "year" in entityTwo as well as "foo" in entityOne.

Initial AttributeValue

Referring to the example in Creating an AggregateEntity, there are two inputs for "month" (one from entityOne and one from entityTwo). Which one is used for the original value for the AggregateEntity? The answer is the first EntityAttr item (EntityInterface + AttributeDescriptorInterface name) that was created for "month". entityOne was added to the AggregateEntity first. A map key was created for "month" in the AttributeDescriptor Association Map and an entry for entityOne, (entityOne+month), was added:

AttributeDescriptor Association Map

month

entityOne

+

month

After adding entityTwo, the AttributeDescriptorMap entry for "month" would look as follows:

AttributeDescriptor Association Map

month

entityOne	+	month
entityTwo	+	month

The initial value of "month" can be changed by invoking moveBetweenKeyLists( String keyFrom, String keyTo, EntityAttr item, int index to reorder the list of EntityAttrs:

          EntityAttr monthAttr = new EntityAttr(entityTwo, "month");
          ae.moveBetweenKeyLists("month","month",monthAttr,0); //move this to the top of the list
 

AttributeDescriptor Association Map

month

entityTwo	+	month
entityOne	+	month

Recreating an AggregateEntity

An AggregateEntity may be created by an application for use in other applications. The application that creates the AggregateEntity may need to persist the AggregateEntity through use of the com.sas.entities.persist.AggregateEntityPersistenceUtility or other persistence mechanisms. When "recreating" an AggregateEntity that has been persisted through the com.sas.entities.persist.AggregateEntityPersistenceUtility, the individual entities that comprise the AggregateEntity need to be relinked (associated) to the AggregateEntity:

 AggregateEntity ae = new AggregateEntity();
 EntityInterface entityOne = new Entity();
 EntityInterface entityTwo = new Entity();

 ae.addEntity(entityOne, "entityOne");
 ae.addEntity(entityTwo, "entityTwo");

 //persist the individual entities and the AggregateEntity
 //using the EntityPersistenceUtility and the
 //AggregateEntityPersistenceUtility

 String sEntityOne = EntityPersistenceUtility.writeXMLToString(entityOne);
 String sEntityTwo = EntityPersistenceUtility.writeXMLToString(entityTwo);
 String sAgg = AggregateEntityPersistenceUtility.writeXMLToString(ae);

 //recreate the individual entities and the AggregateEntity
 EntityInterface newEntityOne = EntityPersistenceUtility.createEntityFromXML(sEntityOne);
 EntityInterface newEntityTwo = EntityPersistenceUtility.createEntityFromXML(sEntityTwo);
 AggregateEntity newAe = AggregateEntityPersistenceUtility.createEntityFromXML(sAgg);


 //associate ("relink") the individual entities to the AggregateEntity
 boolean newEntityOneStatus = newAe.relink(newEntityOne);
 boolean newEntityTwoStatus = newAe.relink(newEntityTwo);
 boolean allStatus = newAe.validateRelink();
 

Constructor Summary

AggregateEntity()
Default constructor.

AggregateEntity(java.lang.String name)
Constructor that specifies the AggregateEntity's name.

Method Summary

void	addEntity(EntityInterface entity, java.lang.String entityName) Add an Entity to the AggregateEntity.
void	addEntityKey(java.lang.String entityKey, java.lang.String entityName) Add an entity key to the aggregate.
void	addToKeyList(java.lang.String key, EntityAttr item, int index) Add an entry to the AttributeDescriptor "association map".
java.util.Map	getEntities() Returns a map of entities that have been added to the AggregateEntity.
EntityInterface	getEntityInterface() Returns an EntityInterface interface that can be used to invoke "entity methods" on the AggregateEntity.
java.util.ArrayList	getKeyList(java.lang.String key) Returns the ordered list of EntityAttrs(EntityInterface + AttributeDescriptor name) for a specific AttributeDescriptor key.
javax.swing.tree.TreeModel	getMappingTreeModel() Returns a TreeModel interface to be used to display the mappings in the AggregateEntity.
java.lang.String[]	getMissingEntities() Returns an array of entityKeys corresponding to the individual entities that were not successfully relinked.
java.lang.String	getName() Returns the AggregateEntity's name.
void	moveBetweenKeyLists(java.lang.String keyFrom, java.lang.String keyTo, EntityAttr item, int index) Move an EntityAttr (EntityInterface + AttributeDescriptor name) from one AttributeDescriptor key to another.
void	refreshModelListeners() Fires a TreeStructureChangeEvent to all of the listeners on the model to notify them of a change.
boolean	relink(EntityInterface entity) Associates an individual entity to the AggregateEntity.
void	removeEntity(EntityInterface entity) Remove an Entity from the AggregateEntity.
void	removeFromKeyList(java.lang.String key, EntityAttr item) Remove an EntityAttr (EntityInterface + AttributeDescriptor name) from the AttributeDescriptor "association map".
void	setName(java.lang.String name) Sets the AggregateEntity's name.
java.lang.String	toString() Returns the AggregateEntity's name.
boolean	validateRelink() Returns a boolean indicating whether all of the individual entities associated with the AggregateEntity were successfully relinked.

Constructor Detail

AggregateEntity

public AggregateEntity()

Default constructor.

AggregateEntity

public AggregateEntity(java.lang.String name)

Constructor that specifies the AggregateEntity's name.

Parameters:

name - name associated with the AggregateEntity

Method Detail

getEntities

public java.util.Map getEntities()

Returns a map of entities that have been added to the AggregateEntity.

Returns:

key-value pairs (EntityInterface/entity name)

setName

public void setName(java.lang.String name)

Sets the AggregateEntity's name.

Parameters:

name - AggregateEntity name

See Also:

getName()

getName

public java.lang.String getName()

Returns the AggregateEntity's name.

Returns:

name associated with the AggregateEntity

See Also:

setName(String name)

toString

public java.lang.String toString()

Returns the AggregateEntity's name.

Overrides:

toString in class java.lang.Object

Returns:

name associated with the AggregateEntity

See Also:

setName(String name)

addEntityKey

public void addEntityKey(java.lang.String entityKey,
                         java.lang.String entityName)

Add an entity key to the aggregate. This method is used by persistence utilities to recreate the entity. It is not intended for general use.

Parameters:

String - entityKey to be added

String - entityName to show for that entity

addEntity

public void addEntity(EntityInterface entity,
                      java.lang.String entityName)

Add an Entity to the AggregateEntity.

Parameters:

entity - instance of EntityInterface to be added to the AggregateEntity

entityName - name associated with the instance of EntityInterface

removeEntity

public void removeEntity(EntityInterface entity)

Remove an Entity from the AggregateEntity.

Parameters:

entity - instance of EntityInterface to be removed

addToKeyList

public void addToKeyList(java.lang.String key,
                         EntityAttr item,
                         int index)

Add an entry to the AttributeDescriptor "association map". The association map is used to associate AttributeDescriptors to the Entities that they were obtained from:

entityOne
foregroundColor
style

entityTwo
foregroundColor
backgroundColor

AttributeDescriptor Association Map

foregroundColor

entityOne	+	foregroundColor
entityTwo	+	foregroundColor

style

entityOne

+

style

backgroundColor

entityTwo

+

backgroundColor

Parameters:

key - AttributeDescriptor name

item - instance of EntityAttr (EntityInterface + AttributeDescriptor name)

index - location for adding the item (-1 = last position)

removeFromKeyList

public void removeFromKeyList(java.lang.String key,
                              EntityAttr item)

Remove an EntityAttr (EntityInterface + AttributeDescriptor name) from the AttributeDescriptor "association map". The AttributeDescriptor key will be removed when the last mapping is removed.

Parameters:

key - AttributeDescriptor name

item - instance of EntityAttr (EntityInterface + AttributeDescriptor name)

moveBetweenKeyLists

public void moveBetweenKeyLists(java.lang.String keyFrom,
                                java.lang.String keyTo,
                                EntityAttr item,
                                int index)

Move an EntityAttr (EntityInterface + AttributeDescriptor name) from one AttributeDescriptor key to another. The entry is first removed from the source AttributeDescriptor key and then added to the target AttributeDescriptor key.

Parameters:

keyFrom - the name of the AttributeDescriptor that the entry is removed from

keyTo - the name of the AttributeDescriptor that the entry is added to

item - instance of EntityAttr (EntityInterface + AttributeDescriptor name) that is to be moved

index - location in the target list

getKeyList

public java.util.ArrayList getKeyList(java.lang.String key)

Returns the ordered list of EntityAttrs(EntityInterface + AttributeDescriptor name) for a specific AttributeDescriptor key.

Parameters:

key - name of the AttributeDescriptor

Returns:

list of EntityAttrs mapped to this key

getMappingTreeModel

public javax.swing.tree.TreeModel getMappingTreeModel()

Returns a TreeModel interface to be used to display the mappings in the AggregateEntity.

Returns:

TreeModel

getEntityInterface

public EntityInterface getEntityInterface()

Returns an EntityInterface interface that can be used to invoke "entity methods" on the AggregateEntity.

Returns:

instance of EntityInterface

See Also:

EntityInterface

refreshModelListeners

public void refreshModelListeners()

Fires a TreeStructureChangeEvent to all of the listeners on the model to notify them of a change.

relink

public boolean relink(EntityInterface entity)

Associates an individual entity to the AggregateEntity. This step is necessary when recreating the AggregateEntity after persisting it through the com.sas.entities.persist.AggregateEntityPersistenceUtility.

 AggregateEntity ae = new AggregateEntity();
 EntityInterface entityOne = new Entity();
 EntityInterface entityTwo = new Entity();

 ae.addEntity(entityOne, "entityOne");
 ae.addEntity(entityTwo, "entityTwo");

 //persist the individual entities and the AggregateEntity
 //using the EntityPersistenceUtility and the
 //AggregateEntityPersistenceUtility

 String sEntityOne = EntityPersistenceUtility.writeXMLToString(entityOne);
 String sEntityTwo = EntityPersistenceUtility.writeXMLToString(entityTwo);
 String sAgg = AggregateEntityPersistenceUtility.writeXMLToString(ae);

 //recreate the individual entities and the AggregateEntity
 EntityInterface newEntityOne = EntityPersistenceUtility.createEntityFromXML(sEntityOne);
 EntityInterface newEntityTwo = EntityPersistenceUtility.createEntityFromXML(sEntityTwo);
 AggregateEntity newAe = AggregateEntityPersistenceUtility.createEntityFromXML(sAgg);


 //associate ("relink") the individual entities to the AggregateEntity
 boolean newEntityOneStatus = newAe.relink(newEntityOne);
 boolean newEntityTwoStatus = newAe.relink(newEntityTwo);
 boolean allStatus = newAe.validateRelink();
 

Parameters:

entity - instance of EntityInterface

Returns:

true if the entity was successfully associated with the AggregateEntity, false otherwise

validateRelink

public boolean validateRelink()

Returns a boolean indicating whether all of the individual entities associated with the AggregateEntity were successfully relinked.

Returns:

true if all entities were successfully relinked; false otherwise

See Also:

relink(com.sas.entities.EntityInterface)

getMissingEntities

public java.lang.String[] getMissingEntities()

Returns an array of entityKeys corresponding to the individual entities that were not successfully relinked.

Returns:

array of entityKeys