/*

 * Copyright (c) 1999, 2013, 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} provides a means to dynamically

 * update the ProtectionDomains associated with the current

 * {@code AccessControlContext}.

 *

 * <p> A {@code DomainCombiner} is passed as a parameter to the

 * appropriate constructor for {@code AccessControlContext}.

 * The newly constructed context is then passed to the

 * {@code AccessController.doPrivileged(..., context)} method

 * to bind the provided context (and associated {@code DomainCombiner})

 * with the current execution Thread.  Subsequent calls to

 * {@code AccessController.getContext} or

 * {@code AccessController.checkPermission}

 * cause the {@code DomainCombiner.combine} 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}.

 * 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}.  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}.

 *

 * <p> The {@code combine} method investigates the two input arrays

 * of ProtectionDomains and returns a single array containing the updated

 * ProtectionDomains.  In the simplest case, the {@code combine}

 * method merges the two stacks into one.  In more complex cases,

 * the {@code combine} 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} method bases its updates on the information

 * encapsulated in the {@code DomainCombiner}.

 *

 * <p> After the {@code AccessController.getContext} method

 * receives the combined stack of ProtectionDomains back from

 * the {@code DomainCombiner}, it returns a new

 * AccessControlContext that has both the combined ProtectionDomains

 * as well as the {@code DomainCombiner}.

 *

 * @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}.

     *          The ProtectionDomains are are listed in order of execution,

     *          with the most recently executing {@code ProtectionDomain}

     *          residing at the beginning of the array. This parameter may

     *          be {@code null} 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}.

     *          This parameter may be {@code null}

     *          if there are no inherited ProtectionDomains.

     *

     * @return a new array consisting of the updated ProtectionDomains,

     *          or {@code null}.

     */

    ProtectionDomain[] combine(ProtectionDomain[] currentDomains,

                                ProtectionDomain[] assignedDomains);

}