      1 /*
      2  * Copyright (c) 1999, 2015, 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} provides a means to dynamically
     30  * update the ProtectionDomains associated with the current
     31  * {@code AccessControlContext}.
     32  *
     33  * <p> A {@code DomainCombiner} is passed as a parameter to the
     34  * appropriate constructor for {@code AccessControlContext}.
     35  * The newly constructed context is then passed to the
     36  * {@code AccessController.doPrivileged(..., context)} method
     37  * to bind the provided context (and associated {@code DomainCombiner})
     38  * with the current execution Thread.  Subsequent calls to
     39  * {@code AccessController.getContext} or
     40  * {@code AccessController.checkPermission}
     41  * cause the {@code DomainCombiner.combine} 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}.
     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}.  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}.
     58  *
     59  * <p> The {@code combine} 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}
     62  * method merges the two stacks into one.  In more complex cases,
     63  * the {@code combine} 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} method bases its updates on the information
     69  * encapsulated in the {@code DomainCombiner}.
     70  *
     71  * <p> After the {@code AccessController.getContext} method
     72  * receives the combined stack of ProtectionDomains back from
     73  * the {@code DomainCombiner}, it returns a new
     74  * AccessControlContext that has both the combined ProtectionDomains
     75  * as well as the {@code DomainCombiner}.
     76  *
     77  * @see AccessController
     78  * @see AccessControlContext
     79  * @since 1.3
     80  * @deprecated This class is only useful in conjunction with
     81  *       {@linkplain SecurityManager the Security Manager}, which is deprecated
     82  *       and subject to removal in a future release. Consequently, this class
     83  *       is also deprecated and subject to removal. There is no replacement for
     84  *       the Security Manager or this class.
     85  */
     86 @Deprecated(since="17", forRemoval=true)
     87 public interface DomainCombiner {
     88
     89     /**
     90      * Modify or update the provided ProtectionDomains.
     91      * ProtectionDomains may be added to or removed from the given
     92      * ProtectionDomains.  The ProtectionDomains may be re-ordered.
     93      * Individual ProtectionDomains may be modified (with a new
     94      * set of Permissions, for example).
     95      *
     96      * @param currentDomains the ProtectionDomains associated with the
     97      *          current execution Thread, up to the most recent
     98      *          privileged {@code ProtectionDomain}.
     99      *          The ProtectionDomains are listed in order of execution,
    100      *          with the most recently executing {@code ProtectionDomain}
    101      *          residing at the beginning of the array. This parameter may
    102      *          be {@code null} if the current execution Thread
    103      *          has no associated ProtectionDomains.
    104      *
    105      * @param assignedDomains an array of inherited ProtectionDomains.
    106      *          ProtectionDomains may be inherited from a parent Thread,
    107      *          or from a privileged {@code AccessControlContext}.
    108      *          This parameter may be {@code null}
    109      *          if there are no inherited ProtectionDomains.
    110      *
    111      * @return a new array consisting of the updated ProtectionDomains,
    112      *          or {@code null}.
    113      */
    114     ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
    115                                 ProtectionDomain[] assignedDomains);
    116 }
    --- EOF ---