1 /* 2 * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.security; 27 28 /** 29 * A {@code DomainCombiner} provides a means to dynamically 30 * update the ProtectionDomains associated with the current 31 * {@code AccessControlContext}. 32 * 33 * <p> A {@code DomainCombiner} is passed as a parameter to the 34 * appropriate constructor for {@code AccessControlContext}. 35 * The newly constructed context is then passed to the 36 * {@code AccessController.doPrivileged(..., context)} method 37 * to bind the provided context (and associated {@code DomainCombiner}) 38 * with the current execution Thread. Subsequent calls to 39 * {@code AccessController.getContext} or 40 * {@code AccessController.checkPermission} 41 * cause the {@code DomainCombiner.combine} to get invoked. 42 * 43 * <p> The combine method takes two arguments. The first argument represents 44 * an array of ProtectionDomains from the current execution Thread, 45 * since the most recent call to {@code AccessController.doPrivileged}. 46 * If no call to doPrivileged was made, then the first argument will contain 47 * all the ProtectionDomains from the current execution Thread. 48 * The second argument represents an array of inherited ProtectionDomains, 49 * which may be {@code null}. ProtectionDomains may be inherited 50 * from a parent Thread, or from a privileged context. If no call to 51 * doPrivileged was made, then the second argument will contain the 52 * ProtectionDomains inherited from the parent Thread. If one or more calls 53 * to doPrivileged were made, and the most recent call was to 54 * doPrivileged(action, context), then the second argument will contain the 55 * ProtectionDomains from the privileged context. If the most recent call 56 * was to doPrivileged(action), then there is no privileged context, 57 * and the second argument will be {@code null}. 58 * 59 * <p> The {@code combine} method investigates the two input arrays 60 * of ProtectionDomains and returns a single array containing the updated 61 * ProtectionDomains. In the simplest case, the {@code combine} 62 * method merges the two stacks into one. In more complex cases, 63 * the {@code combine} method returns a modified 64 * stack of ProtectionDomains. The modification may have added new 65 * ProtectionDomains, removed certain ProtectionDomains, or simply 66 * updated existing ProtectionDomains. Re-ordering and other optimizations 67 * to the ProtectionDomains are also permitted. Typically the 68 * {@code combine} method bases its updates on the information 69 * encapsulated in the {@code DomainCombiner}. 70 * 71 * <p> After the {@code AccessController.getContext} method 72 * receives the combined stack of ProtectionDomains back from 73 * the {@code DomainCombiner}, it returns a new 74 * AccessControlContext that has both the combined ProtectionDomains 75 * as well as the {@code DomainCombiner}. 76 * 77 * @see AccessController 78 * @see AccessControlContext 79 * @since 1.3 80 */ 81 public interface DomainCombiner { 82 83 /** 84 * Modify or update the provided ProtectionDomains. 85 * ProtectionDomains may be added to or removed from the given 86 * ProtectionDomains. The ProtectionDomains may be re-ordered. 87 * Individual ProtectionDomains may be modified (with a new 88 * set of Permissions, for example). 89 * 90 * @param currentDomains the ProtectionDomains associated with the 91 * current execution Thread, up to the most recent 92 * privileged {@code ProtectionDomain}. 93 * The ProtectionDomains are listed in order of execution, 94 * with the most recently executing {@code ProtectionDomain} 95 * residing at the beginning of the array. This parameter may 96 * be {@code null} if the current execution Thread 97 * has no associated ProtectionDomains. 98 * 99 * @param assignedDomains an array of inherited ProtectionDomains. 100 * ProtectionDomains may be inherited from a parent Thread, 101 * or from a privileged {@code AccessControlContext}. 102 * This parameter may be {@code null} 103 * if there are no inherited ProtectionDomains. 104 * 105 * @return a new array consisting of the updated ProtectionDomains, 106 * or {@code null}. 107 */ combine(ProtectionDomain[] currentDomains, ProtectionDomain[] assignedDomains)108 ProtectionDomain[] combine(ProtectionDomain[] currentDomains, 109 ProtectionDomain[] assignedDomains); 110 } 111