org.jasig.portal.groups
Class EntityGroupImpl

java.lang.Object
  extended by org.jasig.portal.groups.GroupMemberImpl
      extended by org.jasig.portal.groups.EntityGroupImpl
All Implemented Interfaces:
IEntityGroup, IGroupMember, IBasicEntity
Direct Known Subclasses:
EntityTestingGroupImpl, LockableEntityGroupImpl

public class EntityGroupImpl
extends GroupMemberImpl
implements IEntityGroup

Reference implementation for IEntityGroup.

Groups do not keep references to their members but instead cache member keys. The members are cached externally. The rules for controlling access to the key caches are a bit obscure, but you should understand them before writing code that updates groups. Access to the caches themselves is synchronized via the cache getters and setters. All requests to get group members and to add or remove group members ultimately go through these methods. The mutating methods, addMember() and removeMember() however, do a copy-on-write. That is, they first make a copy of the cache, add or remove the member key, and then replace the original cache with the copy. This permits multiple read and write threads to run concurrently without throwing ConcurrentModificationExceptions. But it still leaves open the danger of data races because nothing in this class guarantees serialized write access. You must impose this from without, either via explicit locking (GroupService.getLockableGroup()) or by synchronizing access from the caller.

Version:
$Revision: 1.23.4.1 $
Author:
Dan Ellentuck
See Also:
IEntityGroup

Field Summary
private  java.util.HashMap addedMembers
           
private  java.lang.String creatorID
           
private  java.lang.String description
           
private  java.lang.Class leafEntityType
           
protected  IIndividualGroupService localGroupService
           
private  java.util.Set memberEntityKeys
           
private  java.util.Set memberGroupKeys
           
private  boolean memberKeysInitialized
           
private  java.lang.String name
           
private  java.util.HashMap removedMembers
           
 
Constructor Summary
EntityGroupImpl(java.lang.String groupKey, java.lang.Class entityType)
          EntityGroupImpl
 
Method Summary
 void addMember(IGroupMember gm)
          Adds IGroupMember gm to our member Map and conversely, adds this to gm's group Map, after checking that the addition does not violate group rules.
protected  boolean areMemberKeysInitialized()
           
private  void checkProspectiveMember(IGroupMember gm)
          A member must share the entityType of its containing IEntityGroup.
protected  void clearPendingUpdates()
          Clear out caches for pending adds and deletes of group members.
 boolean contains(IGroupMember gm)
          Checks if GroupMember gm is a member of this.
private  java.util.Set copyMemberEntityKeys()
          Clone the member entity keys.
private  java.util.Set copyMemberGroupKeys()
          Clone the member group keys.
 boolean deepContains(IGroupMember gm)
          Checks recursively if GroupMember gm is a member of this.
 void delete()
          Delegates to the factory.
 boolean equals(java.lang.Object obj)
          Answers if Object o is an IGroupMember that refers to the same underlying entity(ies) as this.
 java.util.HashMap getAddedMembers()
           
 java.util.Iterator getAllEntities()
          Returns an Iterator over the Set of this IEntityGroup's recursively-retrieved members that are IEntities.
 java.util.Iterator getAllMembers()
          Returns an Iterator over the Set of recursively-retrieved IGroupMembers that are members of this IEntityGroup.
protected  CompositeEntityIdentifier getCompositeEntityIdentifier()
          Returns the EntityIdentifier cast to a CompositeEntityIdentifier so that its service nodes can be pushed and popped.
 java.lang.String getCreatorID()
          Returns the name of the group creator.
 java.lang.String getDescription()
          Returns the group description, which may be null.
 java.util.Iterator getEntities()
          Returns an Iterator over this IEntityGroup's members that are IEntities.
 EntityIdentifier getEntityIdentifier()
           
 java.lang.String getEntityKey()
          Returns the key of the underyling entity.
 java.lang.Class getEntityType()
          Returns the entity type of this groups's leaf members.
 java.lang.String getGroupID()
           
 java.lang.Class getLeafType()
          Returns the entity type of this groups's members.
protected  IIndividualGroupService getLocalGroupService()
           
 java.lang.String getLocalKey()
          Returns the key from the group service of origin.
protected  java.util.Iterator getMemberEntities()
          Returns an Iterator over the entities in our member Collection.
private  java.util.Set getMemberEntityKeys()
           
private  java.util.Set getMemberGroupKeys()
           
 IEntityGroup getMemberGroupNamed(java.lang.String name)
          Returns the named member IEntityGroup.
