KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > messenger > group > GroupProvider


1 /**
2  * $RCSfile: GroupProvider.java,v $
3  * $Revision: 1.5 $
4  * $Date: 2005/07/08 20:21:58 $
5  *
6  * Copyright (C) 2004 Jive Software. All rights reserved.
7  *
8  * This software is published under the terms of the GNU Public License (GPL),
9  * a copy of which is included in this distribution.
10  */

11
12 package org.jivesoftware.messenger.group;
13
14 import org.jivesoftware.messenger.user.User;
15
16 import java.util.Collection JavaDoc;
17
18 /**
19  * Provider interface for groups. Users that wish to integrate with
20  * their own group system must implement this class and then register
21  * the implementation with Jive Messenger in the <tt>jive-messenger.xml</tt>
22  * file. An entry in that file would look like the following:
23  *
24  * <pre>
25  * &lt;provider&gt;
26  * &lt;group&gt;
27  * &lt;className&gt;com.foo.auth.CustomGroupProvider&lt;/className&gt;
28  * &lt;/group&gt;
29  * &lt;/provider&gt;</pre>
30  *
31  * @author Matt Tucker
32  */

33 public interface GroupProvider {
34
35     /**
36      * Creates a group with the given name (optional operation).<p>
37      *
38      * The provider is responsible for setting the creation date and
39      * modification date to the current date/time.
40      *
41      * @param name name of the group.
42      * @return the newly created group.
43      * @throws GroupAlreadyExistsException if a group with the same name already
44      * exists.
45      * @throws UnsupportedOperationException if the provider does not
46      * support the operation.
47      */

48     Group createGroup(String JavaDoc name) throws UnsupportedOperationException JavaDoc,
49             GroupAlreadyExistsException;
50
51     /**
52      * Deletes the group (optional operation).
53      *
54      * @param name the name of the group to delete
55      * @throws UnsupportedOperationException if the provider does not
56      * support the operation.
57      */

58     void deleteGroup(String JavaDoc name) throws UnsupportedOperationException JavaDoc;
59
60     /**
61      * Returns a group based on it's name.
62      *
63      * @param name the name of the group.
64      * @return the group with the given name.
65      * @throws GroupNotFoundException If no group with that ID could be found
66      */

67     Group getGroup(String JavaDoc name) throws GroupNotFoundException;
68
69     /**
70      * Sets the name of a group to a new name.
71      *
72      * @param oldName the current name of the group.
73      * @param newName the desired new name of the group.
74      * @throws GroupAlreadyExistsException if a group with the same name already
75      * exists.
76      * @throws UnsupportedOperationException if the provider does not
77      * support the operation.
78      */

79     void setName(String JavaDoc oldName, String JavaDoc newName) throws UnsupportedOperationException JavaDoc,
80             GroupAlreadyExistsException;
81
82     /**
83      * Updates the group's description.
84      *
85      * @param name the group name.
86      * @param description the group description.
87      * @throws GroupNotFoundException if no existing group could be found to update.
88      */

89     void setDescription(String JavaDoc name, String JavaDoc description)
90             throws GroupNotFoundException;
91
92     /**
93      * Returns the number of groups in the system.
94      *
95      * @return the number of groups in the system.
96      */

97     int getGroupCount();
98
99     /**
100      * Returns the Collection of all groups in the system.
101      *
102      * @return the Collection of all groups.
103      */

104     Collection JavaDoc<Group> getGroups();
105
106     /**
107      * Returns the Collection of all groups in the system.
108      *
109      * @param startIndex start index in results.
110      * @param numResults number of results to return.
111      * @return the Collection of all groups given the <tt>startIndex</tt> and <tt>numResults</tt>.
112      */

113     Collection JavaDoc<Group> getGroups(int startIndex, int numResults);
114
115     /**
116      * Returns the Collection of Groups that a user belongs to.
117      *
118      * @param user the user.
119      * @return the Collection of groups that the user belongs to.
120      */

121     Collection JavaDoc<Group> getGroups(User user);
122
123     /**
124      * Adds a user to a group (optional operation).
125      *
126      * @param groupName the group to add the member to
127      * @param username the username to add
128      * @param administrator True if the member is an administrator of the group
129      * @throws UnsupportedOperationException if the provider does not
130      * support the operation.
131      */

132     void addMember(String JavaDoc groupName, String JavaDoc username, boolean administrator)
133             throws UnsupportedOperationException JavaDoc;
134
135     /**
136      * Updates the privileges of a user in a group.
137      *
138      * @param groupName the group where the change happened
139      * @param username the username to of the user with new privileges
140      * @param administrator True if the member is an administrator of the group
141      * @throws UnsupportedOperationException if the provider does not
142      * support the operation.
143      */

144     void updateMember(String JavaDoc groupName, String JavaDoc username, boolean administrator)
145             throws UnsupportedOperationException JavaDoc;
146
147     /**
148      * Deletes a user from a group (optional operation).
149      *
150      * @param groupName the group name.
151      * @param username the username.
152      * @throws UnsupportedOperationException if the provider does not
153      * support the operation.
154      */

155     void deleteMember(String JavaDoc groupName, String JavaDoc username) throws UnsupportedOperationException JavaDoc;
156
157     /**
158      * Returns true if this GroupProvider is read-only. When read-only,
159      * groups can not be created, deleted, or modified.
160      *
161      * @return true if the user provider is read-only.
162      */

163     public boolean isReadOnly();
164 }
Popular Tags