001 /* Permission.java -- The superclass for all permission objects 002 Copyright (C) 1998, 2001, 2002, 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package java.security; 039 040 import java.io.Serializable; 041 042 /** 043 * This class is the abstract superclass of all classes that implement 044 * the concept of a permission. A permission consists of a permission name 045 * and optionally a list of actions that relate to the permission. The 046 * actual meaning of the name of the permission is defined only in the 047 * context of a subclass. It may name a resource to which access permissions 048 * are granted (for example, the name of a file) or it might represent 049 * something else entirely. Similarly, the action list only has meaning 050 * within the context of a subclass. Some permission names may have no 051 * actions associated with them. That is, you either have the permission 052 * or you don't. 053 * 054 * <p>The most important method in this class is <code>implies</code>. This 055 * checks whether if one has this permission, then the specified 056 * permission is also implied. As a conceptual example, consider the 057 * permissions "Read All Files" and "Read File foo". The permission 058 * "Read All Files" implies that the caller has permission to read the 059 * file foo. 060 * 061 * <p><code>Permission</code>'s must be immutable - do not change their 062 * state after creation. 063 * 064 * @author Aaron M. Renn (arenn@urbanophile.com) 065 * @see Permissions 066 * @see PermissionCollection 067 * @since 1.1 068 * @status updated to 1.4 069 */ 070 public abstract class Permission implements Guard, Serializable 071 { 072 /** 073 * Compatible with JDK 1.1+. 074 */ 075 private static final long serialVersionUID = -5636570222231596674L; 076 077 /** 078 * This is the name assigned to this permission object. 079 * 080 * @serial the name of the permission 081 */ 082 private String name; 083 084 /** 085 * Create an instance with the specified name. 086 * 087 * @param name the permission name 088 */ 089 public Permission(String name) 090 { 091 this.name = name; 092 } 093 094 /** 095 * This method implements the <code>Guard</code> interface for this class. 096 * It calls the <code>checkPermission</code> method in 097 * <code>SecurityManager</code> with this <code>Permission</code> as its 098 * argument. This method returns silently if the security check succeeds 099 * or throws an exception if it fails. 100 * 101 * @param obj the <code>Object</code> being guarded - ignored by this class 102 * @throws SecurityException if the security check fails 103 * @see GuardedObject 104 * @see SecurityManager#checkPermission(Permission) 105 */ 106 public void checkGuard(Object obj) 107 { 108 SecurityManager sm = System.getSecurityManager(); 109 if (sm != null) 110 sm.checkPermission(this); 111 } 112 113 /** 114 * This method tests whether this <code>Permission</code> implies that the 115 * specified <code>Permission</code> is also granted. 116 * 117 * @param perm the <code>Permission</code> to test against 118 * @return true if perm is implied by this 119 */ 120 public abstract boolean implies(Permission perm); 121 122 /** 123 * Check to see if this object equals obj. Use <code>implies</code>, rather 124 * than <code>equals</code>, when making access control decisions. 125 * 126 * @param obj the object to compare to 127 */ 128 public abstract boolean equals(Object obj); 129 130 /** 131 * This method returns a hash code for this <code>Permission</code>. It 132 * must satisfy the contract of <code>Object.hashCode</code>: it must be 133 * the same for all objects that equals considers to be the same. 134 * 135 * @return a hash value 136 */ 137 public abstract int hashCode(); 138 139 /** 140 * Get the name of this <code>Permission</code>. 141 * 142 * @return the name 143 */ 144 public final String getName() 145 { 146 return name; 147 } 148 149 /** 150 * This method returns the list of actions for this <code>Permission</code> 151 * as a <code>String</code>. The string should be in canonical order, for 152 * example, both <code>new FilePermission(f, "write,read")</code> and 153 * <code>new FilePermission(f, "read,write")</code> have the action list 154 * "read,write". 155 * 156 * @return the action list for this <code>Permission</code> 157 */ 158 public abstract String getActions(); 159 160 /** 161 * This method returns an empty <code>PermissionCollection</code> object 162 * that can store permissions of this type, or <code>null</code> if no 163 * such collection is defined. Subclasses must override this to provide 164 * an appropriate collection when one is needed to accurately calculate 165 * <code>implies</code>. 166 * 167 * @return a new <code>PermissionCollection</code> 168 */ 169 public PermissionCollection newPermissionCollection() 170 { 171 return null; 172 } 173 174 /** 175 * This method returns a <code>String</code> representation of this 176 * <code>Permission</code> object. This is in the format: 177 * <code>'(' + getClass().getName() + ' ' + getName() + ' ' + getActions 178 * + ')'</code>. 179 * 180 * @return this object as a <code>String</code> 181 */ 182 public String toString() 183 { 184 StringBuffer string = new StringBuffer(); 185 186 string = string.append('('); 187 string = string.append(getClass().getName()); 188 string = string.append(' '); 189 string = string.append(getName()); 190 191 if (!(getActions().equals(""))) 192 { 193 string = string.append(' '); 194 string = string.append(getActions()); 195 } 196 197 string = string.append(')'); 198 return string.toString(); 199 } 200 } // class Permission