protected  java.util.Iterator getMemberGroups()
          Returns an Iterator over the groups in our member Collection.
 java.util.Iterator getMembers()
          Returns an Iterator over the GroupMembers in our member Collection.
 java.lang.String getName()
          Returns the group name.
 java.util.HashMap getRemovedMembers()
           
protected  GroupService getService()
           
 javax.naming.Name getServiceName()
          Returns the Name of the group service of origin.
 java.lang.Class getType()
          Returns this object's type for purposes of caching and locking, as opposed to the underlying entity type.
 boolean hasAdds()
          Answers if there are any added memberships not yet committed to the database.
 boolean hasDeletes()
          Answers if there are any deleted memberships not yet committed to the database.
 int hashCode()
          Generates a hash code for the receiver.
 boolean hasMembers()
          Default implementation, overridden on EntityGroupImpl.
private  void initializeMembers()
          Cache the IEntityGroup members.
 boolean isDirty()
          Answers if there are any added or deleted memberships not yet committed to the database.
 boolean isEditable()
          Answers if this IEntityGroup can be changed or deleted.
 boolean isGroup()
           
protected  void primAddMember(IGroupMember gm)
          Adds the IGroupMember key to the appropriate member key cache by copying the cache, adding to the copy, and then replacing the original with the copy.
protected  java.util.Set primGetAllEntities(java.util.Set entities)
          Returns the Set of IEntities in our member Collection and, recursively, in the Collections of our members.
protected  java.util.Set primGetAllMembers(java.util.Set s)
          Returns the Set of IGroupMembers in our member Collection and, recursively, in the Collections of our members.
protected  void primRemoveMember(IGroupMember gm)
          Removes the IGroupMember key from the appropriate key cache, by copying the cache, removing the key from the copy and replacing the original with the copy.
 void primSetName(java.lang.String newName)
           
 void removeMember(IGroupMember gm)
          Removes IGroupMember gm from our member Map and, conversely, remove this from gm's group Map.
 void setCreatorID(java.lang.String newCreatorID)
           
 void setDescription(java.lang.String newDescription)
           
 void setLocalGroupService(IIndividualGroupService newIndividualGroupService)
          Sets the group service of origin.
private  void setMemberEntityKeys(java.util.Set newMemberEntityKeys)
           
private  void setMemberGroupKeys(java.util.Set newMemberGroupKeys)
           
private  void setMemberKeysInitialized(boolean newMemberKeysInitialized)
           
 void setName(java.lang.String newName)
          We used to check duplicate sibling names but no longer do.
 void setServiceName(javax.naming.Name newServiceName)
          Sets the service Name of the group service of origin.
 java.lang.String toString()
          Returns a String that represents the value of this object.
 void update()
          Delegate to the factory.
 void updateMembers()
          Delegate to the factory.
 
Methods inherited from class org.jasig.portal.groups.GroupMemberImpl
addGroup, castAndCopyHashSet, getAllContainingGroups, getCacheKey, getCompositeGroupService, getContainingGroups, getKey, getUnderlyingEntityIdentifier, isDeepMemberOf, isEntity, isKnownEntityType, isMemberOf, primGetAllContainingGroups, removeGroup, setGroupKeysInitialized
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.jasig.portal.groups.IGroupMember
getAllContainingGroups, getContainingGroups, getKey, getUnderlyingEntityIdentifier, isDeepMemberOf, isEntity, isMemberOf
 

Field Detail

creatorID

private java.lang.String creatorID

name

private java.lang.String name

description

private java.lang.String description

localGroupService

protected IIndividualGroupService localGroupService

leafEntityType

private java.lang.Class leafEntityType

memberGroupKeys

private java.util.Set memberGroupKeys

memberEntityKeys

private java.util.Set memberEntityKeys

memberKeysInitialized

private boolean memberKeysInitialized

addedMembers

private java.util.HashMap addedMembers

removedMembers

private java.util.HashMap removedMembers
Constructor Detail

EntityGroupImpl

public EntityGroupImpl(java.lang.String groupKey,
                       java.lang.Class entityType)
                throws GroupsException
EntityGroupImpl

Throws:
GroupsException
Method Detail

addMember

public void addMember(IGroupMember gm)
               throws GroupsException
Adds IGroupMember gm to our member Map and conversely, adds this to gm's group Map, after checking that the addition does not violate group rules. Remember that we have added it so we can update the database if necessary.

