/*
* 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);
}