1 /* 2 * Copyright (c) 1999, 2021, 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 * @deprecated This class is only useful in conjunction with 81 * {@linkplain SecurityManager the Security Manager}, which is deprecated 82 * and subject to removal in a future release. Consequently, this class 83 * is also deprecated and subject to removal. There is no replacement for 84 * the Security Manager or this class. 85 */ 86 @Deprecated(since="17", forRemoval=true) 87 public interface DomainCombiner { 88 89 /** 90 * Modify or update the provided ProtectionDomains. 91 * ProtectionDomains may be added to or removed from the given 92 * ProtectionDomains. The ProtectionDomains may be re-ordered. 93 * Individual ProtectionDomains may be modified (with a new 94 * set of Permissions, for example). 95 * 96 * @param currentDomains the ProtectionDomains associated with the 97 * current execution Thread, up to the most recent 98 * privileged {@code ProtectionDomain}. 99 * The ProtectionDomains are listed in order of execution, 100 * with the most recently executing {@code ProtectionDomain} 101 * residing at the beginning of the array. This parameter may 102 * be {@code null} if the current execution Thread 103 * has no associated ProtectionDomains. 104 * 105 * @param assignedDomains an array of inherited ProtectionDomains. 106 * ProtectionDomains may be inherited from a parent Thread, 107 * or from a privileged {@code AccessControlContext}. 108 * This parameter may be {@code null} 109 * if there are no inherited ProtectionDomains. 110 * 111 * @return a new array consisting of the updated ProtectionDomains, 112 * or {@code null}. 113 */ combine(ProtectionDomain[] currentDomains, ProtectionDomain[] assignedDomains)114 ProtectionDomain[] combine(ProtectionDomain[] currentDomains, 115 ProtectionDomain[] assignedDomains); 116 } 117