/* * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.security; /** * A <code>DomainCombiner</code> provides a means to dynamically * update the ProtectionDomains associated with the current * <code>AccessControlContext</code>. * * <p> A <code>DomainCombiner</code> is passed as a parameter to the * appropriate constructor for <code>AccessControlContext</code>. * The newly constructed context is then passed to the * <code>AccessController.doPrivileged(..., context)</code> method * to bind the provided context (and associated <code>DomainCombiner</code>) * with the current execution Thread.  Subsequent calls to * <code>AccessController.getContext</code> or * <code>AccessController.checkPermission</code> * cause the <code>DomainCombiner.combine</code> to get invoked. * * <p> The combine method takes two arguments.  The first argument represents * an array of ProtectionDomains from the current execution Thread, * since the most recent call to <code>AccessController.doPrivileged</code>. * If no call to doPrivileged was made, then the first argument will contain * all the ProtectionDomains from the current execution Thread. * The second argument represents an array of inherited ProtectionDomains, * which may be <code>null</code>.  ProtectionDomains may be inherited * from a parent Thread, or from a privileged context.  If no call to * doPrivileged was made, then the second argument will contain the * ProtectionDomains inherited from the parent Thread.  If one or more calls * to doPrivileged were made, and the most recent call was to * doPrivileged(action, context), then the second argument will contain the * ProtectionDomains from the privileged context.  If the most recent call * was to doPrivileged(action), then there is no privileged context, * and the second argument will be <code>null</code>. * * <p> The <code>combine</code> method investigates the two input arrays * of ProtectionDomains and returns a single array containing the updated * ProtectionDomains.  In the simplest case, the <code>combine</code> * method merges the two stacks into one.  In more complex cases, * the <code>combine</code> method returns a modified * stack of ProtectionDomains.  The modification may have added new * ProtectionDomains, removed certain ProtectionDomains, or simply * updated existing ProtectionDomains.  Re-ordering and other optimizations * to the ProtectionDomains are also permitted.  Typically the * <code>combine</code> method bases its updates on the information * encapsulated in the <code>DomainCombiner</code>. * * <p> After the <code>AccessController.getContext</code> method * receives the combined stack of ProtectionDomains back from * the <code>DomainCombiner</code>, it returns a new * AccessControlContext that has both the combined ProtectionDomains * as well as the <code>DomainCombiner</code>. * * @see AccessController * @see AccessControlContext * @since 1.3 */public interface DomainCombiner {     /**     * Modify or update the provided ProtectionDomains.     * ProtectionDomains may be added to or removed from the given     * ProtectionDomains.  The ProtectionDomains may be re-ordered.     * Individual ProtectionDomains may be modified (with a new     * set of Permissions, for example).     *     * <p>     *     * @param currentDomains the ProtectionDomains associated with the     *          current execution Thread, up to the most recent     *          privileged <code>ProtectionDomain</code>.     *          The ProtectionDomains are are listed in order of execution,     *          with the most recently executing <code>ProtectionDomain</code>     *          residing at the beginning of the array. This parameter may     *          be <code>null</code> if the current execution Thread     *          has no associated ProtectionDomains.<p>     *     * @param assignedDomains an array of inherited ProtectionDomains.     *          ProtectionDomains may be inherited from a parent Thread,     *          or from a privileged <code>AccessControlContext</code>.     *          This parameter may be <code>null</code>     *          if there are no inherited ProtectionDomains.     *     * @return a new array consisting of the updated ProtectionDomains,     *          or <code>null</code>.     */    ProtectionDomain[] combine(ProtectionDomain[] currentDomains,                                ProtectionDomain[] assignedDomains);}