Specified by:
addMember in interface IEntityGroup
Parameters:
gm - org.jasig.portal.groups.IGroupMember
Throws:
GroupsException - is thrown if the member is a group and this group already has a group with the same name or if the addition of the group creates a circular reference.

areMemberKeysInitialized

protected boolean areMemberKeysInitialized()
Returns:
boolean

checkProspectiveMember

private void checkProspectiveMember(IGroupMember gm)
                             throws GroupsException
A member must share the entityType of its containing IEntityGroup. If it is a group, it must have a unique name within each of its containing groups and the resulting group must not contain a circular reference. Removed the requirement for unique group names. (03-04-2004, de)

Parameters:
gm - org.jasig.portal.groups.IGroupMember
Throws:
GroupsException

clearPendingUpdates

protected void clearPendingUpdates()
Clear out caches for pending adds and deletes of group members.


copyMemberEntityKeys

private java.util.Set copyMemberEntityKeys()
                                    throws GroupsException
Clone the member entity keys.

Returns:
Set
Throws:
GroupsException

copyMemberGroupKeys

private java.util.Set copyMemberGroupKeys()
                                   throws GroupsException
Clone the member group keys.

Returns:
Set
Throws:
GroupsException

contains

public boolean contains(IGroupMember gm)
                 throws GroupsException
Checks if GroupMember gm is a member of this.

Specified by:
contains in interface IGroupMember
Overrides:
contains in class GroupMemberImpl
Parameters:
gm - org.jasig.portal.groups.IGroupMember
Returns:
boolean
Throws:
GroupsException

deepContains

public boolean deepContains(IGroupMember gm)
                     throws GroupsException
Checks recursively if GroupMember gm is a member of this.

Specified by:
deepContains in interface IGroupMember
Overrides:
deepContains in class GroupMemberImpl
Parameters:
gm - org.jasig.portal.groups.IGroupMember
Returns:
boolean
Throws:
GroupsException

delete

public void delete()
            throws GroupsException
Delegates to the factory.

Specified by:
delete in interface IEntityGroup
Throws:
GroupsException - if the delete cannot be performed.

equals

public boolean equals(java.lang.Object obj)
Description copied from interface: IGroupMember
Answers if Object o is an IGroupMember that refers to the same underlying entity(ies) as this.

Specified by:
equals in interface IGroupMember
Overrides:
equals in class java.lang.Object
Parameters:
obj - the Object to compare with
Returns:
true if these Objects are equal; false otherwise.
See Also:
Hashtable

getAddedMembers

public java.util.HashMap getAddedMembers()
Returns:
java.util.HashMap

getAllEntities

public java.util.Iterator getAllEntities()
                                  throws GroupsException
Returns an Iterator over the Set of this IEntityGroup's recursively-retrieved members that are IEntities.

Specified by:
getAllEntities in interface IGroupMember
Overrides:
getAllEntities in class GroupMemberImpl
Returns:
java.util.Iterator
Throws:
GroupsException

getAllMembers

public java.util.Iterator getAllMembers()
                                 throws GroupsException
Returns an Iterator over the Set of recursively-retrieved IGroupMembers that are members of this IEntityGroup.

Specified by:
getAllMembers in interface IGroupMember
Overrides:
getAllMembers in class GroupMemberImpl
Returns:
java.util.Iterator
Throws:
GroupsException

getCompositeEntityIdentifier

protected CompositeEntityIdentifier getCompositeEntityIdentifier()
Returns the EntityIdentifier cast to a CompositeEntityIdentifier so that its service nodes can be pushed and popped.

Returns:
CompositeEntityIdentifier

getCreatorID

public java.lang.String getCreatorID()
Description copied from interface: IEntityGroup
Returns the name of the group creator. May be null.

Specified by:
getCreatorID in interface IEntityGroup
Returns:
java.lang.String

getDescription

public java.lang.String getDescription()
Description copied from interface: IEntityGroup
Returns the group description, which may be null.

Specified by:
getDescription in interface IEntityGroup
Returns:
java.lang.String

getEntities

public java.util.Iterator getEntities()
                               throws GroupsException
Returns an Iterator over this IEntityGroup's members that are IEntities.

Specified by:
getEntities in interface IGroupMember
Overrides:
getEntities in class GroupMemberImpl
Returns:
java.util.Iterator
Throws:
GroupsException

getEntityIdentifier

