GroupProvider.java 10.5 KB
Newer Older
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision: 3117 $
 * $Date: 2005-11-25 22:57:29 -0300 (Fri, 25 Nov 2005) $
 *
6
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
7
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20
 */

21
package org.jivesoftware.openfire.group;
22 23

import java.util.Collection;
24 25
import java.util.Map;

26
import org.jivesoftware.util.PersistableMap;
27
import org.xmpp.packet.JID;
28 29 30 31

/**
 * Provider interface for groups. Users that wish to integrate with
 * their own group system must implement this class and then register
32
 * the implementation with Openfire in the <tt>openfire.xml</tt>
33 34 35 36 37 38 39 40 41
 * file. An entry in that file would look like the following:
 *
 * <pre>
 *   &lt;provider&gt;
 *     &lt;group&gt;
 *       &lt;className&gt;com.foo.auth.CustomGroupProvider&lt;/className&gt;
 *     &lt;/group&gt;
 *   &lt;/provider&gt;</pre>
 *
42
 * @see AbstractGroupProvider
43
 * 
44 45 46 47 48
 * @author Matt Tucker
 */
public interface GroupProvider {

    /**
49 50
     * Creates a group with the given name (optional operation).
     * <p>
51 52
     * The provider is responsible for setting the creation date and
     * modification date to the current date/time.
53
     * </p>
54 55 56 57 58 59 60 61
     *
     * @param name name of the group.
     * @return the newly created group.
     * @throws GroupAlreadyExistsException if a group with the same name already
     *      exists.
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
62
    Group createGroup(String name) throws GroupAlreadyExistsException;
63 64 65 66 67 68 69 70

    /**
     * Deletes the group (optional operation).
     *
     * @param name the name of the group to delete.
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
71
    void deleteGroup(String name);
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91

    /**
     * Returns a group based on it's name.
     *
     * @param name the name of the group.
     * @return the group with the given name.
     * @throws GroupNotFoundException If no group with that ID could be found
     */
    Group getGroup(String name) throws GroupNotFoundException;

    /**
     * Sets the name of a group to a new name.
     *
     * @param oldName the current name of the group.
     * @param newName the desired new name of the group.
     * @throws GroupAlreadyExistsException if a group with the same name already
     *      exists.
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
92
    void setName(String oldName, String newName) throws GroupAlreadyExistsException;
93 94 95 96 97 98 99 100

    /**
     * Updates the group's description.
     *
     * @param name the group name.
     * @param description the group description.
     * @throws GroupNotFoundException if no existing group could be found to update.
     */
101
    void setDescription(String name, String description) throws GroupNotFoundException;
102 103 104 105 106 107 108 109 110

    /**
     * Returns the number of groups in the system.
     *
     * @return the number of groups in the system.
     */
    int getGroupCount();

    /**
111
     * Returns the Collection of all group names in the system.
112 113 114
     *
     * @return the Collection of all groups.
     */
115
    Collection<String> getGroupNames();
116

117 118 119 120 121 122 123 124
    /**
     * Returns true if this GroupProvider allows group sharing. Shared groups
     * enable roster sharing.
     *
     * @return true if the group provider supports group sharing.
     */
    boolean isSharingSupported();

125 126 127 128 129
    /**
     * Returns an unmodifiable Collection of all shared groups in the system.
     *
     * @return unmodifiable Collection of all shared groups in the system.
     */
130 131 132 133 134
    Collection<String> getSharedGroupNames();
    
    /**
     * Returns an unmodifiable Collection of all shared groups in the system for a given user.
     * 
135
     * @param user The bare JID for the user (node@domain)
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
     * @return unmodifiable Collection of all shared groups in the system for a given user.
     */
    Collection<String> getSharedGroupNames(JID user);
    
    /**
     * Returns an unmodifiable Collection of all public shared groups in the system.
     *
     * @return unmodifiable Collection of all public shared groups in the system.
     */
    Collection<String> getPublicSharedGroupNames();
    
    /**
     * Returns an unmodifiable Collection of groups that are visible
     * to the members of the given group.
     * 
     * @param userGroup The given group
     * @return unmodifiable Collection of group names that are visible
     * to the given group.
     */
    Collection<String> getVisibleGroupNames(String userGroup);
    
157 158 159 160 161
    /**
     * Returns the Collection of all groups in the system.
     *
     * @param startIndex start index in results.
     * @param numResults number of results to return.
162 163
     * @return the Collection of all group names given the
     *      <tt>startIndex</tt> and <tt>numResults</tt>.
164
     */
165
    Collection<String> getGroupNames(int startIndex, int numResults);
166 167

