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  ;
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   name) throws UnsupportedOperationException  ,
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   name) throws UnsupportedOperationException  ;
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   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   oldName, String   newName) throws UnsupportedOperationException  ,
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   name, String   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  <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  <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  <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   groupName, String   username, boolean administrator)
133             throws UnsupportedOperationException  ;
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   groupName, String   username, boolean administrator)
145             throws UnsupportedOperationException  ;
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   groupName, String   username) throws UnsupportedOperationException  ;
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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags