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 gnu.java.lang.CPStringBuilder; 041 042 import java.io.Serializable; 043 044 /** 045 * This class is the abstract superclass of all classes that implement 046 * the concept of a permission. A permission consists of a permission name 047 * and optionally a list of actions that relate to the permission. The 048 * actual meaning of the name of the permission is defined only in the 049 * context of a subclass. It may name a resource to which access permissions 050 * are granted (for example, the name of a file) or it might represent 051 * something else entirely. Similarly, the action list only has meaning 052 * within the context of a subclass. Some permission names may have no 053 * actions associated with them. That is, you either have the permission 054 * or you don't. 055 * 056 * <p>The most important method in this class is <code>implies</code>. This 057 * checks whether if one has this permission, then the specified 058 * permission is also implied. As a conceptual example, consider the 059 * permissions "Read All Files" and "Read File foo". The permission 060 * "Read All Files" implies that the caller has permission to read the 061 * file foo. 062 * 063 * <p><code>Permission</code>'s must be immutable - do not change their 064 * state after creation. 065 * 066 * @author Aaron M. Renn (arenn@urbanophile.com) 067 * @see Permissions 068 * @see PermissionCollection 069 * @since 1.1 070 * @status updated to 1.4 071 */ 072 public abstract class Permission implements Guard, Serializable 073 { 074 /** 075 * Compatible with JDK 1.1+. 076 */ 077 private static final long serialVersionUID = -5636570222231596674L; 078 079 /** 080 * This is the name assigned to this permission object. 081 * 082 * @serial the name of the permission 083 */ 084 private String name; 085 086 /** 087 * Create an instance with the specified name. 088 * 089 * @param name the permission name 090 */ 091 public Permission(String name) 092 { 093 this.name = name; 094 } 095 096 /** 097 * This method implements the <code>Guard</code> interface for this class. 098 * It calls the <code>checkPermission</code> method in 099 * <code>SecurityManager</code> with this <code>Permission</code> as its 100 * argument. This method returns silently if the security check succeeds 101 * or throws an exception if it fails. 102 * 103 * @param obj the <code>Object</code> being guarded - ignored by this class 104 * @throws SecurityException if the security check fails 105 * @see GuardedObject 106 * @see SecurityManager#checkPermission(Permission) 107 */ 108 public void checkGuard(Object obj) 109 { 110 SecurityManager sm = System.getSecurityManager(); 111 if (sm != null) 112 sm.checkPermission(this); 113 } 114 115 /** 116 * This method tests whether this <code>Permission</code> implies that the 117 * specified <code>Permission</code> is also granted. 118 * 119 * @param perm the <code>Permission</code> to test against 120 * @return true if perm is implied by this 121 */ 122 public abstract boolean implies(Permission perm); 123 124 /** 125 * Check to see if this object equals obj. Use <code>implies</code>, rather 126 * than <code>equals</code>, when making access control decisions. 127 * 128 * @param obj the object to compare to 129 */ 130 public abstract boolean equals(Object obj); 131 132 /** 133 * This method returns a hash code for this <code>Permission</code>. It 134 * must satisfy the contract of <code>Object.hashCode</code>: it must be 135 * the same for all objects that equals considers to be the same. 136 * 137 * @return a hash value 138 */ 139 public abstract int hashCode(); 140 141 /** 142 * Get the name of this <code>Permission</code>. 143 * 144 * @return the name 145 */ 146 public final String getName() 147 { 148 return name; 149 } 150 151 /** 152 * This method returns the list of actions for this <code>Permission</code> 153 * as a <code>String</code>. The string should be in canonical order, for 154 * example, both <code>new FilePermission(f, "write,read")</code> and 155 * <code>new FilePermission(f, "read,write")</code> have the action list 156 * "read,write". 157 * 158 * @return the action list for this <code>Permission</code> 159 */ 160 public abstract String getActions(); 161 162 /** 163 * This method returns an empty <code>PermissionCollection</code> object 164 * that can store permissions of this type, or <code>null</code> if no 165 * such collection is defined. Subclasses must override this to provide 166 * an appropriate collection when one is needed to accurately calculate 167 * <code>implies</code>. 168 * 169 * @return a new <code>PermissionCollection</code> 170 */ 171 public PermissionCollection newPermissionCollection() 172 { 173 return null; 174 } 175 176 /** 177 * This method returns a <code>String</code> representation of this 178 * <code>Permission</code> object. This is in the format: 179 * <code>'(' + getClass().getName() + ' ' + getName() + ' ' + getActions 180 * + ')'</code>. 181 * 182 * @return this object as a <code>String</code> 183 */ 184 public String toString() 185 { 186 CPStringBuilder string = new CPStringBuilder(); 187 188 string = string.append('('); 189 string = string.append(getClass().getName()); 190 string = string.append(' '); 191 string = string.append(getName()); 192 193 if (!(getActions().equals(""))) 194 { 195 string = string.append(' '); 196 string = string.append(getActions()); 197 } 198 199 string = string.append(')'); 200 return string.toString(); 201 } 202 } // class Permission