View Javadoc

1   /* 
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.security;
18  
19  import java.util.Collection;
20  import java.util.Iterator;
21  
22  /***
23   * <p>
24   * Describes the service interface for managing groups.
25   * </p>
26   * <p>
27   * Group hierarchy elements are being returned as a {@link Group}collection.
28   * The backing implementation must appropriately map the group hierarchy to a
29   * preferences sub-tree.
30   * </p>
31   * <p>
32   * The convention {principal}.{subprincipal} has been chosen to name groups
33   * hierachies. Implementation follow the conventions enforced by the Preferences
34   * API.
35   * </p>
36   * 
37   * @author <a href="mailto:dlestrat@apache.org">David Le Strat </a>
38   */
39  public interface GroupManager
40  {
41  
42      /***
43       * <p>
44       * Add a new group.
45       * </p>
46       * <p>
47       * Group principal names are expressed as {principal}.{subprincipal} where
48       * "." is the separator expressing the hierarchical nature of a group.
49       * </p>
50       * <p>
51       * Group principal path names are stored leveraging the {@link Preferences}
52       * api. Groups will be stored under /group/theGroupName/theGroupNameChild
53       * when given the full path name theGroupName.theGroupNameChild.
54       * 
55       * @param groupFullPathName The group name full path (e.g.
56       *            theGroupName.theGroupNameChild).
57       * @throws Throws a security exception.
58       */
59      void addGroup(String groupFullPathName) throws SecurityException;
60  
61      /***
62       * <p>
63       * Remove a group.
64       * </p>
65       * <p>
66       * Group principal names are expressed as {principal}.{subprincipal} where
67       * "." is the separator expressing the hierarchical nature of a group.
68       * </p>
69       * <p>
70       * Group principal path names are stored leveraging the {@link Preferences}
71       * api. Groups will be stored under /group/theGroupName/theGroupNameChild
72       * when given the full path name theGroupName.theGroupNameChild.
73       * 
74       * @param groupFullPathName The group name full path (e.g.
75       *            theGroupName.theGroupNameChild)
76       * @throws Throws a security exception.
77       */
78      void removeGroup(String groupFullPathName) throws SecurityException;
79  
80      /***
81       * <p>
82       * Whether or not a group exists.
83       * </p>
84       * 
85       * @param groupFullPathName The group name full path (e.g.
86       *            theGroupName.theGroupNameChild)
87       * @return Whether or not a group exists.
88       */
89      boolean groupExists(String groupFullPathName);
90  
91      /***
92       * <p>
93       * Get a group {@link Group}for a given group full path name.
94       * 
95       * @param groupFullPathName The group name full path (e.g.
96       *            theGroupName.theGroupChildName).
97       * @return The {@link Preferences}node.
98       * @throws Throws security exception if the group does not exist.
99       */
100     Group getGroup(String groupFullPathName) throws SecurityException;
101 
102     /***
103      * <p>
104      * A collection of {@link Group}for all the groups associated to a specific
105      * user.
106      * 
107      * @param username The user name.
108      * @return A collection of {@link Group}.
109      * @throws Throws security exception if the user does not exist.
110      */
111     Collection getGroupsForUser(String username) 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) throws SecurityException;
124 
125     /***
126      * <p>
127      * Add a user to a group.
128      * </p>
129      * 
130      * @param username The user name.
131      * @param groupFullPathName The group name full path (e.g.
132      *            theGroupName.theGroupChildName).
133      * @throws Throws a security exception.
134      */
135     void addUserToGroup(String username, String groupFullPathName) throws SecurityException;
136 
137     /***
138      * <p>
139      * Remove a user from a group.
140      * </p>
141      * 
142      * @param username The user name.
143      * @param groupFullPathName The group name full path (e.g.
144      *            theGroupName.theGroupChildName).
145      * @throws Throws a security exception.
146      */
147     void removeUserFromGroup(String username, String groupFullPathName) throws SecurityException;
148 
149     /***
150      * <p>
151      * Whether or not a user is in a group.
152      * </p>
153      * 
154      * @param username The user name.
155      * @param groupFullPathName The group name full path (e.g.
156      *            theGroupName.theGroupChildName).
157      * @return Whether or not a user is in a group.
158      * @throws Throws security exception if the user or group does not exist.
159      */
160     boolean isUserInGroup(String username, String groupFullPathName) throws SecurityException;
161 
162     /***
163      * Get all groups available from all group handlers
164      * 
165      * @param filter The filter used to retrieve matching groups.
166      * @return all groups available as {@link Principal} 
167      */
168    Iterator getGroups(String filter) throws SecurityException;
169     
170    /***
171     * Enable or disable a group.
172     * @param groupFullPathName The group name full path 
173      *            theGroupName.theGroupChildName).
174     * @param enabled enabled flag for the group
175     */
176    void setGroupEnabled(String groupFullPathName, boolean enabled) throws SecurityException;
177 }