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.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 &quot;theUserPrincipal&quot;
42   *  {
43   *      permission o.a.j.security.PortletPermission &quot;myportlet&quot;, &quot;view,edit,minimize,maximize&quot;;
44   *  };
45   *  
46   * </code>
47   * &lt;pre&gt;
48   *  @author &lt;a href=&quot;mailto:dlestrat@apache.org&quot;&gt;David Le Strat&lt;/a&gt;
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 }