libjava/java/security/Permission.java

   1 /* Permission.java -- The superclass for all permission objects
   2    Copyright (C) 1998, 2001, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.security;
  39
  40 import java.io.Serializable;
  41
  42 /**
  43  * This class is the abstract superclass of all classes that implement
  44  * the concept of a permission.  A permission consists of a permission name
  45  * and optionally a list of actions that relate to the permission.  The
  46  * actual meaning of the name of the permission is defined only in the
  47  * context of a subclass.  It may name a resource to which access permissions
  48  * are granted (for example, the name of a file) or it might represent
  49  * something else entirely.  Similarly, the action list only has meaning
  50  * within the context of a subclass.  Some permission names may have no
  51  * actions associated with them.  That is, you either have the permission
  52  * or you don't.
  53  *
  54  * <p>The most important method in this class is <code>implies</code>.  This
  55  * checks whether if one has this permission, then the specified
  56  * permission is also implied.  As a conceptual example, consider the
  57  * permissions "Read All Files" and "Read File foo".  The permission
  58  * "Read All Files" implies that the caller has permission to read the
  59  * file foo.
  60  *
  61  * <p><code>Permission</code>'s must be immutable - do not change their
  62  * state after creation.
  63  *
  64  * @author Aaron M. Renn (arenn@urbanophile.com)
  65  * @see Permissions
  66  * @see PermissionCollection
  67  * @since 1.1
  68  * @status updated to 1.4
  69  */
  70 public abstract class Permission implements Guard, Serializable
  71 {
  72   /**
  73    * Compatible with JDK 1.1+.
  74    */
  75   private static final long serialVersionUID = -5636570222231596674L;
  76
  77   /**
  78    * This is the name assigned to this permission object.
  79    *
  80    * @serial the name of the permission
  81    */
  82   private String name;
  83
  84   /**
  85    * Create an instance with the specified name.
  86    *
  87    * @param name the permission name
  88    */
  89   public Permission(String name)
  90   {
  91     this.name = name;
  92   }
  93
  94   /**
  95    * This method implements the <code>Guard</code> interface for this class.
  96    * It calls the <code>checkPermission</code> method in
  97    * <code>SecurityManager</code> with this <code>Permission</code> as its
  98    * argument.  This method returns silently if the security check succeeds
  99    * 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     return '(' + getClass().getName() + ' ' + getName() + ' '
 185       + getActions() + ')';
 186   }
 187 } // class Permission