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.security.Permission;
020: import java.security.Permissions;
021: import java.security.Principal;
022: import java.util.Collection;
023: import javax.security.auth.Subject;
024:
025: /**
026: * <p>
027: * Describe the interface for managing {@link Permission}and permission
028: * association to {@link Principal}. Permissions are used to manage Principals
029: * access entitlement on specified resources.
030: * </p>
031: * <p>
032: * The permission manager does not enforce any hierarchy resolution, all relevant
033: * principals must be passed to the permission manager to assess the proper permissions.
034: * </p>
035: * <p>
036: * For instance:
037: * </p>
038: *
039: * <pre><code>
040: *
041: * grant principal o.a.j.security.UserPrincipal "theUserPrincipal"
042: * {
043: * permission o.a.j.security.PortletPermission "myportlet", "view,edit,minimize,maximize";
044: * };
045: *
046: * </code>
047: * <pre>
048: * @author <a href="mailto:dlestrat@apache.org">David Le Strat</a>
049: *
050: */
051: public interface PermissionManager {
052:
053: /**
054: * <p>
055: * Gets the {@link Permissions}given a {@link Principal}.
056: *
057: * @param principal The principal.
058: * @return The permissions.
059: */
060: Permissions getPermissions(Principal principal);
061:
062: /**
063: * <p>
064: * Gets the {@link Permissions}given a collection of {@link Principal}.
065: *
066: * @param principals A collection of principal.
067: * @return The permissions.
068: */
069: Permissions getPermissions(Collection principals);
070:
071: /**
072: * <p>
073: * Adds a permission definition.
074: * </p>
075: *
076: * @param permission The permission to add.
077: * @throws Throws a security exception.
078: */
079: void addPermission(Permission permission) throws SecurityException;
080:
081: /**
082: * <p>
083: * Remove all instances of a given permission.
084: * </p>
085: *
086: * @param permission The permission to remove.
087: * @throws Throws a security exception.
088: */
089: void removePermission(Permission permission)
090: throws SecurityException;
091:
092: /**
093: * <p>
094: * Whether the given permission exists.
095: * </p>
096: *
097: * @param permission The permission to look for.
098: * @return Whether the permission exists.
099: */
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)
111: throws SecurityException;
112:
113: /**
114: * <p>
115: * Grant a {@link Permission}to a given {@link Principal}.
116: *
117: * @param principal The principal.
118: * @param permission The permission.
119: * @throws Throws a security exception if the principal does not exist.
120: */
121: void grantPermission(Principal principal, Permission permission)
122: throws SecurityException;
123:
124: /**
125: * <p>
126: * Revoke a {@link Permission}from a given {@link Principal}.
127: *
128: * @param principal The principal.
129: * @param permission The permission.
130: * @throws Throws a security exception.
131: */
132: void revokePermission(Principal principal, Permission permission)
133: throws SecurityException;
134:
135: /**
136: * <p>
137: * Check permission for the given subject's access to the resource protected by the permission
138: * This is an abstraction introduced in M4 for Permission Manager implementations NOT
139: * founded upon the a Java security policy.</p>
140: *
141: * @param subject The Java subject.
142: * @param permission The permission, usually a portlet, page or folder type permission.
143: * @return true if the subject has access to the permission protected resource, false
144: * if the subject does not have access.
145: */
146: boolean checkPermission(Subject subject, Permission permission);
147:
148: /**
149: * Retrieve a collection of all Permissions in the system ordered by Permission Type, resource
150: * Note that we return a collection of <code>InternalPrincipal</code>
151: *
152: * @return A Java Security collection of <code>InternalPrincipal</code>
153: */
154: Collection getPermissions();
155:
156: /**
157: * Retrieve a list of all Permissions in the system for a given resource
158: * The resource can be a prefix, for example "j2-admin" will retrieve all
159: * portlet permissions starting with j2-admin
160: *
161: * @return A Java Security collection of Permissions
162: */
163: Permissions getPermissions(String classname, String resource);
164:
165: /**
166: * Update the collection of principals on the given principal,
167: * appropriately granting or revoking principals to the given permission.
168: *
169: * @param permission Permission to be updated
170: * @param principals The new collection of principals based on BasePrincipal
171: * to be associated with this permission
172: * @return
173: * @throws SecurityException
174: */
175: int updatePermission(Permission permission, Collection principals)
176: throws SecurityException;
177:
178: /**
179: * Given a permission, return all principals granted to that permission
180: *
181: * @param permission
182: * @return A collection of Java Security Permission objects
183: */
184: public Collection getPrincipals(Permission permission);
185: }
|