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