001: /* Copyright 2001, 2002 The JA-SIG Collaborative. All rights reserved.
002: * See license distributed with this file and
003: * available online at http://www.uportal.org/license.html
004: */
005:
006: package org.jasig.portal.groups;
007:
008: import java.util.Iterator;
009:
010: import org.jasig.portal.EntityIdentifier;
011: import org.jasig.portal.IBasicEntity;
012:
013: /**
014: * An <code>IGroupMember</code> defines common behavior for both the leaf
015: * <code>IEntity</code> and composite <code>IEntityGroup</code> sub-types
016: * that together make up a Groups structure.
017: * <p>
018: * An <code>IGroupMember</code> can answer both its parents and its children but
019: * has no api for adding or removing them. These methods are defined on
020: * the composite type, <code>IEntityGroup</code>, since you add a member to a
021: * group, and not vice versa.
022: * <p>
023: * Because it extends <code>IBasicEntity</code>, an <code>IGroupMember</code> has
024: * an <code>EntityIdentifier</code> that can be used to cache and lock it. A leaf
025: * <code>IGroupMember</code> also has a separate <code>EntityIdentifier</code> for
026: * its underlying entity. This second <code>EntityIdentifier</code> is used to
027: * create and record group memberships. In the case of a composite (non-leaf)
028: * <code>IGroupMember</code>, both <code>EntityIdentifiers</code> are the same.
029: * <p>
030: * Take care to implement <code>equals()</code> and <code>hashCode()</code> so
031: * that duplicates returned from "deep" methods can be recognized.
032: *
033: * @author Dan Ellentuck
034: * @version $Revision: 34758 $
035: */
036: public interface IGroupMember extends IBasicEntity {
037: /**
038: * Answers if <code>IGroupMember</code> gm is a member of <code>this</code>.
039: * @return boolean
040: * @param gm org.jasig.portal.groups.IGroupMember
041: */
042: public boolean contains(IGroupMember gm) throws GroupsException;
043:
044: /**
045: * Answers if <code>IGroupMember</code> gm is a recursive member of <code>this</code>.
046: * @return boolean
047: * @param gm org.jasig.portal.groups.IGroupMember
048: */
049: public boolean deepContains(IGroupMember gm) throws GroupsException;
050:
051: /**
052: * Answers if Object o is an <code>IGroupMember</code> that refers to the same underlying
053: * entity(ies) as <code>this</code>.
054: * @param o
055: * @return boolean
056: */
057: public boolean equals(Object o);
058:
059: /**
060: * Returns an <code>Iterator</code> over the <code>Set</code> of this
061: * <code>IGroupMember's</code> recursively-retrieved parent groups.
062: *
063: * @return java.util.Iterator
064: */
065: public Iterator getAllContainingGroups() throws GroupsException;
066:
067: /**
068: * Returns an <code>Iterator</code> over the <code>Set</code> of this
069: * <code>IGroupMember's</code> recursively-retrieved members that are
070: * <code>IEntities</code>.
071: * @return java.util.Iterator
072: */
073: public Iterator getAllEntities() throws GroupsException;
074:
075: /**
076: * Returns an <code>Iterator</code> over the <code>Set</code> of recursively-retrieved
077: * <code>IGroupMembers</code> that are members of <code>this</code>.
078: * @return java.util.Iterator
079: */
080: public Iterator getAllMembers() throws GroupsException;
081:
082: /**
083: * Returns an <code>Iterator</code> over this <code>IGroupMember's</code> parent groups.
084: * @return java.util.Iterator
085: */
086: public Iterator getContainingGroups() throws GroupsException;
087:
088: /**
089: * Returns an <code>Iterator</code> over this <code>IGroupMember's</code>
090: * members that are <code>IEntities</code>.
091: * @return java.util.Iterator
092: */
093: public Iterator getEntities() throws GroupsException;
094:
095: /**
096: * Returns the underlying entity type. For an <code>IEntityGroup</code>, this is
097: * analagous to <code>Class</code> as applied to an <code>Array</code>; it is an
098: * attribute of the group object. For an <code>IEntity</code>, it is the entity
099: * type of the group the entity belongs to, which may be any <code>Class</code>
100: * the underlying entity can be legally cast to. Thus, an <code>IEntity</code>
101: * with an underlying entity of type <code>Manager</code> could have an entity
102: * type of <code>Employee</code> as long as <code>Employee</code> was a
103: * superclass of <code>Manager</code>.
104: *
105: * @return java.lang.Class
106: */
107: public Class getEntityType();
108:
109: /**
110: * Returns the key of the underlying entity.
111: * @return String
112: */
113: public String getKey();
114:
115: /**
116: * @see #getEntityType()
117: */
118: public Class getLeafType();
119:
120: /**
121: * Returns the named <code>IEntityGroup</code> from our members <code>Collection</code>.
122: * @return org.jasig.portal.groups.IEntityGroup
123: * @param name java.lang.String
124: */
125: public IEntityGroup getMemberGroupNamed(String name)
126: throws GroupsException;
127:
128: /**
129: * Returns an <code>Iterator</code> over the <code>IGroupMembers</code> in our
130: * member <code>Collection</code>.
131: * @return java.util.Iterator
132: */
133: public Iterator getMembers() throws GroupsException;
134:
135: /**
136: * Returns the type of the underlying entity. For a group this will be
137: * <code>IEntityGroup</code>. For an entity, it will be the type of the
138: * underlying <code>EntityIdentifier</code>.
139: *
140: * @return java.lang.Class
141: */
142: public Class getType();
143:
144: /**
145: * Returns <code>EntityIdentifier</code> for this <code>IGroupMember's</code>
146: * underlying entity. In the case of an <code>IEntityGroup</code>, it will
147: * be the <code>EntityIdentifier</code> for <code>this</code>. In the case
148: * of an <code>IEntity</code>, it will be the <code>EntityIdentifier</code>
149: * that identifies the underlying IPerson, ChannelDefinition, etc.
150: *
151: * @return org.jasig.portal.EntityIdentifier
152: */
153: public EntityIdentifier getUnderlyingEntityIdentifier();
154:
155: /**
156: * @return int
157: */
158: public int hashCode();
159:
160: /**
161: * Answers if this <code>IGroupMember</code> has any members.
162: * @return boolean
163: */
164: public boolean hasMembers() throws GroupsException;
165:
166: /**
167: * Answers if <code>this</code> is a recursive member of <code>IGroupMember</code> gm.
168: * @return boolean
169: * @param gm org.jasig.portal.groups.IGroupMember
170: */
171: public boolean isDeepMemberOf(IGroupMember gm)
172: throws GroupsException;
173:
174: /**
175: * @return boolean
176: */
177: public boolean isEntity();
178:
179: /**
180: * @return boolean
181: */
182: public boolean isGroup();
183:
184: /**
185: * Answers if <code>this</code> is a member of <code>IGroupMember</code> gm.
186: * @return boolean
187: * @param gm org.jasig.portal.groups.IGroupMember
188: */
189: public boolean isMemberOf(IGroupMember gm) throws GroupsException;
190: }
|