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