home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / security / Permission.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  7.4 KB  |  216 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Permission.java    1.31 98/09/24
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. /**
  18.  * Abstract class for representing access to a system resource.
  19.  * All permissions have a name (whose interpretation depends on the subclass),
  20.  * as well as abstract functions for defining the semantics of the
  21.  * particular Permission subclass. 
  22.  * 
  23.  * <p>Most Permission objects also include an "actions" list that tells the actions 
  24.  * that are permitted for the object.  For example, 
  25.  * for a <code>java.io.FilePermission</code> object, the permission name is
  26.  * the pathname of a file (or directory), and the actions list
  27.  * (such as "read, write") specifies which actions are granted for the
  28.  * specified file (or for files in the specified directory).
  29.  * The actions list is optional for Permission objects, such as 
  30.  * <code>java.lang.RuntimePermission</code>,
  31.  * that don't need such a list; you either have the named permission (such
  32.  * as "system.exit") or you don't.
  33.  * 
  34.  * <p>An important method that must be implemented by each subclass is
  35.  * the <code>implies</code> method to compare Permissions. Basically,
  36.  * "permission p1 implies permission p2" means that
  37.  * if one is granted permission p1, one is naturally granted permission p2.
  38.  * Thus, this is not an equality test, but rather more of a
  39.  * subset test.
  40.  * 
  41.  * <P> Permission objects are similar to String objects in that they
  42.  * are immutable once they have been created. Subclasses should not
  43.  * provide methods that can change the state of a permission
  44.  * once it has been created.
  45.  *
  46.  * @see Permissions
  47.  * @see PermissionCollection
  48.  *
  49.  * @version 1.31 99/03/26
  50.  *
  51.  * @author Marianne Mueller
  52.  * @author Roland Schemers 
  53.  */
  54.  
  55. public abstract class Permission implements Guard, java.io.Serializable {
  56.  
  57.     private String name;
  58.  
  59.     /**
  60.      * Constructs a permission with the specified name.
  61.      *
  62.      * @param name name of the Permission object being created.
  63.      *
  64.      */
  65.  
  66.     public Permission(String name) {
  67.     this.name = name;
  68.     }
  69.  
  70.     /**
  71.      * Implements the guard interface for a permission. The 
  72.      * <code>SecurityManager.checkPermission</code> method is called, 
  73.      * passing this permission object as the permission to check.
  74.      * Returns silently if access is granted. Otherwise, throws
  75.      * a SecurityException.
  76.      * 
  77.      * @param object the object being guarded (currently ignored).
  78.      *
  79.      * @throws SecurityException
  80.      *        if a security manager exists and its 
  81.      *        <code>checkPermission</code> method doesn't allow access.
  82.      * 
  83.      * @see Guard
  84.      * @see GuardedObject
  85.      * @see SecurityManager#checkPermission
  86.      * 
  87.      */
  88.     public void checkGuard(Object object) throws SecurityException {
  89.     SecurityManager sm = System.getSecurityManager();
  90.     if (sm != null) sm.checkPermission(this);
  91.     }
  92.  
  93.     /**
  94.      * Checks if the specified permission's actions are "implied by" 
  95.      * this object's actions.
  96.      * <P>
  97.      * This must be implemented by subclasses of Permission, as they are the 
  98.      * only ones that can impose semantics on a Permission object.
  99.      * 
  100.      * <p>The <code>implies</code> method is used by the AccessController to determine
  101.      * whether or not a requested permission is implied by another permission that
  102.      * is known to be valid in the current execution context.
  103.      *
  104.      * @param permission the permission to check against.
  105.      *
  106.      * @return true if the specified permission is implied by this object,
  107.      * false if not.
  108.      */
  109.  
  110.     public abstract boolean implies(Permission permission);
  111.  
  112.     /**
  113.      * Checks two Permission objects for equality.
  114.      * <P>
  115.      * Do not use the <code>equals</code> method for making access control
  116.      * decisions; use the <code>implies</code> method.
  117.      *  
  118.      * @param obj the object we are testing for equality with this object.
  119.      *
  120.      * @return true if both Permission objects are equivalent.
  121.      */
  122.  
  123.     public abstract boolean equals(Object obj);
  124.  
  125.     /**
  126.      * Returns the hash code value for this Permission object.
  127.      * <P>
  128.      * The required <code>hashCode</code> behavior for Permission Objects is
  129.      * the following: <p>
  130.      * <ul>
  131.      * <li>Whenever it is invoked on the same Permission object more than 
  132.      *     once during an execution of a Java application, the 
  133.      *     <code>hashCode</code> method
  134.      *     must consistently return the same integer. This integer need not 
  135.      *     remain consistent from one execution of an application to another 
  136.      *     execution of the same application. <p>
  137.      * <li>If two Permission objects are equal according to the 
  138.      *     <code>equals</code> 
  139.      *     method, then calling the <code>hashCode</code> method on each of the
  140.      *     two Permission objects must produce the same integer result. 
  141.      * </ul>
  142.      *
  143.      * @return a hash code value for this object.
  144.      */
  145.  
  146.     public abstract int hashCode();
  147.  
  148.     /**
  149.      * Returns the name of this Permission.
  150.      * For example, in the case of a <code>java.io.FilePermission</code>,
  151.      * the name will be a pathname.
  152.      *
  153.      * @return the name of this Permission.
  154.      * 
  155.      */
  156.  
  157.     public final String getName() {
  158.     return name;
  159.     }
  160.  
  161.     /**
  162.      * Returns the actions as a String. This is abstract
  163.      * so subclasses can defer creating a String representation until 
  164.      * one is needed. Subclasses should always return actions in what they
  165.      * consider to be their
  166.      * canonical form. For example, two FilePermission objects created via
  167.      * the following:
  168.      * 
  169.      * <pre>
  170.      *   perm1 = new FilePermission(p1,"read,write");
  171.      *   perm2 = new FilePermission(p2,"write,read"); 
  172.      * </pre>
  173.      * 
  174.      * both return 
  175.      * "read,write" when the <code>getActions</code> method is invoked.
  176.      *
  177.      * @return the actions of this Permission.
  178.      *
  179.      */
  180.  
  181.     public abstract String getActions();
  182.  
  183.     /**
  184.      * Returns an empty PermissionCollection for a given Permission object, or null if
  185.      * one is not defined. Subclasses of class Permission should 
  186.      * override this if they need to store their permissions in a particular
  187.      * PermissionCollection object in order to provide the correct semantics
  188.      * when the <code>PermissionCollection.implies</code> method is called. 
  189.      * If null is returned,
  190.      * then the caller of this method is free to store permissions of this
  191.      * type in any PermissionCollection they choose (one that uses a Hashtable,
  192.      * one that uses a Vector, etc).
  193.      *
  194.      * @return a new PermissionCollection object for this type of Permission, or 
  195.      * null if one is not defined.
  196.      */
  197.  
  198.     public PermissionCollection newPermissionCollection() {
  199.     return null;
  200.     }
  201.  
  202.     /**
  203.      * Returns a string describing this Permission.  The convention is to
  204.      * specify the class name, the permission name, and the actions in
  205.      * the following format: '("ClassName" "name" "actions")'.
  206.      * 
  207.      * @return information about this Permission.
  208.      */
  209.  
  210.     public String toString() {
  211.     return "(" + getClass().getName() + " " + 
  212.                       name + " " + getActions() + ")";
  213.     }
  214. }
  215.  
  216.