1 /* 2 * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.security; 27 28 /** 29 * Abstract class for representing access to a system resource. 30 * All permissions have a name (whose interpretation depends on the subclass), 31 * as well as abstract functions for defining the semantics of the 32 * particular Permission subclass. 33 * 34 * <p>Most Permission objects also include an "actions" list that tells the actions 35 * that are permitted for the object. For example, 36 * for a <code>java.io.FilePermission</code> object, the permission name is 37 * the pathname of a file (or directory), and the actions list 38 * (such as "read, write") specifies which actions are granted for the 39 * specified file (or for files in the specified directory). 40 * The actions list is optional for Permission objects, such as 41 * <code>java.lang.RuntimePermission</code>, 42 * that don't need such a list; you either have the named permission (such 43 * as "system.exit") or you don't. 44 * 45 * <p>An important method that must be implemented by each subclass is 46 * the <code>implies</code> method to compare Permissions. Basically, 47 * "permission p1 implies permission p2" means that 48 * if one is granted permission p1, one is naturally granted permission p2. 49 * Thus, this is not an equality test, but rather more of a 50 * subset test. 51 * 52 * <P> Permission objects are similar to String objects in that they 53 * are immutable once they have been created. Subclasses should not 54 * provide methods that can change the state of a permission 55 * once it has been created. 56 * 57 * @see Permissions 58 * @see PermissionCollection 59 * 60 * 61 * @author Marianne Mueller 62 * @author Roland Schemers 63 */ 64 65 public abstract class Permission implements Guard, java.io.Serializable { 66 67 private static final long serialVersionUID = -5636570222231596674L; 68 69 private String name; 70 71 /** 72 * Constructs a permission with the specified name. 73 * 74 * @param name name of the Permission object being created. 75 * 76 */ 77 78 public Permission(String name) { 79 this.name = name; 80 } 81 82 /** 83 * Implements the guard interface for a permission. The 84 * <code>SecurityManager.checkPermission</code> method is called, 85 * passing this permission object as the permission to check. 86 * Returns silently if access is granted. Otherwise, throws 87 * a SecurityException. 88 * 89 * @param object the object being guarded (currently ignored). 90 * 91 * @throws SecurityException 92 * if a security manager exists and its 93 * <code>checkPermission</code> method doesn't allow access. 94 * 95 * @see Guard 96 * @see GuardedObject 97 * @see SecurityManager#checkPermission 98 * 99 */ 100 public void checkGuard(Object object) throws SecurityException { 101 SecurityManager sm = System.getSecurityManager(); 102 if (sm != null) sm.checkPermission(this); 103 } 104 105 /** 106 * Checks if the specified permission's actions are "implied by" 107 * this object's actions. 108 * <P> 109 * This must be implemented by subclasses of Permission, as they are the 110 * only ones that can impose semantics on a Permission object. 111 * 112 * <p>The <code>implies</code> method is used by the AccessController to determine 113 * whether or not a requested permission is implied by another permission that 114 * is known to be valid in the current execution context. 115 * 116 * @param permission the permission to check against. 117 * 118 * @return true if the specified permission is implied by this object, 119 * false if not. 120 */ 121 122 public abstract boolean implies(Permission permission); 123 124 /** 125 * Checks two Permission objects for equality. 126 * <P> 127 * Do not use the <code>equals</code> method for making access control 128 * decisions; use the <code>implies</code> method. 129 * 130 * @param obj the object we are testing for equality with this object. 131 * 132 * @return true if both Permission objects are equivalent. 133 */ 134 135 public abstract boolean equals(Object obj); 136 137 /** 138 * Returns the hash code value for this Permission object. 139 * <P> 140 * The required <code>hashCode</code> behavior for Permission Objects is 141 * the following: <p> 142 * <ul> 143 * <li>Whenever it is invoked on the same Permission object more than 144 * once during an execution of a Java application, the 145 * <code>hashCode</code> method 146 * must consistently return the same integer. This integer need not 147 * remain consistent from one execution of an application to another 148 * execution of the same application. <p> 149 * <li>If two Permission objects are equal according to the 150 * <code>equals</code> 151 * method, then calling the <code>hashCode</code> method on each of the 152 * two Permission objects must produce the same integer result. 153 * </ul> 154 * 155 * @return a hash code value for this object. 156 */ 157 158 public abstract int hashCode(); 159 160 /** 161 * Returns the name of this Permission. 162 * For example, in the case of a <code>java.io.FilePermission</code>, 163 * the name will be a pathname. 164 * 165 * @return the name of this Permission. 166 * 167 */ 168 169 public final String getName() { 170 return name; 171 } 172 173 /** 174 * Returns the actions as a String. This is abstract 175 * so subclasses can defer creating a String representation until 176 * one is needed. Subclasses should always return actions in what they 177 * consider to be their 178 * canonical form. For example, two FilePermission objects created via 179 * the following: 180 * 181 * <pre> 182 * perm1 = new FilePermission(p1,"read,write"); 183 * perm2 = new FilePermission(p2,"write,read"); 184 * </pre> 185 * 186 * both return 187 * "read,write" when the <code>getActions</code> method is invoked. 188 * 189 * @return the actions of this Permission. 190 * 191 */ 192 193 public abstract String getActions(); 194 195 /** 196 * Returns an empty PermissionCollection for a given Permission object, or null if 197 * one is not defined. Subclasses of class Permission should 198 * override this if they need to store their permissions in a particular 199 * PermissionCollection object in order to provide the correct semantics 200 * when the <code>PermissionCollection.implies</code> method is called. 201 * If null is returned, 202 * then the caller of this method is free to store permissions of this 203 * type in any PermissionCollection they choose (one that uses a Hashtable, 204 * one that uses a Vector, etc). 205 * 206 * @return a new PermissionCollection object for this type of Permission, or 207 * null if one is not defined. 208 */ 209 210 public PermissionCollection newPermissionCollection() { 211 return null; 212 } 213 214 /** 215 * Returns a string describing this Permission. The convention is to 216 * specify the class name, the permission name, and the actions in 217 * the following format: '("ClassName" "name" "actions")', or 218 * '("ClassName" "name")' if actions list is null or empty. 219 * 220 * @return information about this Permission. | 1 /* 2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.security; 27 28 /** 29 * Abstract class for representing access to a system resource. 30 * All permissions have a name (whose interpretation depends on the subclass), 31 * as well as abstract functions for defining the semantics of the 32 * particular Permission subclass. 33 * 34 * <p>Most Permission objects also include an "actions" list that tells the actions 35 * that are permitted for the object. For example, 36 * for a {@code java.io.FilePermission} object, the permission name is 37 * the pathname of a file (or directory), and the actions list 38 * (such as "read, write") specifies which actions are granted for the 39 * specified file (or for files in the specified directory). 40 * The actions list is optional for Permission objects, such as 41 * {@code java.lang.RuntimePermission}, 42 * that don't need such a list; you either have the named permission (such 43 * as "system.exit") or you don't. 44 * 45 * <p>An important method that must be implemented by each subclass is 46 * the {@code implies} method to compare Permissions. Basically, 47 * "permission p1 implies permission p2" means that 48 * if one is granted permission p1, one is naturally granted permission p2. 49 * Thus, this is not an equality test, but rather more of a 50 * subset test. 51 * 52 * <P> Permission objects are similar to String objects in that they 53 * are immutable once they have been created. Subclasses should not 54 * provide methods that can change the state of a permission 55 * once it has been created. 56 * 57 * @see Permissions 58 * @see PermissionCollection 59 * 60 * 61 * @author Marianne Mueller 62 * @author Roland Schemers 63 */ 64 65 public abstract class Permission implements Guard, java.io.Serializable { 66 67 private static final long serialVersionUID = -5636570222231596674L; 68 69 private String name; 70 71 /** 72 * Constructs a permission with the specified name. 73 * 74 * @param name name of the Permission object being created. 75 * 76 */ 77 78 public Permission(String name) { 79 this.name = name; 80 } 81 82 /** 83 * Implements the guard interface for a permission. The 84 * {@code SecurityManager.checkPermission} method is called, 85 * passing this permission object as the permission to check. 86 * Returns silently if access is granted. Otherwise, throws 87 * a SecurityException. 88 * 89 * @param object the object being guarded (currently ignored). 90 * 91 * @throws SecurityException 92 * if a security manager exists and its 93 * {@code checkPermission} method doesn't allow access. 94 * 95 * @see Guard 96 * @see GuardedObject 97 * @see SecurityManager#checkPermission 98 * 99 */ 100 public void checkGuard(Object object) throws SecurityException { 101 SecurityManager sm = System.getSecurityManager(); 102 if (sm != null) sm.checkPermission(this); 103 } 104 105 /** 106 * Checks if the specified permission's actions are "implied by" 107 * this object's actions. 108 * <P> 109 * This must be implemented by subclasses of Permission, as they are the 110 * only ones that can impose semantics on a Permission object. 111 * 112 * <p>The {@code implies} method is used by the AccessController to determine 113 * whether or not a requested permission is implied by another permission that 114 * is known to be valid in the current execution context. 115 * 116 * @param permission the permission to check against. 117 * 118 * @return true if the specified permission is implied by this object, 119 * false if not. 120 */ 121 122 public abstract boolean implies(Permission permission); 123 124 /** 125 * Checks two Permission objects for equality. 126 * <P> 127 * Do not use the {@code equals} method for making access control 128 * decisions; use the {@code implies} method. 129 * 130 * @param obj the object we are testing for equality with this object. 131 * 132 * @return true if both Permission objects are equivalent. 133 */ 134 135 public abstract boolean equals(Object obj); 136 137 /** 138 * Returns the hash code value for this Permission object. 139 * <P> 140 * The required {@code hashCode} behavior for Permission Objects is 141 * the following: <p> 142 * <ul> 143 * <li>Whenever it is invoked on the same Permission object more than 144 * once during an execution of a Java application, the 145 * {@code hashCode} method 146 * must consistently return the same integer. This integer need not 147 * remain consistent from one execution of an application to another 148 * execution of the same application. <p> 149 * <li>If two Permission objects are equal according to the 150 * {@code equals} 151 * method, then calling the {@code hashCode} method on each of the 152 * two Permission objects must produce the same integer result. 153 * </ul> 154 * 155 * @return a hash code value for this object. 156 */ 157 158 public abstract int hashCode(); 159 160 /** 161 * Returns the name of this Permission. 162 * For example, in the case of a {@code java.io.FilePermission}, 163 * the name will be a pathname. 164 * 165 * @return the name of this Permission. 166 * 167 */ 168 169 public final String getName() { 170 return name; 171 } 172 173 /** 174 * Returns the actions as a String. This is abstract 175 * so subclasses can defer creating a String representation until 176 * one is needed. Subclasses should always return actions in what they 177 * consider to be their 178 * canonical form. For example, two FilePermission objects created via 179 * the following: 180 * 181 * <pre> 182 * perm1 = new FilePermission(p1,"read,write"); 183 * perm2 = new FilePermission(p2,"write,read"); 184 * </pre> 185 * 186 * both return 187 * "read,write" when the {@code getActions} method is invoked. 188 * 189 * @return the actions of this Permission. 190 * 191 */ 192 193 public abstract String getActions(); 194 195 /** 196 * Returns an empty PermissionCollection for a given Permission object, or null if 197 * one is not defined. Subclasses of class Permission should 198 * override this if they need to store their permissions in a particular 199 * PermissionCollection object in order to provide the correct semantics 200 * when the {@code PermissionCollection.implies} method is called. 201 * If null is returned, 202 * then the caller of this method is free to store permissions of this 203 * type in any PermissionCollection they choose (one that uses a Hashtable, 204 * one that uses a Vector, etc). 205 * 206 * @return a new PermissionCollection object for this type of Permission, or 207 * null if one is not defined. 208 */ 209 210 public PermissionCollection newPermissionCollection() { 211 return null; 212 } 213 214 /** 215 * Returns a string describing this Permission. The convention is to 216 * specify the class name, the permission name, and the actions in 217 * the following format: '("ClassName" "name" "actions")', or 218 * '("ClassName" "name")' if actions list is null or empty. 219 * 220 * @return information about this Permission. |