public EntityIdentifier getEntityIdentifier()
Specified by:
getEntityIdentifier in interface IBasicEntity
Returns:
EntityIdentifier

getEntityKey

public java.lang.String getEntityKey()
Returns the key of the underyling entity.

Returns:
java.lang.String

getEntityType

public java.lang.Class getEntityType()
Returns the entity type of this groups's leaf members.

Specified by:
getEntityType in interface IGroupMember
Returns:
java.lang.Class
See Also:
EntityTypes

getGroupID

public java.lang.String getGroupID()
Returns:
String

getLeafType

public java.lang.Class getLeafType()
Returns the entity type of this groups's members.

Specified by:
getLeafType in interface IGroupMember
Returns:
java.lang.Class
See Also:
EntityTypes

getLocalGroupService

protected IIndividualGroupService getLocalGroupService()
Returns:
IIndividualGroupService

getLocalKey

public java.lang.String getLocalKey()
Returns the key from the group service of origin.

Specified by:
getLocalKey in interface IEntityGroup
Returns:
String

getMemberEntities

protected java.util.Iterator getMemberEntities()
                                        throws GroupsException
Returns an Iterator over the entities in our member Collection.

Returns:
java.util.Iterator
Throws:
GroupsException

getMemberEntityKeys

private java.util.Set getMemberEntityKeys()
                                   throws GroupsException
Returns:
java.util.Set
Throws:
GroupsException

getMemberGroupKeys

private java.util.Set getMemberGroupKeys()
                                  throws GroupsException
Returns:
java.util.Set
Throws:
GroupsException

getMemberGroupNamed

public IEntityGroup getMemberGroupNamed(java.lang.String name)
                                 throws GroupsException
Returns the named member IEntityGroup.

Specified by:
getMemberGroupNamed in interface IGroupMember
Overrides:
getMemberGroupNamed in class GroupMemberImpl
Parameters:
name - java.lang.String
Returns:
org.jasig.portal.groups.IEntityGroup
Throws:
GroupsException

getMemberGroups

protected java.util.Iterator getMemberGroups()
                                      throws GroupsException
Returns an Iterator over the groups in our member Collection.

Returns:
java.util.Iterator
Throws:
GroupsException

getMembers

public java.util.Iterator getMembers()
                              throws GroupsException
Returns an Iterator over the GroupMembers in our member Collection.

Specified by:
getMembers in interface IGroupMember
Overrides:
getMembers in class GroupMemberImpl
Returns:
java.util.Iterator
Throws:
GroupsException

getName

public java.lang.String getName()
Description copied from interface: IEntityGroup
Returns the group name.

Specified by:
getName in interface IEntityGroup
Returns:
java.lang.String

getRemovedMembers

public java.util.HashMap getRemovedMembers()
Returns:
java.util.HashMap

getService

protected GroupService getService()
                           throws GroupsException
Returns:
IGroupService
Throws:
GroupsException

getServiceName

public javax.naming.Name getServiceName()
Returns the Name of the group service of origin.

Specified by:
getServiceName in interface IEntityGroup
Returns:
javax.naming.Nme

getType

public java.lang.Class getType()
Returns this object's type for purposes of caching and locking, as opposed to the underlying entity type.

Specified by:
getType in interface IGroupMember
Overrides:
getType in class GroupMemberImpl
Returns:
java.lang.Class

hasAdds

public boolean hasAdds()
Answers if there are any added memberships not yet committed to the database.

Returns:
boolean

hasDeletes

public boolean hasDeletes()
Answers if there are any deleted memberships not yet committed to the database.

Returns:
boolean

hashCode

public int hashCode()
Generates a hash code for the receiver. This method is supported primarily for hash tables, such as those provided in java.util.

Specified by:
hashCode in interface IGroupMember
Overrides:
hashCode in class GroupMemberImpl
Returns:
an integer hash code for the receiver
See Also:
Hashtable

hasMembers

public boolean hasMembers()
                   throws GroupsException
Description copied from class: GroupMemberImpl
Default implementation, overridden on EntityGroupImpl.

Specified by:
hasMembers in interface IGroupMember
Overrides:
hasMembers in class GroupMemberImpl
Returns:
boolean
Throws:
GroupsException

initializeMembers

private void initializeMembers()
                        throws GroupsException
Cache the IEntityGroup members.

Throws:
GroupsException

isDirty

public boolean isDirty()
Answers if there are any added or deleted memberships not yet committed to the database.

