--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/security/DomainCombiner.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,112 @@
+/*
+ * Copyright 1999-2006 Sun Microsystems, Inc. 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. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.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);
+}