      1 /*
      2  * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
      3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
      4  *
      5  * This code is free software; you can redistribute it and/or modify it
      6  * under the terms of the GNU General Public License version 2 only, as
      7  * published by the Free Software Foundation.  Oracle designates this
      8  * particular file as subject to the "Classpath" exception as provided
      9  * by Oracle in the LICENSE file that accompanied this code.
     10  *
     11  * This code is distributed in the hope that it will be useful, but WITHOUT
     12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
     13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
     14  * version 2 for more details (a copy is included in the LICENSE file that
     15  * accompanied this code).
     16  *
     17  * You should have received a copy of the GNU General Public License version
     18  * 2 along with this work; if not, write to the Free Software Foundation,
     19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
     20  *
     21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
     22  * or visit www.oracle.com if you need additional information or have any
     23  * questions.
     24  */
     25
     26 package java.security;
     27
     28 /**
     29  * Abstract class for representing access to a system resource.
     30  * All permissions have a name (whose interpretation depends on the subclass),
     31  * as well as abstract functions for defining the semantics of the
     32  * particular Permission subclass.
     33  *
     34  * <p>Most Permission objects also include an "actions" list that tells the actions
     35  * that are permitted for the object.  For example,
     36  * for a {@code java.io.FilePermission} object, the permission name is
     37  * the pathname of a file (or directory), and the actions list
     38  * (such as "read, write") specifies which actions are granted for the
     39  * specified file (or for files in the specified directory).
     40  * The actions list is optional for Permission objects, such as
     41  * {@code java.lang.RuntimePermission},
     42  * that don't need such a list; you either have the named permission (such
     43  * as "system.exit") or you don't.
     44  *
     45  * <p>An important method that must be implemented by each subclass is
     46  * the {@code implies} method to compare Permissions. Basically,
     47  * "permission p1 implies permission p2" means that
     48  * if one is granted permission p1, one is naturally granted permission p2.
     49  * Thus, this is not an equality test, but rather more of a
     50  * subset test.
     51  *
     52  * <P> Permission objects are similar to String objects in that they
     53  * are immutable once they have been created. Subclasses should not
     54  * provide methods that can change the state of a permission
     55  * once it has been created.
     56  *
     57  * @see Permissions
     58  * @see PermissionCollection
     59  *
     60  *
     61  * @author Marianne Mueller
     62  * @author Roland Schemers
     63  * @since 1.2
     64  */
     65
     66 public abstract class Permission implements Guard, java.io.Serializable {
     67
     68     @java.io.Serial
     69     private static final long serialVersionUID = -5636570222231596674L;
     70

     71     private String name;
     72
     73     /**
     74      * Constructs a permission with the specified name.
     75      *
     76      * @param name name of the Permission object being created.
     77      *
     78      */
     79
     80     public Permission(String name) {
     81         this.name = name;
     82     }
     83
     84     /**
     85      * Implements the guard interface for a permission. The
     86      * {@code SecurityManager.checkPermission} method is called,
     87      * passing this permission object as the permission to check.
     88      * Returns silently if access is granted. Otherwise, throws
     89      * a SecurityException.
     90      *
     91      * @param object the object being guarded (currently ignored).
     92      *
     93      * @throws SecurityException
     94      *        if a security manager exists and its
     95      *        {@code checkPermission} method doesn't allow access.
     96      *
     97      * @see Guard
     98      * @see GuardedObject
     99      * @see SecurityManager#checkPermission
    100      *
    101      */
    102     public void checkGuard(Object object) throws SecurityException {
    103         SecurityManager sm = System.getSecurityManager();
    104         if (sm != null) sm.checkPermission(this);
    105     }
    106
    107     /**
    108      * Checks if the specified permission's actions are "implied by"
    109      * this object's actions.
    110      * <P>
    111      * This must be implemented by subclasses of Permission, as they are the
    112      * only ones that can impose semantics on a Permission object.
    113      *
    114      * <p>The {@code implies} method is used by the AccessController to determine
    115      * whether or not a requested permission is implied by another permission that
    116      * is known to be valid in the current execution context.
    117      *
    118      * @param permission the permission to check against.
    119      *
    120      * @return true if the specified permission is implied by this object,
    121      * false if not.
    122      */
    123
    124     public abstract boolean implies(Permission permission);
    125
    126     /**
    127      * Checks two Permission objects for equality.
    128      * <P>
    129      * Do not use the {@code equals} method for making access control
    130      * decisions; use the {@code implies} method.
    131      *
    132      * @param obj the object we are testing for equality with this object.
    133      *
    134      * @return true if both Permission objects are equivalent.
    135      */
    136
    137     public abstract boolean equals(Object obj);
    138
    139     /**
    140      * Returns the hash code value for this Permission object.
    141      * <P>
    142      * The required {@code hashCode} behavior for Permission Objects is
    143      * the following:
    144      * <ul>
    145      * <li>Whenever it is invoked on the same Permission object more than
    146      *     once during an execution of a Java application, the
    147      *     {@code hashCode} method
    148      *     must consistently return the same integer. This integer need not
    149      *     remain consistent from one execution of an application to another
    150      *     execution of the same application.
    151      * <li>If two Permission objects are equal according to the
    152      *     {@code equals}
    153      *     method, then calling the {@code hashCode} method on each of the
    154      *     two Permission objects must produce the same integer result.
    155      * </ul>
    156      *
    157      * @return a hash code value for this object.
    158      */
    159
    160     public abstract int hashCode();
    161
    162     /**
    163      * Returns the name of this Permission.
    164      * For example, in the case of a {@code java.io.FilePermission},
    165      * the name will be a pathname.
    166      *
    167      * @return the name of this Permission.
    168      *
    169      */
    170
    171     public final String getName() {
    172         return name;
    173     }
    174
    175     /**
    176      * Returns the actions as a String. This is abstract
    177      * so subclasses can defer creating a String representation until
    178      * one is needed. Subclasses should always return actions in what they
    179      * consider to be their
    180      * canonical form. For example, two FilePermission objects created via
    181      * the following:
    182      *
    183      * <pre>
    184      *   perm1 = new FilePermission(p1,"read,write");
    185      *   perm2 = new FilePermission(p2,"write,read");
    186      * </pre>
    187      *
    188      * both return
    189      * "read,write" when the {@code getActions} method is invoked.
    190      *
    191      * @return the actions of this Permission.
    192      *
    193      */
    194
    195     public abstract String getActions();
    196
    197     /**
    198      * Returns an empty PermissionCollection for a given Permission object, or null if
    199      * one is not defined. Subclasses of class Permission should
    200      * override this if they need to store their permissions in a particular
    201      * PermissionCollection object in order to provide the correct semantics
    202      * when the {@code PermissionCollection.implies} method is called.
    203      * If null is returned,
    204      * then the caller of this method is free to store permissions of this
    205      * type in any PermissionCollection they choose (one that uses a Hashtable,
    206      * one that uses a Vector, etc).
    207      *
    208      * @return a new PermissionCollection object for this type of Permission, or
    209      * null if one is not defined.
    210      */
    211
    212     public PermissionCollection newPermissionCollection() {
    213         return null;
    214     }
    215
    216     /**
    217      * Returns a string describing this Permission.  The convention is to
    218      * specify the class name, the permission name, and the actions in
    219      * the following format: '("ClassName" "name" "actions")', or
    220      * '("ClassName" "name")' if actions list is null or empty.
    221      *
    222      * @return information about this Permission.
    223      */
    224     public String toString() {
    225         String actions = getActions();
    226         if (actions == null || actions.isEmpty()) { // OPTIONAL
    227             return "(\"" + getClass().getName() + "\" \"" + name + "\")";
    228         } else {
    229             return "(\"" + getClass().getName() + "\" \"" + name +
    230                  "\" \"" + actions + "\")";
    231         }
    232     }
    233 }
    --- EOF ---