001: /**
002: * $Id: CMCNode.java,v 1.3 2007/01/26 03:47:47 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: * Provides access to community membership and configuration.
021: * <br><br>
022: * Clients obtain instances of <CODE>CommunityNode</CODE> objects
023: * through a <CODE>CommunityFactory</CODE> object.
024: * <br><br>
025: * <CODE>CommunityNode</CODE> objects operate from the
026: * perspective of the community.
027: * For example, the client has a community principal identifying a community,
028: * and they want
029: * to ask questions about it or perform operations on it.
030: * Contrast this with a <CODE>CommunityUser</CODE>
031: * object. <CODE>CommunityUser</CODE> objects operate from the
032: * perspective of a given user. For example,
033: * the client has a user ID, and they want to ask questions and perform operations
034: * relating to the user's relation to a set of communities.
035: * <br><br>
036: * Community node implementations are not expected to be thread-safe; the same
037: * <CODE>CommunityNode</CODE> object should not be used by
038: * multiple threads concurrently.
039: * <br><br>
040: * The lifecycle of a community node is under control of the client application.
041: * The lifecycle usage pattern depends on the type of application, but must
042: * be determined with the knowledge that any particular community node cannot be
043: * assumed to be thread safe. For example, a single-threaded, single-user
044: * application can safely use the same community node object for the lifetime
045: * of the application. A web application should obtain a new community node
046: * object for each request (in other words, each thread).
047: * <br><br>
048: * This interface contains a set of methods that indicate the capabilities of the
049: * underlying <CODE>CommunityNode</CODE> implementation
050: * (see <CODE>supports*()</CODE>).
051: * These methods are used by clients to distinguish between different classes
052: * of communities. For example, if a client wants to add users
053: * to a community, they must test the target community
054: * node first by calling <CODE>supportsAddUsers()</CODE>.
055: * In cases where an community node
056: * implementation returns false from a <CODE>supportsX()</CODE> method,
057: * the corresponding
058: * X method is required to throw <CODE>UnsupportedOperationException</CODE>.
059: * The operations that a community node implementation is required to support
060: * are:
061: * <ul>
062: * <li>init()
063: * <li>getCommunityPrincipal()
064: * <li>getUsers()
065: * <li>supportsRole()
066: * <li>exists()
067: * <li>getDPDocuments()
068: * <li>getDPDocumentsLastModified()
069: * </ul>
070: * Consequently, these methods cannot be tested with an associated supports*()
071: * method.
072: * <br><br>
073: * The existence of a <CODE>CommunityNode</CODE> object does not indicate
074: * existence
075: * in a persistent store. It is up to the client to test persistent existence
076: * by calling the <CODE>exists()</CODE> method before performing
077: * operations that act on the
078: * community node persistently. Community node implementations must throw
079: * <CODE>CommunityException</CODE> if a persistent operation is attempted on a
080: * non-existent community node.
081: * <br><br>
082: * Persistent changes affected through this interface commit immediately.
083: */
084: public interface CMCNode {
085: /**
086: * Initialize this <CODE>CommunityNode</CODE> object.
087: * <br><br>
088: * <CODE>CommunityNode</CODE> objects must be initialized before they are used.
089: * This method is called either directly or indirectly
090: * by the <CODE>CommunityFactory</CODE>
091: * object before it returns CommunityNode instances.
092: * @param properties Properties used by the <CODE>CommunityNode</CODE>
093: * implementation to initialize the object instance.
094: * Clients should not call this method directly.
095: * <br><br>
096: * The exact properties used are
097: * <CODE>CommunityNode</CODE> implementation dependent.
098: * @param communityPrincipal A community principal that unqiuely identifies this <CODE>CommunityNode</CODE>.
099: * @throws com.sun.portal.community.mc.CommunityException If there was a problem initializing this object.
100: */
101: public void init(Properties properties,
102: CMCPrincipal communityPrincipal) throws CMCException;
103:
104: /**
105: * Get the community principal that identifies this object.
106: * @return A <CODE>CommunityPrincipal</CODE> object that unqiuely identifies this object.
107: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the community principal for this object.
108: */
109: public CMCPrincipal getCMCPrincipal() throws CMCException;
110:
111: /**
112: * Get all users of this community node.
113: *
114: * This method is equivalent to calling <CODE>getUsers(null)</CODE>.
115: * @return A <CODE>Set</CODE> of <CODE>String</CODE>s, the user IDs.
116: * @throws com.sun.portal.community.mc.CommunityException If there was a problem obtaining the user set.
117: */
118: public Set getUsers() throws CMCException;
119:
120: /**
121: * Get the users that have the given roles for this community node.
122: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipal</CODE>s, the roles to match to community node users to
123: * be returned.
124: * @return A <CODE>Set</CODE> of <CODE>String</CODE>s, the user IDs that match the given roles in the community node.
125: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the community node's users.
126: */
127: public Set getUsers(Set rolePrincipals) throws CMCException;
128:
129: /**
130: * Get the roles for this community node.
131: * @return A <CODE>Set</CODE> of <CODE>CMCRolePrincipal</CODE>s, the community roles
132: * @throws com.sun.portal.community.mc.CMCException if there was a problem getting the roles.
133: */
134: public Set getRoles() throws CMCException;
135:
136: /**
137: * Does this community node support the <CODE>getRoles()</CODE> operation?
138: * @return a <CODE>boolean</CODE> indicating if <CODE>getRoles()</CODE> is supported
139: * @see #getRoles()
140: * @throws com.sun.portal.community.mc.CommunityException If there is a problem determining if <CODE>getRoles()</CODE> is supported
141: */
142: public boolean supportsGetRoles() throws CMCException;
143:
144: /**
145: * Add users to this community node.
146: * @param uids A <CODE>Set</CODE> of <CODE>String</CODE>s, the user IDs to add to the community node.
147: * @param rolePrincipal A <CODE>RolePrincipal</CODE>, the role to add the given users to in the community node.
148: * @throws com.sun.portal.community.mc.CommunityException If there was a problem adding the users to the community node.
149: */
150: public void addUsers(Set uids, CMCRolePrincipal rolePrincipal)
151: throws CMCException;
152:
153: /**
154: * Does this community node support the <CODE>addUsers()</CODE> operation?
155: * @return a <CODE>boolean</CODE> indicating if <CODE>addUsers()</CODE> is supported
156: * @see #addUsers(java.util.Set, RolePrincipal)
157: * @throws com.sun.portal.community.mc.CommunityException If there is a problem determining if <CODE>addUsers()</CODE> is supported
158: */
159: public boolean supportsAddUsers() throws CMCException;
160:
161: /**
162: * Add a role to this community node.
163: * @param rolePrincipal The role to add to this CMC node.
164: * @throws com.sun.portal.community.mc.CMCException if there was a problem adding the role.
165: */
166: public void addRole(CMCRolePrincipal rolePrincipal)
167: throws CMCException;
168:
169: /**
170: * Does this community node support the <CODE>addRole()</CODE> operation?
171: * @return a <CODE>boolean</CODE> indicating if <CODE>addRole()</CODE> is supported
172: * @see #addRole(RolePrincipal)
173: * @throws com.sun.portal.community.mc.CMCException if there was a problem determining if the <code>addRole()</code> operation is supported.
174: */
175: public boolean supportsAddRole() throws CMCException;
176:
177: /**
178: * Remove users from roles in this community node.
179: * @param uids A <CODE>Set</CODE> of <CODE>Strings</CODE>, the user IDs to remove.
180: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>, the roles to remove the users from in the community node.
181: * @throws com.sun.portal.community.mc.CommunityException If there was a problem removing the users from the roles in the community.
182: */
183: public void removeUsers(Set uids, Set rolePrincipals)
184: throws CMCException;
185:
186: /**
187: * Does this community node support the <CODE>removeUsers()</CODE> operation?
188: * @return a <CODE>boolean</CODE> indicating if the <CODE>removeUsers()</CODE> operation is supported.
189: * @throws com.sun.portal.community.mc.CommunityException If there is a problem determining if <CODE>removeUsers()</CODE> is suppoorted.
190: * @see #removeUsers(Set, Set)
191: */
192: public boolean supportsRemoveUsers() throws CMCException;
193:
194: /**
195: * Remove a role from this community node.
196: * @param rolePrincipal the role to add.
197: * @throws com.sun.portal.community.mc.CMCException if a problem occurs adding the role.
198: */
199: public void removeRole(CMCRolePrincipal rolePrincipal)
200: throws CMCException;
201:
202: /**
203: * Does this community node support the <CODE>removeRole()</CODE>
204: * operation?
205: * @return a <CODE>boolean</CODE> indicating if the
206: * <CODE>removeRole()</CODE> operation is supported.
207: * @see #removeRole(CMCRolePrincipal)
208: * @throws com.sun.portal.community.mc.CMCException if a problem occurs when determining if the <code>removeRole() operation is supported.
209: */
210: public boolean supportsRemoveRole() throws CMCException;
211:
212: /**
213: * Does this community node support the given role?
214: * @param rolePrincipal A <CODE>RolePrincipal</CODE> to test.
215: * @throws com.sun.portal.community.mc.CommunityException If there was a problem testing support for the role.
216: * @return A boolean indicating if the role is supported by this community node implementation.
217: */
218: public boolean supportsRole(CMCRolePrincipal rolePrincipal)
219: throws CMCException;
220:
221: /**
222: * Create this community node persistently.
223: * <br><br>
224: * @throws com.sun.portal.community.mc.CommunityExistsException If the community node already exists.
225: * @throws com.sun.portal.community.mc.CommunityException If there was a problem creating the community node.
226: */
227: public void create() throws CMCExistsException, CMCException;
228:
229: /**
230: * Does this community node support the <CODE>create()</CODE> operation?
231: * @throws com.sun.portal.community.mc.CommunityException If there was a problem testing if the <CODE>create()</CODE> operation is supported.
232: * @return a <CODE>boolean</CODE> indicating if the <CODE>create()</CODE> operation is supported.
233: * @see #create()
234: */
235: public boolean supportsCreate() throws CMCException;
236:
237: /**
238: * Remove this community node persistently.
239: * @throws com.sun.portal.community.mc.CommunityException If there was a problem removing this community node persistently.
240: */
241: public void remove() throws CMCException;
242:
243: /**
244: * Does this community node support the <CODE>remove()</CODE> operation?
245: * @throws com.sun.portal.community.mc.CommunityException If there was a problem determining if the <CODE>remove()</CODE> operation is supported.
246: * @return a <CODE>boolean</CODE> indicating if the remove() operation is supported.
247: * @see #remove()
248: */
249: public boolean supportsRemove() throws CMCException;
250:
251: /**
252: * Does this community node exist persistently?
253: * @throws com.sun.portal.community.mc.CommunityException If there was a problem determining if this community node exists persistently.
254: * @return a <CODE>boolean</CODE> indicating if this community node exists persistently.
255: */
256: public boolean exists() throws CMCException;
257:
258: /**
259: * Get the Display Profile documents associated with this community node.
260: * <p>
261: * This method returns the DP documents for all community roles supported
262: * by the community node. It is equivalent to calling
263: * <CODE>getDPDocuments(null)</CODE>.
264: * <p>
265: * The values in the returned <CODE>ConfigTable</CODE> object
266: * are <CODE>byte[]</CODE> objects. The <CODE>byte[]</CODE>
267: * is a UTF-8 encoded character stream.
268: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the DP documents from this community node.
269: * @return a <CODE>ConfigTable</CODE> object containing the DP documents.
270: * @see #getDPDocuments(Set)
271: */
272: public ConfigTable getDPDocuments() throws CMCException;
273:
274: /**
275: * Get the Display Profile documents for this community node, for the given set of roles.
276: * <p>
277: * The values in the returned <CODE>ConfigTable</CODE> object
278: * are <CODE>byte[]</CODE> objects. The <CODE>byte[]</CODE>
279: * is a UTF-8 encoded character stream.
280: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>, the roles to return DP documents for.
281: * @throws com.sun.portal.community.mc.CommunityException If there was a problem get the DP documents for this community node.
282: * @return a <CODE>ConfigTable</CODE> containing the DP documents for the given set of roles.
283: */
284: public ConfigTable getDPDocuments(Set rolePrincipals)
285: throws CMCException;
286:
287: /**
288: * Get the last modified times for the DP documents of this community node.
289: * <br><br>
290: * This method returns the modified times for all community roles supported
291: * by the community node. It is equivalent to calling
292: * <CODE>getDPDocumentLastModified(null)</CODE>.
293: * <br><br>
294: * The modified time values are in milliseconds,
295: * the difference between the current time and midnight,
296: * January 1, 1970 UTC. A value of -1 indicates that the
297: * document has never been set.
298: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the DP document last modified times for this
299: * community node.
300: * @return A ConfigTable containing the DP document last modified times for this
301: * community node.
302: * The value objects in the <CODE>ConfigTable</CODE> are <CODE>Longs</CODE>.
303: */
304: public ConfigTable getDPDocumentsLastModified() throws CMCException;
305:
306: /**
307: * Get the last modified times for the DP documents of this community node for
308: * the given set of roles.
309: * <br><br>
310: * The modified time values are in milliseconds,
311: * the difference between the current time and midnight,
312: * January 1, 1970 UTC. A value of -1 indicates that the
313: * document has never been set.
314: * @param rolePrincipals A <CODE>Set</CODE> of <CODE>RolePrincipals</CODE>,
315: * the roles to return DP document last modified times for.
316: * @throws com.sun.portal.community.mc.CommunityException If there was a problem getting the DP document last modified times
317: * for this community node.
318: * @return A ConfigTable containing the DP document last modified times for this
319: * community node.
320: * The value objects in the <CODE>ConfigTable</CODE> are <CODE>Longs</CODE>.
321: */
322: public ConfigTable getDPDocumentsLastModified(Set rolePrincipals)
323: throws CMCException;
324:
325: /**
326: * Set DP documents for this community node.
327: * <p>
328: * Setting a DP document will update its last modified time in this community
329: * node.
330: * <p>
331: * The values passed in the <CODE>ConfigTable</CODE> object
332: * are UTF-8 encoded <CODE>byte[]</CODE> objects
333: * representing a character stream.
334: * @param dpDocuments A <CODE>ConfigTable</CODE>
335: * containing the DP document values, as <CODE>byte[]</CODE>
336: * objects, to set
337: * in this community node.
338: * <br><br>
339: * If the config table contains mappings for community nodes other than
340: * this community, those entries will be silently ignored.
341: * <br><br>
342: * If the config table contains mappings for this community, and roles
343: * that this community does not support, an exception will be thrown.
344: * @throws com.sun.portal.community.mc.CommunityException If there was a problem setting the DP documents in this community node.
345: */
346: public void setDPDocuments(ConfigTable dpDocuments)
347: throws CMCException;
348:
349: /**
350: * Does this community node support the <CODE>setDPDocuments()</CODE> operation?
351: * @throws com.sun.portal.community.mc.CommunityException If there was a problem determining if this <CODE>setDPDocuments()</CODE>
352: * operation is supported in this community.
353: * @return a <CODE>boolean</CODE> indicating if this community supports the
354: * <CODE>setDPDocuments()</CODE> operation.
355: * @see #setDPDocuments(ConfigTable)
356: */
357: public boolean supportsSetDPDocuments() throws CMCException;
358:
359: /** Returns the description for the community
360: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
361: * operation is supported in this community.
362: * @return the description for the community
363: */
364:
365: public String getDescription() throws CMCException;
366:
367: /** Sets the description for the community
368: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
369: * operation is supported in this community.
370: */
371: public void setDescription(String description) throws CMCException;
372:
373: /**
374: * Does this community node support the <CODE>getDescription()</CODE> and
375: * <CODE>setDescription() operation.
376: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
377: * operations are supported in this community.
378: * @return a <CODE>boolean</CODE> indicating if this community supports the
379: * <CODE>setDescription()</CODE> and <CODE>getDescription()</CODE>operation.
380: * @see #setDescription(String description)
381: * @see #getDescription()
382: */
383: public boolean supportsDescription() throws CMCException;
384:
385: /** Returns the classification for the community
386: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
387: * operation is supported in this community.
388: * @return the classification for the community
389: */
390:
391: public String getCategory() throws CMCException;
392:
393: /** Sets the classification for the community
394: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
395: * operation is supported in this community.
396: */
397: public void setCategory(String classification) throws CMCException;
398:
399: /**
400: * Does this community node support the <CODE>getCategory()</CODE> and
401: * <CODE>setCategory() operation.
402: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
403: * operations are supported in this community.
404: * @return a <CODE>boolean</CODE> indicating if this community supports the
405: * <CODE>setCategory()</CODE> and <CODE>getCategory()</CODE>operation.
406: * @see #setCategory(String classification)
407: * @see #getCategory()
408: */
409: public boolean supportsCategory() throws CMCException;
410:
411: /** Returns the time when community was created.
412: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
413: * performing the operation.
414: * @return time in milliseconds since the community was created. Returns -1 if the time is unknown.
415: */
416: public long getCommunityCreationTime() throws CMCException;
417:
418: /**
419: * Does this community node support the <CODE>getComunityCreationTime()</CODE> operation.
420: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if
421: * operation is supported in this community.
422: * @return a <CODE>boolean</CODE> indicating if this community supports the
423: * <CODE>getComunityCreationTime()</CODE>operation.
424: * @see #getComunityCreationTime()
425: */
426: public boolean supportsCommunityCreationTime() throws CMCException;
427:
428: /**
429: * Is the membership restricted for the community?
430: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
431: * evaluating that.
432: * @return true if community membership is restricted, else returns false.
433: */
434: public boolean isMembershipRestricted() throws CMCException;
435:
436: /**
437: * Set the flag indicating whether the community membership is restricting.
438: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
439: * performing the operation.
440: * @param a boolean flag indicating the new setting.
441: */
442: public void setMembershipRestricted(boolean isMembershipRestricted)
443: throws CMCException;
444:
445: /**
446: * Does this community node support the <CODE>isMembershipRestricted()</CODE> and
447: * <CODE>setMembershipRestricted() operation.
448: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if
449: * operations are supported in this community.
450: * @return a <CODE>boolean</CODE> indicating if this community supports the
451: * <CODE>setMembershipRestricted()</CODE> and <CODE>isMembershipRestricted()</CODE>operation.
452: * @see #setMembershipRestricted(boolean isMembershipRestricted)
453: * @see #isMembershipRestricted()
454: */
455: public boolean supportsMembershipRestriction() throws CMCException;
456:
457: /**
458: * Are the community contents secured or accessible to all.
459: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
460: * evaluating that.
461: * @return true if community contents are secured, else return false.
462: */
463: public boolean isSecure() throws CMCException;
464:
465: /**
466: * Set the flag indicating whether the community content are secured.
467: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
468: * performing the operation.
469: * @param a boolean flag indicating the new setting.
470: */
471: public void setSecure(boolean isSecure) throws CMCException;
472:
473: /**
474: * Does this community node support the <CODE>isSecure()</CODE> and
475: * <CODE>setSecure() operation.
476: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if
477: * operations are supported in this community.
478: * @return a <CODE>boolean</CODE> indicating if this community supports the
479: * <CODE>setSecure()</CODE> and <CODE>isSecure()</CODE>operation.
480: * @see #setSecure(boolean isSecure)
481: * @see #isSecure()
482: */
483: public boolean supportsSecuring() throws CMCException;
484:
485: /**
486: * Is this community listed in the search database ?
487: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
488: * evaluating that.
489: * @return true if community is listed and false otherwise.
490: */
491: public boolean isListed() throws CMCException;
492:
493: /**
494: * Set the flag indicating the community is listed in the database.
495: * @throws com.sun.portal.community.mc.CommunityException if there was a problem
496: * performing the operation.
497: * @param a boolean flag indicating the new setting.
498: */
499: public void setListed(boolean isListed) throws CMCException;
500:
501: /**
502: * Does this community node support the <CODE>isListed()</CODE> and
503: * <CODE>setListed() operation.
504: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if
505: * operations are supported in this community.
506: * @return a <CODE>boolean</CODE> indicating if this community supports the
507: * <CODE>setListed()</CODE> and <CODE>isListed()</CODE>operation.
508: * @see #setListed(boolean isListed)
509: * @see #isListed()
510: */
511: public boolean supportsListing() throws CMCException;
512:
513: /**
514: * Does this community node support the <CODE>getRoleCreationTime()</CODE> operation.
515: * @throws com.sun.portal.community.mc.CommunityException if there was a problem determining if this <CODE>setDPDocuments()</CODE>
516: * operation is supported in this community.
517: * @return a <CODE>boolean</CODE> indicating if this community supports the
518: * <CODE>getRoleCreationTime()</CODE>operation.
519: * @see #getRoleCreationTime()
520: */
521:
522: public boolean supportsRoleCreationTime() throws CMCException;
523:
524: }
|