001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.jetspeed.security;
018:
019: import java.util.Collection;
020: import java.util.Iterator;
021:
022: /**
023: * <p>
024: * Describes the service interface for managing groups.
025: * </p>
026: * <p>
027: * Group hierarchy elements are being returned as a {@link Group}collection.
028: * The backing implementation must appropriately map the group hierarchy to a
029: * preferences sub-tree.
030: * </p>
031: * <p>
032: * The convention {principal}.{subprincipal} has been chosen to name groups
033: * hierachies. Implementation follow the conventions enforced by the Preferences
034: * API.
035: * </p>
036: *
037: * @author <a href="mailto:dlestrat@apache.org">David Le Strat </a>
038: */
039: public interface GroupManager {
040:
041: /**
042: * <p>
043: * Add a new group.
044: * </p>
045: * <p>
046: * Group principal names are expressed as {principal}.{subprincipal} where
047: * "." is the separator expressing the hierarchical nature of a group.
048: * </p>
049: * <p>
050: * Group principal path names are stored leveraging the {@link Preferences}
051: * api. Groups will be stored under /group/theGroupName/theGroupNameChild
052: * when given the full path name theGroupName.theGroupNameChild.
053: *
054: * @param groupFullPathName The group name full path (e.g.
055: * theGroupName.theGroupNameChild).
056: * @throws Throws a security exception.
057: */
058: void addGroup(String groupFullPathName) throws SecurityException;
059:
060: /**
061: * <p>
062: * Remove a group.
063: * </p>
064: * <p>
065: * Group principal names are expressed as {principal}.{subprincipal} where
066: * "." is the separator expressing the hierarchical nature of a group.
067: * </p>
068: * <p>
069: * Group principal path names are stored leveraging the {@link Preferences}
070: * api. Groups will be stored under /group/theGroupName/theGroupNameChild
071: * when given the full path name theGroupName.theGroupNameChild.
072: *
073: * @param groupFullPathName The group name full path (e.g.
074: * theGroupName.theGroupNameChild)
075: * @throws Throws a security exception.
076: */
077: void removeGroup(String groupFullPathName) throws SecurityException;
078:
079: /**
080: * <p>
081: * Whether or not a group exists.
082: * </p>
083: *
084: * @param groupFullPathName The group name full path (e.g.
085: * theGroupName.theGroupNameChild)
086: * @return Whether or not a group exists.
087: */
088: boolean groupExists(String groupFullPathName);
089:
090: /**
091: * <p>
092: * Get a group {@link Group}for a given group full path name.
093: *
094: * @param groupFullPathName The group name full path (e.g.
095: * theGroupName.theGroupChildName).
096: * @return The {@link Preferences}node.
097: * @throws Throws security exception if the group does not exist.
098: */
099: Group getGroup(String groupFullPathName) throws SecurityException;
100:
101: /**
102: * <p>
103: * A collection of {@link Group}for all the groups associated to a specific
104: * user.
105: *
106: * @param username The user name.
107: * @return A collection of {@link Group}.
108: * @throws Throws security exception if the user does not exist.
109: */
110: Collection getGroupsForUser(String username)
111: throws SecurityException;
112:
113: /**
114: * <p>
115: * A collection of {@link Group}for all the groups in a specific role.
116: * </p>
117: *
118: * @param roleFullPathName The role full path (e.g.
119: * theRoleName.theRoleChildName)..
120: * @return A Collection of {@link Group}.
121: * @throws Throws a security exception if the role does not exist.
122: */
123: Collection getGroupsInRole(String roleFullPathName)
124: throws SecurityException;
125:
126: /**
127: * <p>
128: * Add a user to a group.
129: * </p>
130: *
131: * @param username The user name.
132: * @param groupFullPathName The group name full path (e.g.
133: * theGroupName.theGroupChildName).
134: * @throws Throws a security exception.
135: */
136: void addUserToGroup(String username, String groupFullPathName)
137: throws SecurityException;
138:
139: /**
140: * <p>
141: * Remove a user from a group.
142: * </p>
143: *
144: * @param username The user name.
145: * @param groupFullPathName The group name full path (e.g.
146: * theGroupName.theGroupChildName).
147: * @throws Throws a security exception.
148: */
149: void removeUserFromGroup(String username, String groupFullPathName)
150: throws SecurityException;
151:
152: /**
153: * <p>
154: * Whether or not a user is in a group.
155: * </p>
156: *
157: * @param username The user name.
158: * @param groupFullPathName The group name full path (e.g.
159: * theGroupName.theGroupChildName).
160: * @return Whether or not a user is in a group.
161: * @throws Throws security exception if the user or group does not exist.
162: */
163: boolean isUserInGroup(String username, String groupFullPathName)
164: throws SecurityException;
165:
166: /**
167: * Get all groups available from all group handlers
168: *
169: * @param filter The filter used to retrieve matching groups.
170: * @return all groups available as {@link Principal}
171: */
172: Iterator getGroups(String filter) throws SecurityException;
173:
174: /**
175: * Enable or disable a group.
176: * @param groupFullPathName The group name full path
177: * theGroupName.theGroupChildName).
178: * @param enabled enabled flag for the group
179: */
180: void setGroupEnabled(String groupFullPathName, boolean enabled)
181: throws SecurityException;
182: }
|