Returns:
boolean

isEditable

public boolean isEditable()
                   throws GroupsException
Answers if this IEntityGroup can be changed or deleted.

Specified by:
isEditable in interface IEntityGroup
Returns:
boolean
Throws:
GroupsException

isGroup

public boolean isGroup()
Specified by:
isGroup in interface IGroupMember
Overrides:
isGroup in class GroupMemberImpl
Returns:
boolean

primAddMember

protected void primAddMember(IGroupMember gm)
                      throws GroupsException
Adds the IGroupMember key to the appropriate member key cache by copying the cache, adding to the copy, and then replacing the original with the copy. At this point, gm does not yet have this in its containing group cache. That cache entry is not added until update(), when changes are committed to the store.

Parameters:
gm - org.jasig.portal.groups.IGroupMember
Throws:
GroupsException

primGetAllEntities

protected java.util.Set primGetAllEntities(java.util.Set entities)
                                    throws GroupsException
Returns the Set of IEntities in our member Collection and, recursively, in the Collections of our members.

Parameters:
entities - a Set that IEntity-GroupMembers are added to.
Returns:
java.util.Set
Throws:
GroupsException

primGetAllMembers

protected java.util.Set primGetAllMembers(java.util.Set s)
                                   throws GroupsException
Returns the Set of IGroupMembers in our member Collection and, recursively, in the Collections of our members.

Parameters:
s - java.lang.Set - a Set that members are added to.
Returns:
java.util.Set
Throws:
GroupsException

primRemoveMember

protected void primRemoveMember(IGroupMember gm)
                         throws GroupsException
Removes the IGroupMember key from the appropriate key cache, by copying the cache, removing the key from the copy and replacing the original with the copy. At this point, gm still has this in its containing groups cache. That cache entry is not removed until update(), when changes are committed to the store.

Parameters:
gm - org.jasig.portal.groups.IGroupMember
Throws:
GroupsException

primSetName

public void primSetName(java.lang.String newName)
Parameters:
newName - java.lang.String

removeMember

public void removeMember(IGroupMember gm)
                  throws GroupsException
Removes IGroupMember gm from our member Map and, conversely, remove this from gm's group Map. Remember that we have removed it so we can update the database, if necessary.

Specified by:
removeMember in interface IEntityGroup
Parameters:
gm - org.jasig.portal.groups.IGroupMember
Throws:
GroupsException

setCreatorID

public void setCreatorID(java.lang.String newCreatorID)
Specified by:
setCreatorID in interface IEntityGroup
Parameters:
newCreatorID - java.lang.String

setDescription

public void setDescription(java.lang.String newDescription)
Specified by:
setDescription in interface IEntityGroup
Parameters:
newDescription - java.lang.String

setLocalGroupService

public void setLocalGroupService(IIndividualGroupService newIndividualGroupService)
                          throws GroupsException
Description copied from interface: IEntityGroup
Sets the group service of origin.

Specified by:
setLocalGroupService in interface IEntityGroup
Parameters:
newIndividualGroupService - IIndividualGroupService
Throws:
GroupsException

setMemberKeysInitialized

private void setMemberKeysInitialized(boolean newMemberKeysInitialized)
Parameters:
newMemberKeysInitialized - boolean

setMemberEntityKeys

private void setMemberEntityKeys(java.util.Set newMemberEntityKeys)
Parameters:
newMemberEntityKeys - Set

setMemberGroupKeys

private void setMemberGroupKeys(java.util.Set newMemberGroupKeys)
Parameters:
newMemberGroupKeys - Set

setName

public void setName(java.lang.String newName)
             throws GroupsException
We used to check duplicate sibling names but no longer do.

Specified by:
setName in interface IEntityGroup
Parameters:
newName - java.lang.String
Throws:
GroupsException

setServiceName

public void setServiceName(javax.naming.Name newServiceName)
                    throws GroupsException
Sets the service Name of the group service of origin.

Throws:
GroupsException

toString

public java.lang.String toString()
Returns a String that represents the value of this object.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the receiver

update

public void update()
            throws GroupsException
Delegate to the factory.

Specified by:
update in interface IEntityGroup
Throws:
GroupsException - if the update cannot be performed.

updateMembers

public void updateMembers()
                   throws GroupsException
Delegate to the factory.

Specified by:
updateMembers in interface IEntityGroup
Throws:
GroupsException - if the update cannot be performed.