org.jrabbit.base.data.cache
Class GroupedCache<T extends Destroyable & Referenced>

java.lang.Object
  extended by org.jrabbit.base.data.structures.BaseKeyedContainer<T>
      extended by org.jrabbit.base.data.cache.Cache<T>
          extended by org.jrabbit.base.data.cache.GroupedCache<T>
Type Parameters:
T - The type of object to contain in the GroupedCache.
All Implemented Interfaces:
java.lang.Iterable<T>, Destroyable, Factory<T>, Accepter<T>, Container<T>, KeyedContainer<T>, Remover<T>
Direct Known Subclasses:
FontCache, ImageCache

public class GroupedCache<T extends Destroyable & Referenced>
extends Cache<T>

This class extends Cache to provide some additional organizational functionality. With GroupedCaches, the developer has the option of building groups of references that make organizing data easier. The groups are GroupTrees of Strings. There is no actual organization of the data itself, simply the references. Because of this, the core data is organized identically to that of a Cache, and all additional functionality is separate. In the comments for this class, certain groups are referenced as "top level" and others are "lower level." This is based on the tree-like behavior of GroupTrees. A GroupedCache only accesses the groups that have been directly added to it. These are "top level," because they lie directly accessible to the GroupedCache. However, the GroupedCache has no built-in ability to directly control the children of these groups, and so they are "lower-level" - out of sight unless the developer manually controls them (which is, in fact, the idea).

Author:
Chris Molini

Nested Class Summary
protected  class GroupedCache.EntryList
          Class that provides an Iterator through the group of objects that a list of Strings references, allowing iteration through selected sections of the Cache.
 
Field Summary
protected  GroupTree<java.lang.String> groups
          The groups.
 
Fields inherited from class org.jrabbit.base.data.structures.BaseKeyedContainer
contents, factory
 
Constructor Summary
GroupedCache(Factory<T> factory)
          Creates am empty GroupCache with no defined groups.
 
Method Summary
 boolean addGroup(java.lang.String groupName)
          Creates a new, empty group with the specified key.
 boolean addGroup(java.lang.String groupName, GroupTree<java.lang.String> group)
          Adds an already defined GroupTree to the Cache, under the indicated name.
 boolean addIntoGroup(java.lang.String groupName, java.lang.String... references)
          Adds a series of references into a top-level group.
 boolean addIntoGroup(java.lang.String reference, java.lang.String groupName)
          Adds the reference to the indicated top-level group.
 void addIntoGroup(java.lang.String groupName, T... objects)
          Adds a series of object references into a top-level group.
 boolean addIntoGroup(T object, java.lang.String groupName)
          Adds an already defined object into the indicated group.
 boolean clearGroups()
          Completely removes all groups.
 boolean destroyGroup(java.lang.String groupName)
          Attempts to completely eradicate the specified top-level group, both destroying and removing every object it references, and removing it from the list of available groups.
 boolean disgroup(java.lang.String groupName)
          Attempts to completely remove a top-level group from the GroupedCache, removing the GroupTree under the specified reference.
 boolean emptyGroup(java.lang.String groupName)
          Attempts to empty the specified top-level group.
 java.util.LinkedHashMap<java.lang.String,GroupTree<java.lang.String>> groups()
          Accesses the list of top-level groups.
 java.lang.Iterable<T> objectsReferenced(java.lang.Iterable<java.lang.String> list)
          Provides a convenience method to iterate through all objects referenced by the supplied list of Strings.
 java.lang.Iterable<T> objectsReferenced(java.lang.String groupName)
          Provides a convenience method to iterate through all objects referenced by the indicated top-level group.
 boolean removeFromGroup(java.lang.String reference, java.lang.String groupName)
          Attempts to remove an object from the indicated list.
 boolean wipeGroup(java.lang.String groupName)
          Attempts to clear the contents of a top-level group from the Cache.
 
Methods inherited from class org.jrabbit.base.data.cache.Cache
destroy, get, get, removeAndDestroy, setTo
 
Methods inherited from class org.jrabbit.base.data.structures.BaseKeyedContainer
add, add, add, add, clear, contains, contains, create, createMap, factory, iterator, remove, remove, remove, remove, setFactory, size
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

groups

protected GroupTree<java.lang.String> groups
The groups. A group's "name" is the String it is keyed to.

Constructor Detail

GroupedCache

public GroupedCache(Factory<T> factory)
Creates am empty GroupCache with no defined groups.

Parameters:
factory - The Factory to use to create new objects.
Method Detail

groups

public java.util.LinkedHashMap<java.lang.String,GroupTree<java.lang.String>> groups()
Accesses the list of top-level groups.

Returns:
The collection of groups that contain references to resources in the GroupedCache.

addIntoGroup

