8187443: Forest Consolidation: Move files to unified layout

Reviewed-by: darcy, ihse

src/java.base/share/classes/java/security/DomainCombiner.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 1999, 2015, 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).
+     *
+     * @param currentDomains the ProtectionDomains associated with the
+     *          current execution Thread, up to the most recent
+     *          privileged {@code ProtectionDomain}.
+     *          The ProtectionDomains 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.
+     *
+     * @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);
+}