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 * @since 1.2 64 */ 65 66 public abstract class Permission implements Guard, java.io.Serializable { 67 68 private static final long serialVersionUID = -5636570222231596674L; 69 70 private String name; 71 72 /** 73 * Constructs a permission with the specified name. 74 * 75 * @param name name of the Permission object being created. 76 * 77 */ 78 79 public Permission(String name) { 80 this.name = name; 81 } 82 83 /** 84 * Implements the guard interface for a permission. The 85 * {@code SecurityManager.checkPermission} method is called, 86 * passing this permission object as the permission to check. 87 * Returns silently if access is granted. Otherwise, throws 88 * a SecurityException. 89 * 90 * @param object the object being guarded (currently ignored). 91 * 92 * @throws SecurityException 93 * if a security manager exists and its 94 * {@code checkPermission} method doesn't allow access. 95 * 96 * @see Guard 97 * @see GuardedObject 98 * @see SecurityManager#checkPermission 99 * 100 */ 101 public void checkGuard(Object object) throws SecurityException { 102 SecurityManager sm = System.getSecurityManager(); 103 if (sm != null) sm.checkPermission(this); 104 } 105 106 /** 107 * Checks if the specified permission's actions are "implied by" 108 * this object's actions. 109 * <P> 110 * This must be implemented by subclasses of Permission, as they are the 111 * only ones that can impose semantics on a Permission object. 112 * 113 * <p>The {@code implies} method is used by the AccessController to determine 114 * whether or not a requested permission is implied by another permission that 115 * is known to be valid in the current execution context. 116 * 117 * @param permission the permission to check against. 118 * 119 * @return true if the specified permission is implied by this object, 120 * false if not. 121 */ 122 123 public abstract boolean implies(Permission permission); 124 125 /** 126 * Checks two Permission objects for equality. 127 * <P> 128 * Do not use the {@code equals} method for making access control 129 * decisions; use the {@code implies} method. 130 * 131 * @param obj the object we are testing for equality with this object. 132 * 133 * @return true if both Permission objects are equivalent. 134 */ 135 136 public abstract boolean equals(Object obj); 137 138 /** 139 * Returns the hash code value for this Permission object. 140 * <P> 141 * The required {@code hashCode} behavior for Permission Objects is 142 * the following: 143 * <ul> 144 * <li>Whenever it is invoked on the same Permission object more than 145 * once during an execution of a Java application, the 146 * {@code hashCode} method 147 * must consistently return the same integer. This integer need not 148 * remain consistent from one execution of an application to another 149 * execution of the same application. 150 * <li>If two Permission objects are equal according to the 151 * {@code equals} 152 * method, then calling the {@code hashCode} method on each of the 153 * two Permission objects must produce the same integer result. 154 * </ul> 155 * 156 * @return a hash code value for this object. 157 */ 158 159 public abstract int hashCode(); 160 161 /** 162 * Returns the name of this Permission. 163 * For example, in the case of a {@code java.io.FilePermission}, 164 * the name will be a pathname. 165 * 166 * @return the name of this Permission. 167 * 168 */ 169 170 public final String getName() { 171 return name; 172 } 173 174 /** 175 * Returns the actions as a String. This is abstract 176 * so subclasses can defer creating a String representation until 177 * one is needed. Subclasses should always return actions in what they 178 * consider to be their 179 * canonical form. For example, two FilePermission objects created via 180 * the following: 181 * 182 * <pre> 183 * perm1 = new FilePermission(p1,"read,write"); 184 * perm2 = new FilePermission(p2,"write,read"); 185 * </pre> 186 * 187 * both return 188 * "read,write" when the {@code getActions} method is invoked. 189 * 190 * @return the actions of this Permission. 191 * 192 */ 193 194 public abstract String getActions(); 195 196 /** 197 * Returns an empty PermissionCollection for a given Permission object, or null if 198 * one is not defined. Subclasses of class Permission should 199 * override this if they need to store their permissions in a particular 200 * PermissionCollection object in order to provide the correct semantics 201 * when the {@code PermissionCollection.implies} method is called. 202 * If null is returned, 203 * then the caller of this method is free to store permissions of this 204 * type in any PermissionCollection they choose (one that uses a Hashtable, 205 * one that uses a Vector, etc). 206 * 207 * @return a new PermissionCollection object for this type of Permission, or 208 * null if one is not defined. 209 */ 210 211 public PermissionCollection newPermissionCollection() { 212 return null; 213 } 214 215 /** 216 * Returns a string describing this Permission. The convention is to 217 * specify the class name, the permission name, and the actions in 218 * the following format: '("ClassName" "name" "actions")', or 219 * '("ClassName" "name")' if actions list is null or empty. 220 * 221 * @return information about this Permission. 222 */ 223 public String toString() { 224 String actions = getActions(); 225 if ((actions == null) || (actions.length() == 0)) { // OPTIONAL 226 return "(\"" + getClass().getName() + "\" \"" + name + "\")"; 227 } else { 228 return "(\"" + getClass().getName() + "\" \"" + name + 229 "\" \"" + actions + "\")"; 230 } 231 } 232 }