Group.java 8.59 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14
package org.jivesoftware.messenger.auth;

import org.jivesoftware.messenger.user.UserAlreadyExistsException;
15 16
import org.jivesoftware.messenger.user.User;

Matt Tucker's avatar
Matt Tucker committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
import java.util.Date;
import java.util.Iterator;

/**
 * Organizes entities into a group for easier permissions management.
 * In this way, groups essentially serve the same purpose that
 * they do in Unix or Windows.<p>
 * <p/>
 * For example, CREATE_THREAD permissions can be set per forum. A
 * forum administrator may wish to create a "Thread Posters" group
 * that has CREATE_THREAD permissions in the forum. Then, users can
 * be added to that group and will automatically receive CREATE_THREAD
 * permissions in that forum.<p>
 * <p/>
 * Security for Group objects is provide by GroupProxy protection proxy objects.
 *
 * @author Iain Shigeoka
 */
public interface Group {

    /**
     * Returns the id of the group.
     *
     * @return the id of the group.
     */
    public long getID();

    /**
     * Returns the name of the group. For example, 'XYZ Admins'.
     *
     * @return the name of the group.
     */
    public String getName();

    /**
     * Sets the name of the group. For example, 'XYZ Admins'. This
     * method is restricted to those with group administration permission.
     *
     * @param name the name for the group.
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
    public void setName(String name) throws UnauthorizedException;

    /**
     * Returns the description of the group. The description often
     * summarizes a group's function, such as 'Administrators of the XYZ forum'.
     *
     * @return the description of the group.
     */
    public String getDescription();

    /**
     * Sets the description of the group. The description often
     * summarizes a group's function, such as 'Administrators of
     * the XYZ forum'. This method is restricted to those with group
     * administration permission.
     *
     * @param description the description of the group.
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
    public void setDescription(String description) throws UnauthorizedException;

    /**
     * Returns the date that the group was created.
     *
     * @return the date the group was created.
     */
    public Date getCreationDate();

    /**
     * Sets the creation date of the group. In most cases, the
     * creation date will default to when the group was entered
     * into the system. However, the date needs to be set manually when
     * importing data. In other words, skin authors should ignore
     * this method since it only intended for system maintenance.
     *
     * @param creationDate the date the group was created.
     * @throws UnauthorizedException if does not have administrator permissions.
     */
    public void setCreationDate(Date creationDate) throws UnauthorizedException;

    /**
     * Returns the date that the group was last modified.
     *
     * @return the date the group record was last modified.
     */
    public Date getModificationDate();

    /**
     * Sets the date the group was last modified. Skin authors
     * should ignore this method since it only intended for
     * system maintenance.
     *
     * @param modificationDate the date the group was modified.
     * @throws UnauthorizedException if does not have administrator permissions.
     */
    public void setModificationDate(Date modificationDate) throws UnauthorizedException;

    /**
     * Returns an extended property of the group. Each group can
     * have an arbitrary number of extended properties. This
     * lets particular skins or filters provide enhanced functionality
     * that is not part of the base interface.
     *
     * @param name the name of the property to get.
     * @return the value of the property
     */
    public String getProperty(String name);

    /**
     * Sets an extended property of the group. Each group can have
     * an arbitrary number of extended properties. This lets
     * particular skins or filters provide enhanced functionality that is not
     * part of the base interface.
     *
     * @param name  the name of the property to set.
     * @param value the new value for the property.
     * @throws UnauthorizedException if not allowed to change the group.
     */
    public void setProperty(String name, String value) throws UnauthorizedException;

    /**
     * Deletes an extended property. If the property specified by
     * <code>name</code> does not exist, this method will do nothing.
     *
     * @param name the name of the property to delete.
     * @throws UnauthorizedException if not allowed to edit messages.
     */
    public void deleteProperty(String name) throws UnauthorizedException;

    /**
     * Returns an Iterator for all the names of the extended group properties.
     *
     * @return an Iterator for the property names.
     */
    public Iterator getPropertyNames();

    /**
     * Grants administrator privileges of the group to a user. This
     * method is restricted to those with group administration permission.
     *
158
     * @param user the User to grant adminstrative privileges to.
Matt Tucker's avatar
Matt Tucker committed
159 160
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
161
    public void addAdministrator(User user) throws UnauthorizedException, UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
162 163 164 165 166

    /**
     * Revokes administrator privileges of the group to a user.
     * This method is restricted to those with group administration permission.
     *
167
     * @param user the User to grant adminstrative privileges to.
Matt Tucker's avatar
Matt Tucker committed
168 169
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
170
    public void removeAdministrator(User user) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
171 172 173 174 175

    /**
     * Adds a member to the group. This method is restricted to
     * those with group administration permission.
     *
176
     * @param user the User to add to the group.
Matt Tucker's avatar
Matt Tucker committed
177 178
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
179
    public void addMember(User user) throws UnauthorizedException, UserAlreadyExistsException;
Matt Tucker's avatar
Matt Tucker committed
180 181 182 183 184 185

    /**
     * Removes a member from the group. If the User is not
     * in the group, this method does nothing. This method
     * is restricted to those with group administration permission.
     *
186
     * @param user the User to remove from the group.
Matt Tucker's avatar
Matt Tucker committed
187 188
     * @throws UnauthorizedException if does not have group administrator permissions.
     */
189
    public void removeMember(User user) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
190 191 192 193 194 195

    /**
     * Returns true if the User has group administrator permissions.
     *
     * @return true if the User is an administrator of the group.
     */
196
    public boolean isAdministrator(User user);
Matt Tucker's avatar
Matt Tucker committed
197 198 199 200 201 202

    /**
     * Returns true if if the User is a member of the group.
     *
     * @return true if the User is a member of the group.
     */
203
    public boolean isMember(User user);
Matt Tucker's avatar
Matt Tucker committed
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

    /**
     * Returns the number of group administrators.
     *
     * @return the number of group administrators.
     */
    public int getAdministratorCount();

    /**
     * Returns the number of group members.
     *
     * @return the number of group members.
     */
    public int getMemberCount();

    /**
     * An iterator for all the Entities that are members of the group.
     *
     * @return an Iterator for all members of the group.
     */
    public Iterator members();

    /**
     * An iterator for all the Entities that are administrators of the group.
     *
     * @return an Iterator for all administrators of the group.
     */
    public Iterator administrators();

    /**
     * Returns the permissions for the group that correspond to the passed-in AuthToken.
     *
     * @param authToken the auth token to lookup permissions for.
     * @return the permissions for the group that correspond to the passed-in AuthToken.
     * @see Permissions
     */
    public Permissions getPermissions(AuthToken authToken);

    /**
     * Returns true if the handle on the object has the
     * permission specified. A list of possible
     * permissions can be found in the Permissions class.
     * Certain methods of this class are restricted to
     * certain permissions as specified in the method comments.
     *
     * @param permissionType a permission type.
     * @return true if the specified permission is valid.
     * @see Permissions
     */
    public boolean isAuthorized(long permissionType);
}