Save This Page
Home » openjdk-7 » java » security » [javadoc | source]
    1   /*
    2    * Copyright (c) 1999, 2006, 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    * A <code>DomainCombiner</code> provides a means to dynamically
   30    * update the ProtectionDomains associated with the current
   31    * <code>AccessControlContext</code>.
   32    *
   33    * <p> A <code>DomainCombiner</code> is passed as a parameter to the
   34    * appropriate constructor for <code>AccessControlContext</code>.
   35    * The newly constructed context is then passed to the
   36    * <code>AccessController.doPrivileged(..., context)</code> method
   37    * to bind the provided context (and associated <code>DomainCombiner</code>)
   38    * with the current execution Thread.  Subsequent calls to
   39    * <code>AccessController.getContext</code> or
   40    * <code>AccessController.checkPermission</code>
   41    * cause the <code>DomainCombiner.combine</code> to get invoked.
   42    *
   43    * <p> The combine method takes two arguments.  The first argument represents
   44    * an array of ProtectionDomains from the current execution Thread,
   45    * since the most recent call to <code>AccessController.doPrivileged</code>.
   46    * If no call to doPrivileged was made, then the first argument will contain
   47    * all the ProtectionDomains from the current execution Thread.
   48    * The second argument represents an array of inherited ProtectionDomains,
   49    * which may be <code>null</code>.  ProtectionDomains may be inherited
   50    * from a parent Thread, or from a privileged context.  If no call to
   51    * doPrivileged was made, then the second argument will contain the
   52    * ProtectionDomains inherited from the parent Thread.  If one or more calls
   53    * to doPrivileged were made, and the most recent call was to
   54    * doPrivileged(action, context), then the second argument will contain the
   55    * ProtectionDomains from the privileged context.  If the most recent call
   56    * was to doPrivileged(action), then there is no privileged context,
   57    * and the second argument will be <code>null</code>.
   58    *
   59    * <p> The <code>combine</code> method investigates the two input arrays
   60    * of ProtectionDomains and returns a single array containing the updated
   61    * ProtectionDomains.  In the simplest case, the <code>combine</code>
   62    * method merges the two stacks into one.  In more complex cases,
   63    * the <code>combine</code> method returns a modified
   64    * stack of ProtectionDomains.  The modification may have added new
   65    * ProtectionDomains, removed certain ProtectionDomains, or simply
   66    * updated existing ProtectionDomains.  Re-ordering and other optimizations
   67    * to the ProtectionDomains are also permitted.  Typically the
   68    * <code>combine</code> method bases its updates on the information
   69    * encapsulated in the <code>DomainCombiner</code>.
   70    *
   71    * <p> After the <code>AccessController.getContext</code> method
   72    * receives the combined stack of ProtectionDomains back from
   73    * the <code>DomainCombiner</code>, it returns a new
   74    * AccessControlContext that has both the combined ProtectionDomains
   75    * as well as the <code>DomainCombiner</code>.
   76    *
   77    * @see AccessController
   78    * @see AccessControlContext
   79    * @since 1.3
   80    */
   81   public interface DomainCombiner {
   82   
   83       /**
   84        * Modify or update the provided ProtectionDomains.
   85        * ProtectionDomains may be added to or removed from the given
   86        * ProtectionDomains.  The ProtectionDomains may be re-ordered.
   87        * Individual ProtectionDomains may be modified (with a new
   88        * set of Permissions, for example).
   89        *
   90        * <p>
   91        *
   92        * @param currentDomains the ProtectionDomains associated with the
   93        *          current execution Thread, up to the most recent
   94        *          privileged <code>ProtectionDomain</code>.
   95        *          The ProtectionDomains are are listed in order of execution,
   96        *          with the most recently executing <code>ProtectionDomain</code>
   97        *          residing at the beginning of the array. This parameter may
   98        *          be <code>null</code> if the current execution Thread
   99        *          has no associated ProtectionDomains.<p>
  100        *
  101        * @param assignedDomains an array of inherited ProtectionDomains.
  102        *          ProtectionDomains may be inherited from a parent Thread,
  103        *          or from a privileged <code>AccessControlContext</code>.
  104        *          This parameter may be <code>null</code>
  105        *          if there are no inherited ProtectionDomains.
  106        *
  107        * @return a new array consisting of the updated ProtectionDomains,
  108        *          or <code>null</code>.
  109        */
  110       ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
  111                                   ProtectionDomain[] assignedDomains);
  112   }

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