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

Save This Page
Home » openjdk-7 » java » security » [javadoc | source]