View Javadoc

1   /*
2    * Copyright 2000-2001,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.jetspeed.services.security;
18  
19  import java.util.Iterator;
20  
21  import org.apache.jetspeed.om.security.Group;
22  import org.apache.turbine.services.Service;
23  
24  /***
25   * <p> The <code>GroupManagement</code> interface describes contract between
26   * the portal and security provider required for Jetspeed Group Management.
27   * This interface enables an application to be independent of the underlying
28   * group management technology.
29   *
30   * @author <a href="mailto:david@bluesunrise.com">David Sean Taylor</a>
31   * @version $Id: GroupManagement.java,v 1.4 2004/02/23 03:58:11 jford Exp $
32   */
33  
34  public interface GroupManagement extends Service
35  {
36      public String SERVICE_NAME = "GroupManagement";
37      
38  	public String DEFAULT_GROUP_NAME = "Jetspeed";
39  	
40      /***
41       * Retrieves all <code>Group</code>s for a given username principal.
42       *
43       * The security service may optionally check the current user context
44       * to determine if the requestor has permission to perform this action.
45       *
46       * @param username a user principal identity to be retrieved.
47       * @return Iterator over all groups associated to the user principal.
48       * @exception GroupException when the security provider has a general failure.
49       * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
50       */
51      Iterator getGroups(String username)
52          throws JetspeedSecurityException;
53  
54      /***
55       * Retrieves all <code>Group</code>s.
56       *
57       * The security service may optionally check the current user context
58       * to determine if the requestor has permission to perform this action.
59       *
60       * @return Iterator over all groups.
61       * @exception GroupException when the security provider has a general failure.
62       * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
63       */
64      Iterator getGroups()
65          throws JetspeedSecurityException;
66  
67      /***
68       * Adds a <code>Group</code> into permanent storage.
69       *
70       * The security service may optionally check the current user context
71       * to determine if the requestor has permission to perform this action.
72       *
73       * @exception GroupException when the security provider has a general failure.
74       * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
75       */
76      void addGroup(Group group)
77          throws JetspeedSecurityException;
78  
79      /***
80       * Saves a <code>Group</code> into permanent storage.
81       *
82       * The security service may optionally check the current user context
83       * to determine if the requestor has permission to perform this action.
84       *
85       * @exception GroupException when the security provider has a general failure.
86       * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
87       */
88      void saveGroup(Group group)
89          throws JetspeedSecurityException;
90  
91      /***
92       * Removes a <code>Group</code> from the permanent store.
93       *
94       * The security service may optionally check the current user context
95       * to determine if the requestor has permission to perform this action.
96       *
97       * @param groupname the principal identity of the group to be retrieved.
98       * @exception GroupException when the security provider has a general failure.
99       * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
100      */
101     void removeGroup(String groupname)
102         throws JetspeedSecurityException;
103 
104     /***
105      * Joins a user to a group.
106      *
107      * The security service may optionally check the current user context
108      * to determine if the requestor has permission to perform this action.
109      *
110      * @exception GroupException when the security provider has a general failure retrieving groups.
111      * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
112      */
113     void joinGroup(String username, String groupname)
114         throws JetspeedSecurityException;
115 
116     /***
117      * Joins a user into a group with a specific role.
118      *
119      * The security service may optionally check the current user context
120      * to determine if the requestor has permission to perform this action.
121      *
122      * @exception GroupException when the security provider has a general failure retrieving groups.
123      * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
124      */
125     void joinGroup(String username, String groupname, String rolename)
126         throws JetspeedSecurityException;
127 
128     /***
129      * Unjoins a user from a group.
130      *
131      * The security service may optionally check the current user context
132      * to determine if the requestor has permission to perform this action.
133      *
134      * @exception GroupException when the security provider has a general failure retrieving groups.
135      * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
136      */
137     void unjoinGroup(String username, String groupname)
138         throws JetspeedSecurityException;
139 
140     /***
141     * Unjoins a user from a group - specific role.
142     *
143     * The security service may optionally check the current user context
144     * to determine if the requestor has permission to perform this action.
145     *
146     * @exception GroupException when the security provider has a general failure retrieving groups.
147     * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
148     */
149     void unjoinGroup(String username, String groupname, String rolename)
150         throws JetspeedSecurityException;
151 
152     /***
153      * Checks for the relationship of user in a group. Returns true when the user is in the given group.
154      *
155      * The security service may optionally check the current user context
156      * to determine if the requestor has permission to perform this action.
157      *
158      * @exception GroupException when the security provider has a general failure retrieving groups.
159      * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
160      */
161     boolean inGroup(String username, String groupname)
162         throws JetspeedSecurityException;
163 
164     /***
165      * Retrieves a single <code>Group</code> for a given groupname principal.
166      *
167      * The security service may optionally check the current user context
168      * to determine if the requestor has permission to perform this action.
169      *
170      * @param groupname a group principal identity to be retrieved.
171      * @return Group the group record retrieved.
172      * @exception GroupException when the security provider has a general failure.
173      * @exception InsufficientPrivilegeException when the requestor is denied due to insufficient privilege
174      */
175     Group getGroup(String groupname)
176         throws JetspeedSecurityException;
177 }
178 
179 
180 
181 
182 
183 
184 
185 
186 
187