    /**
168
     * Returns the Collection of group names that an entity belongs to.
169 170
     *
     * @param user the JID of the entity.
171
     * @return the Collection of group names that the user belongs to.
172
     */
173
    Collection<String> getGroupNames(JID user);
174 175 176 177 178 179 180 181 182 183

    /**
     * Adds an entity to a group (optional operation).
     *
     * @param groupName the group to add the member to
     * @param user the JID of the entity to add
     * @param administrator True if the member is an administrator of the group
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
184
    void addMember(String groupName, JID user, boolean administrator);
185 186 187 188 189 190 191 192 193 194

    /**
     * Updates the privileges of an entity in a group.
     *
     * @param groupName the group where the change happened
     * @param user the JID of the entity with new privileges
     * @param administrator True if the member is an administrator of the group
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
195
    void updateMember(String groupName, JID user, boolean administrator);
196 197 198 199 200 201 202 203 204

    /**
     * Deletes an entity from a group (optional operation).
     *
     * @param groupName the group name.
     * @param user the JID of the entity to delete.
     * @throws UnsupportedOperationException if the provider does not
     *      support the operation.
     */
205
    void deleteMember(String groupName, JID user);
206 207 208 209 210 211 212

    /**
     * Returns true if this GroupProvider is read-only. When read-only,
     * groups can not be created, deleted, or modified.
     *
     * @return true if the user provider is read-only.
     */
213 214 215
    boolean isReadOnly();

    /**
216
     * Returns the group names that match a search. The search is over group names and
217 218 219 220 221 222 223 224 225 226
     * implicitly uses wildcard matching (although the exact search semantics are left
     * up to each provider implementation). For example, a search for "HR" should match
     * the groups "HR", "HR Department", and "The HR People".<p>
     *
     * Before searching or showing a search UI, use the {@link #isSearchSupported} method
     * to ensure that searching is supported.
     *
     * @param query the search string for group names.
     * @return all groups that match the search.
     */
227
    Collection<String> search(String query);
228 229

    /**
230
     * Returns the group names that match a search given a start index and desired number of results.
231 232 233 234 235 236 237 238
     * The search is over group names and implicitly uses wildcard matching (although the
     * exact search semantics are left up to each provider implementation). For example, a
     * search for "HR" should match the groups "HR", "HR Department", and "The HR People".<p>
     *
     * Before searching or showing a search UI, use the {@link #isSearchSupported} method
     * to ensure that searching is supported.
     *
     * @param query the search string for group names.
Matt Tucker's avatar
Matt Tucker committed
239 240
     * @param startIndex start index in results.
     * @param numResults number of results to return.
241 242
     * @return all groups that match the search.
     */
243
    Collection<String> search(String query, int startIndex, int numResults);
244

245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
    /**
     * Returns the names of groups that have a property matching the given
     * key/value pair. This provides an simple extensible search mechanism
     * for providers with differing property sets and storage models.
     * 
     * The semantics of the key/value matching (wildcard support, scoping, etc.) 
     * are unspecified by the interface and may vary for each implementation.
     * 
     * Before searching or showing a search UI, use the {@link #isSearchSupported} method
     * to ensure that searching is supported.
     *
     * @param key The name of a group property (e.g. "sharedRoster.showInRoster")
     * @param value The value to match for the given property
     * @return unmodifiable Collection of group names that match the
     * 			given key/value pair.
     */
    Collection<String> search(String key, String value);
    
263 264 265 266 267 268
    /**
     * Returns true if group searching is supported by the provider.
     *
     * @return true if searching is supported.
     */
    boolean isSearchSupported();
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
    
    /**
     * Loads the group properties (if any) from the backend data store. If
     * the properties can be changed, the provider implementation must ensure
     * that updates to the resulting {@link Map} are persisted to the
     * backend data store. Otherwise if a mutator method is called, the
     * implementation should throw an {@link UnsupportedOperationException}.
     * 
     * If there are no corresponding properties for the given group, or if the
     * provider does not support group properties, this method should return
     * an empty Map rather than null.
     * 
     * @param group The target group
     * @return The properties for the given group
     */
284
    PersistableMap<String,String> loadProperties(Group group);
285
    
286
}