1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.security;
18
19 import java.security.Permission;
20 import java.security.Permissions;
21 import java.security.Principal;
22 import java.util.Collection;
23 import javax.security.auth.Subject;
24
25 /***
26 * <p>
27 * Describe the interface for managing {@link Permission}and permission
28 * association to {@link Principal}. Permissions are used to manage Principals
29 * access entitlement on specified resources.
30 * </p>
31 * <p>
32 * The permission manager does not enforce any hierarchy resolution, all relevant
33 * principals must be passed to the permission manager to assess the proper permissions.
34 * </p>
35 * <p>
36 * For instance:
37 * </p>
38 *
39 * <pre><code>
40 *
41 * grant principal o.a.j.security.UserPrincipal "theUserPrincipal"
42 * {
43 * permission o.a.j.security.PortletPermission "myportlet", "view,edit,minimize,maximize";
44 * };
45 *
46 * </code>
47 * <pre>
48 * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
49 *
50 */
51 public interface PermissionManager
52 {
53
54 /***
55 * <p>
56 * Gets the {@link Permissions}given a {@link Principal}.
57 *
58 * @param principal The principal.
59 * @return The permissions.
60 */
61 Permissions getPermissions(Principal principal);
62
63 /***
64 * <p>
65 * Gets the {@link Permissions}given a collection of {@link Principal}.
66 *
67 * @param principals A collection of principal.
68 * @return The permissions.
69 */
70 Permissions getPermissions(Collection principals);
71
72 /***
73 * <p>
74 * Adds a permission definition.
75 * </p>
76 *
77 * @param permission The permission to add.
78 * @throws Throws a security exception.
79 */
80 void addPermission(Permission permission) throws SecurityException;
81
82 /***
83 * <p>
84 * Remove all instances of a given permission.
85 * </p>
86 *
87 * @param permission The permission to remove.
88 * @throws Throws a security exception.
89 */
90 void removePermission(Permission permission) throws SecurityException;
91
92 /***
93 * <p>
94 * Whether the given permission exists.
95 * </p>
96 *
97 * @param permission The permission to look for.
98 * @return Whether the permission exists.
99 */
100 boolean permissionExists(Permission permission);
101
102 /***
103 * <p>
104 * Remove all permissions for a given principal.
105 * </p>
106 *
107 * @param principal The principal.
108 * @throws Throws a security exception.
109 */
110 void removePermissions(Principal principal) throws SecurityException;
111
112 /***
113 * <p>
114 * Grant a {@link Permission}to a given {@link Principal}.
115 *
116 * @param principal The principal.
117 * @param permission The permission.
118 * @throws Throws a security exception if the principal does not exist.
119 */
120 void grantPermission(Principal principal, Permission permission) throws SecurityException;
121
122 /***
123 * <p>
124 * Revoke a {@link Permission}from a given {@link Principal}.
125 *
126 * @param principal The principal.
127 * @param permission The permission.
128 * @throws Throws a security exception.
129 */
130 void revokePermission(Principal principal, Permission permission) throws SecurityException;
131
132 /***
133 * <p>
134 * Check permission for the given subject's access to the resource protected by the permission
135 * This is an abstraction introduced in M4 for Permission Manager implementations NOT
136 * founded upon the a Java security policy.</p>
137 *
138 * @param subject The Java subject.
139 * @param permission The permission, usually a portlet, page or folder type permission.
140 * @return true if the subject has access to the permission protected resource, false
141 * if the subject does not have access.
142 */
143 boolean checkPermission(Subject subject, Permission permission);
144
145 /***
146 * Retrieve a collection of all Permissions in the system ordered by Permission Type, resource
147 * Note that we return a collection of <code>InternalPrincipal</code>
148 *
149 * @return A Java Security collection of <code>InternalPrincipal</code>
150 */
151 Collection getPermissions();
152
153 /***
154 * Retrieve a list of all Permissions in the system for a given resource
155 * The resource can be a prefix, for example "j2-admin" will retrieve all
156 * portlet permissions starting with j2-admin
157 *
158 * @return A Java Security collection of Permissions
159 */
160 Permissions getPermissions(String classname, String resource);
161
162 /***
163 * Update the collection of principals on the given principal,
164 * appropriately granting or revoking principals to the given permission.
165 *
166 * @param permission Permission to be updated
167 * @param principals The new collection of principals based on BasePrincipal
168 * to be associated with this permission
169 * @return
170 * @throws SecurityException
171 */
172 int updatePermission(Permission permission, Collection principals)
173 throws SecurityException;
174
175 /***
176 * Given a permission, return all principals granted to that permission
177 *
178 * @param permission
179 * @return A collection of Java Security Permission objects
180 */
181 public Collection getPrincipals(Permission permission);
182 }