001: /**
002: * $Id: CMCUser.java,v 1.2 2007/01/26 03:47:48 portalbld Exp $
003: * Copyright 2005 Sun Microsystems, Inc. All
004: * rights reserved. Use of this product is subject
005: * to license terms. Federal Acquisitions:
006: * Commercial Software -- Government Users
007: * Subject to Standard License Terms and
008: * Conditions.
009: *
010: * Sun, Sun Microsystems, the Sun logo, and Sun ONE
011: * are trademarks or registered trademarks of Sun Microsystems,
012: * Inc. in the United States and other countries.
013: */package com.sun.portal.community.mc;
014:
015: import java.util.Set;
016: import java.util.Properties;
017: import com.sun.portal.community.mc.CMCRolePrincipal;
018:
019: /**
020: * Describes the relationship between a user and communities.
021: * <br><br>
022: * Clients obtain instances of <CODE>CommunityUser</CODE> objects
023: * through a <CODE>CommunityFactory</CODE> factory object.
024: * <br><br>
025: * <CODE>CommunityUser</CODE> objects operate from the
026: * perspective of the user.
027: * For example, the client has a user ID, and they want
028: * to ask questions about the user's relationship
029: * with communities.
030: * Contrast this with a <CODE>CommunityNode</CODE>
031: * object. <CODE>CommunityNode</CODE> objects operate from the
032: * perspective of a given community. For example,
033: * the client has community principal, and they want to ask
034: * questions and perform operations
035: * on that given community node identified by the community
036: * principal.
037: * <br><br>
038: * Community user implementations are not expected to be thread-safe; the same
039: * <CODE>CommunityUser</CODE> object should not be used by
040: * multiple threads concurrently.
041: * <br><br>
042: * The lifecycle of a community user is under control of the client application.
043: * The lifecycle usage pattern depends on the type of application, but must
044: * be determined with the knowledge that any particular community user cannot be
045: * assumed to be thread safe. For example, a single-threaded, single-user
046: * application can safely use the same community user object for the lifetime
047: * of the application. A web application should obtain a new community user
048: * object for each request (in other words, each thread).
049: * <br><br>
050: * Persistent changes affected through this interface commit immediately.
051: */
052: public interface CMCUser {
053: /**
054: * Initialize this <CODE>CommunityUser</CODE> object.
055: * <br><br>
056: * <CODE>CommunityUser</CODE> objects must be initialized before they are used.
057: * This method is called either directly or indirectly
058: * by the <CODE>CommunityFactory</CODE>
059: * object before it returns <CODE>CommunityUser</CODE> instances.
060: * Clients should not call this method directly.
061: * <br><br>
062: * The properties required are community user implementation
063: * dependent.
064: * @param properties Properties used by the community user
065: * implementation to initialize the object instance.
066: * The exact properties used are
067: * community user implementation dependent.
068: * @throws com.sun.portal.community.mc.CommunityException If there was a problem initializing this community user.
069: * @param userId A <CODE>String</CODE>, the user ID of the community user.
070: */
071: public void init(Properties properties, String userId)
072: throws CMCException;
073:
074: /**
075: * Get the user ID of the community user.
076: * @return A <CODE>String</CODE>, the community user ID.
077: */
078: public String getUserId();
079:
080: /**
081: * Get the community membership for the community user,
082: * for all possible roles.
083: * <br><br>
084: * Calling this method is equivalent to calling
085: * <CODE>getMembership(null)</CODE>. This method simply combines
086: * the result of <code>getMembershipByName()</code> and
087: * <code>getMembershipByRole()</code>.
088: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
089: * the community principal - role tuples indicating the user's
090: * role in their member communities.
091: * @throws com.sun.portal.community.mc.CommunityException If a
092: * problem occured getting the membership.
093: * @see #getMembership(Set)
094: * @see #getMembershipByName()
095: * @see #getMembershipByRole()
096: */
097: public Set getMembership() throws CMCException;
098:
099: /**
100: * Get the community membership for the community user,
101: * for all possible roles. This method only returns the user's
102: * user roles, not the user's community roles.
103: * <br><br>
104: * Calling this method is equivalent to calling
105: * <CODE>getMembershipByName(null)</CODE>.
106: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
107: * the community principal - role tuples indicating the user's
108: * role in their member communities.
109: * @throws com.sun.portal.community.mc.CommunityException If a
110: * problem occured getting the membership.
111: * @see #getMembershipByName(Set)
112: */
113: public Set getMembershipByName() throws CMCException;
114:
115: /**
116: * Get the community membership for the community user,
117: * for all possible roles. This method only returns the
118: * user's community roles, not the user's user roles.
119: * <br><br>
120: * Calling this method is equivalent to calling
121: * <CODE>getMembershipByRole(null)</CODE>.
122: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
123: * the community principal - role tuples indicating the user's
124: * role in their member communities.
125: * @throws com.sun.portal.community.mc.CommunityException If a
126: * problem occured getting the membership.
127: * @see #getMembershipByRole(Set)
128: */
129: public Set getMembershipByRole() throws CMCException;
130:
131: /**
132: * Get the community user's membership for the given set of roles.
133: * <br><br>
134: * Calling this method with a null rolePrincipals parameter is equivalent
135: * to calling <CODE>getMembership()</CODE> (no argument).
136: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>,
137: * the roles to check for membership.
138: * @throws com.sun.portal.community.mc.CommunityException
139: * If there was a problem getting the membership communities for the
140: * community user.
141: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
142: * the community principal - role tuples indicating the user's
143: * role in their member communities.
144: * @see #getMembership()
145: * @see #getMembershipByName(Set)
146: * @see #getMembershipByRole(Set)
147: */
148: public Set getMembership(Set rolePrincipals) throws CMCException;
149:
150: /**
151: * Get the community user's membership for the given set of roles. This
152: * method only returns the user roles, and not community roles.
153: * <br><br>
154: * Calling this method with a null rolePrincipals parameter is equivalent
155: * to calling <CODE>getMembershipByName()</CODE> (no argument).
156: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>,
157: * the roles to check for membership.
158: * @throws com.sun.portal.community.mc.CommunityException
159: * If there was a problem getting the membership.
160: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
161: * the community principal - role tuples indicating the user's
162: * role in their member communities.
163: * @see #getMembershipByName()
164: */
165: public Set getMembershipByName(Set rolePrincipals)
166: throws CMCException;
167:
168: /**
169: * Get the community user's membership for the given set of roles. This
170: * method only returns the community roles, and not user roles.
171: * <br><br>
172: * Calling this method with a null rolePrincipals parameter is equivalent
173: * to calling <CODE>getMembershipByRole()</CODE> (no argument).
174: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>,
175: * the roles to check for membership.
176: * @throws com.sun.portal.community.mc.CommunityException
177: * If there was a problem getting the membership.
178: * @return A <CODE>Set</CODE> of <CODE>ConfigKey</CODE> objects,
179: * the community principal - role tuples indicating the user's
180: * role in their member communities.
181: * @see #getMembershipByName()
182: */
183: public Set getMembershipByRole(Set rolePrincipals)
184: throws CMCException;
185:
186: /**
187: * Get the all communities accessible to the user.
188: * @return A <CODE>Set</CODE> of <CODE>CommunityPrincipal</CODE>
189: * objects, the communities that this community
190: * user may join.
191: * @throws com.sun.portal.community.mc.CommunityException If a problem
192: * occured getting the communities that this community user
193: * may join.
194: */
195: public Set getAvailable() throws CMCException;
196:
197: /**
198: * Does this community user have the given role in the given community?
199: * @param communityPrincipal A <CODE>CommunityPrincipal</CODE> object, the community principal to check.
200: * @param rolePrincipal A RolePrincipal object, the role to check.
201: * @throws com.sun.portal.community.mc.CommunityException If there was a problem checking if this community user has the role.
202: * @return A <CODE>boolean</CODE> indicating if this community user has
203: * the given role in the given community.
204: */
205: public boolean hasRole(CMCPrincipal communityPrincipal,
206: CMCRolePrincipal rolePrincipal) throws CMCException;
207:
208: /**
209: * Get the Display Profile documents for the community user, for all member communities,
210: * for all roles that the user has within these communities.
211: * <p>
212: * The values in the returned <CODE>ConfigTable</CODE> object
213: * are <CODE>byte[]</CODE> objects. The <CODE>byte[]</CODE>
214: * is a UTF-8 encoded character stream.
215: * @param lastReadTimes A <CODE>ConfigTable</CODE> of <CODE>Long</CODE> objects
216: * describing the time that the client last
217: * read the DP documents for the user.
218: * <br><br>
219: * The community user implementation uses the last read times to
220: * optimize it's access to the persistent store. It must not
221: * return DP documents that have not been modified since the
222: * last read time specified.
223: * <br><br>
224: * If the client wants to retrieve DP document irrespective
225: * of the time it was last read, it should pass an empty
226: * <CODE>ConfigTable</CODE> in place of this parameter.
227: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the DP documents for the user.
228: * @return A <CODE>ConfigTable</CODE> containing
229: * <CODE>byte[]</CODE> objects, the DP documents for the user.
230: */
231: public ConfigTable getDPDocuments(ConfigTable lastReadTimes)
232: throws CMCException;
233:
234: public ConfigTable getDPDocuments(ConfigTable lastReadTimes,
235: Set membership) throws CMCException;
236:
237: /** Returns the time when a user was assigned to a role in community.
238: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
239: * operation is supported in this community.
240: * @return time in milliseconds when a user was assigned to a role in community. Returns -1 if the time is unknown
241: * user is not in the role or time is unknown
242: */
243: public long getRoleCreationTime(CMCPrincipal cp,
244: CMCRolePrincipal rolePrincipal) throws CMCException;
245: }
|