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.Iterator;
020: import java.util.Collection;
021:
022: /**
023: * <p>Describes the service interface for managing roles.</p>
024: * <p>Role hierarchy elements are being returned as a {@link Role}
025: * collection. The backing implementation must appropriately map
026: * the role hierarchy to a preferences sub-tree.</p>
027: * <p>The convention {principal}.{subprincipal} has been chosen to name
028: * roles hierachies in order to support declarative security. Implementation
029: * follow the conventions enforced by the preferences API.</p>
030: * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
031: */
032: public interface RoleManager {
033:
034: /**
035: * <p>Add a new role.</p>
036: * <p>Role principal names are expressed as {principal}.{subprincipal} where
037: * "." is the separator expressing the hierarchical nature of a role.</p>
038: * <p>Role principal path names are stored leveraging the {@link Preferences}
039: * api. Roles will be stored under /role/theGroupName/theGroupNameChild
040: * when given the full path name theRoleName.theRoleNameChild.
041: * @param roleFullPathName The role name full path
042: * (e.g. theRoleName.theRoleNameChild).
043: * @throws Throws a security exception if the role already exists.
044: */
045: void addRole(String roleFullPathName) throws SecurityException;
046:
047: /**
048: * <p>Remove a given role and all the children of that role.</p>
049: * <p>Role principal names are expressed as {principal}.{subprincipal} where
050: * "." is the separator expressing the hierarchical nature of a role.</p>
051: * <p>Role principal path names are stored leveraging the {@link Preferences}
052: * api. Roles will be stored under /role/theGroupName/theGroupNameChild
053: * when given the full path name theRoleName.theRoleNameChild.
054: * @param roleFullPathName The role name full path
055: * (e.g. theRoleName.theRoleNameChild).
056: * @throws Throws a security exception.
057: */
058: void removeRole(String roleFullPathName) throws SecurityException;
059:
060: /**
061: * <p>Whether or not a role exists.</p>
062: * @param roleFullPathName The role name full path
063: * (e.g. theRoleName.theRoleNameChild).
064: * @return Whether or not a role exists.
065: */
066: boolean roleExists(String roleFullPathName);
067:
068: /**
069: * <p>Get a role {@link Role} for a given role full path name.
070: * @param roleFullPathName The role name full path
071: * (e.g. theRoleName.theRoleNameChild).
072: * @return The {@link Preferences} node.
073: * @throws Throws a security exception if the role does not exist.
074: */
075: Role getRole(String roleFullPathName) throws SecurityException;
076:
077: /**
078: * <p>A collection of {@link Role} for all the roles
079: * associated to a specific user.</p>
080: * @param username The user name.
081: * @return A Collection of {@link Role}.
082: * @throws Throws a security exception if the user does not exist.
083: */
084: Collection getRolesForUser(String username)
085: throws SecurityException;
086:
087: /**
088: * <p>A collection of {@link Role} for all the roles
089: * associated to a specific group.</p>
090: * @param groupFullPathName The group full path
091: * (e.g. theGroupName.theGroupChildName).
092: * @return A Collection of {@link Role}.
093: * @throws Throws a security exception if the group does not exist.
094: */
095: Collection getRolesInGroup(String groupFullPathName)
096: throws SecurityException;
097:
098: /**
099: * <p>Add a role to a user.</p>
100: * @param username The user name.
101: * @param roleFullPathName The role name full path
102: * (e.g. theRoleName.theRoleChildName).
103: * @throws Throws a security exception if the role or the user do not exist.
104: */
105: void addRoleToUser(String username, String roleFullPathName)
106: throws SecurityException;
107:
108: /**
109: * <p>Remove a user from a role.</p>
110: * @param username The user name.
111: * @param roleFullPathName The role name full path relative to the
112: * /role node (e.g. /theRoleName/theRoleChildName).
113: * @throws Throws a security exception.
114: */
115: void removeRoleFromUser(String username, String roleFullPathName)
116: throws SecurityException;
117:
118: /**
119: * <p>Whether or not a user is in a role.</p>
120: * @param username The user name.
121: * @param roleFullPathName The role name full path
122: * (e.g. theRoleName.theRoleChildName).
123: * @return Whether or not a user is in a role.
124: * @throws Throws a security exception if the role or the user does not exist.
125: */
126: boolean isUserInRole(String username, String roleFullPathName)
127: throws SecurityException;
128:
129: /**
130: * <p>Add a role to a group.</p>
131: * @param roleFullPathName The role name full path
132: * (e.g. theRoleName.theRoleChildName).
133: * @param groupFullPathName The group name full path
134: * (e.g. theGroupName.theGroupChildName).
135: * @throws Throws a security exception.
136: */
137: void addRoleToGroup(String roleFullPathName,
138: String groupFullPathName) throws SecurityException;
139:
140: /**
141: * <p>Remove a role from a group.</p>
142: * @param roleFullPathName The role name full path
143: * (e.g. theRoleName.theRoleChildName).
144: * @param groupFullPathName The group name full path
145: * (e.g. theGroupName.theGroupChildName).
146: * @throws Throws a security exception.
147: */
148: void removeRoleFromGroup(String roleFullPathName,
149: String groupFullPathName) throws SecurityException;
150:
151: /**
152: * <p>Whether or not a role is in a group.</p>
153: * @param groupFullPathName The group name full path
154: * (e.g. theGroupName.theGroupChildName).
155: * @param roleFullPathName The role name full path
156: * (e.g. theRoleName.theRoleChildName).
157: * @return Whether or not a role is in a group.
158: * @throws Throws a security exception if the role or the group does not exist.
159: */
160: boolean isGroupInRole(String groupFullPathName,
161: String roleFullPathName) throws SecurityException;
162:
163: /**
164: * Get all roles available from all role handlers
165: *
166: * @param filter The filter used to retrieve matching roles.
167: * @return all roles available as {@link Principal}
168: */
169: Iterator getRoles(String filter) throws SecurityException;
170:
171: /**
172: * Enable or disable a role.
173: * @param roleFullPathName The role name full path
174: * (e.g. theRoleName.theRoleChildName).
175: * @param enabled enabled flag for the role
176: */
177: void setRoleEnabled(String roleFullPathName, boolean enabled)
178: throws SecurityException;
179: }
|