public boolean addIntoGroup(java.lang.String reference,
                            java.lang.String groupName)
Adds the reference to the indicated top-level group. Note that this does not access lower-level groups. If the reference is not in the Cache, then an object is created from it and added. If you want to add a reference to a lower level group, you need to retrieve the top-level group that contains it, then trawl through its children to find the desired group

Parameters:
reference - The reference to an object in the Cache.
groupName - The group identifier.
Returns - true if the group exists and it accepted the add. A false value indicates that the indicated group does not exist.

addIntoGroup

public boolean addIntoGroup(java.lang.String groupName,
                            java.lang.String... references)
Adds a series of references into a top-level group.

Parameters:
references - The list of references to add.
groupName - The group identifier.
Returns:
If the group existed and the operation was successful, returns true; otherwise returns false.

addIntoGroup

public boolean addIntoGroup(T object,
                            java.lang.String groupName)
Adds an already defined object into the indicated group. If the object's reference is not in the Cache, it is also added.

Parameters:
object - The object we wish to reference.
groupName - The group identifier.
Returns - true if the group exists and it accepted the add. A false value indicates that the indicated group does not exist.

addIntoGroup

public void addIntoGroup(java.lang.String groupName,
                         T... objects)
Adds a series of object references into a top-level group. If any of the objects aren't in the Cache, they are added.

Parameters:
references - The list of objects whose references we wish to add.
groupName - The group identifier.

removeFromGroup

public boolean removeFromGroup(java.lang.String reference,
                               java.lang.String groupName)
Attempts to remove an object from the indicated list.

Parameters:
reference - The reference we want to remove.
groupName - The group identifier.
Returns:
True if the removal was a success. False if either the group did not exist, or if the group did not contain the reference.

addGroup

public boolean addGroup(java.lang.String groupName)
Creates a new, empty group with the specified key. If a group already exists under the supplied name, then no changes occur.

Parameters:
groupName - The String used to identify the Group.
Returns:
True if there was no group with the specified name, false if there was.

addGroup

public boolean addGroup(java.lang.String groupName,
                        GroupTree<java.lang.String> group)
Adds an already defined GroupTree to the Cache, under the indicated name. If a group already exists under that name, then the two groups are combined; if not, then the group is simply added.

Parameters:
groupName - The reference to key to the group.
group - The group to add.
Returns:
False if a group already existed under the supplied String; true if not, and the group was

emptyGroup

public boolean emptyGroup(java.lang.String groupName)
Attempts to empty the specified top-level group. This removes all contained references and destroys all subgroups, but leaves the group in available in the GroupedCache and does not affect any actual Cache data.

Parameters:
groupName - The group identifier.
Returns:
True if a group was found and cleared; false if none exist under the supplied key.

disgroup

public boolean disgroup(java.lang.String groupName)
Attempts to completely remove a top-level group from the GroupedCache, removing the GroupTree under the specified reference. After this call, that group is no longer available; however, Cache data is unchanged.

Parameters:
groupName - The group identifier.
Returns:
True if a group was found and removed; false if no group was found to remove.

wipeGroup

public boolean wipeGroup(java.lang.String groupName)
Attempts to clear the contents of a top-level group from the Cache. All objects that the group (and its children) contains references for are removed from the Cache and destroyed, and the group is cleared. However, the group remains present in the list of groups - it is simply emptied.

Parameters:
groupName - The group identifier.
Returns:
True if a group was found and its contents were destroyed; false if no group was found to remove.

destroyGroup

public boolean destroyGroup(java.lang.String groupName)
Attempts to completely eradicate the specified top-level group, both destroying and removing every object it references, and removing it from the list of available groups. This is the most heavy-duty group removal method; it destroys Cache data and edits the group list.

Parameters:
groupName - The group identifier.
Returns:
True if a group was found and annihilated; false if no group was found to destroy.

clearGroups

public boolean clearGroups()
Completely removes all groups. Cache data is left alone.

Returns:
Whether or not there were any groups to remove - if false is returned, there were no groups to begin with.

objectsReferenced

public java.lang.Iterable<T> objectsReferenced(java.lang.String groupName)
Provides a convenience method to iterate through all objects referenced by the indicated top-level group.

Parameters:
groupName - The group identifier.
Returns:
An Iterable that will cycle through all objects the Cache maps to the references in the specified group. If no group is found, returns null.

objectsReferenced

public java.lang.Iterable<T> objectsReferenced(java.lang.Iterable<java.lang.String> list)
Provides a convenience method to iterate through all objects referenced by the supplied list of Strings.

Parameters:
list - The list of references to use while iteration occurs.
Returns:
If the supplied list is null, then returns null. Otherwise, returns an iterable that cycles through the GroupTree and accesses the objects the Cache has keyed to the references.