1 /*
2 * Copyright (c) 1999, 2013, 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 * <p>
91 *
92 * @param currentDomains the ProtectionDomains associated with the
93 * current execution Thread, up to the most recent
94 * privileged {@code ProtectionDomain}.
95 * The ProtectionDomains are are listed in order of execution,
96 * with the most recently executing {@code ProtectionDomain}
97 * residing at the beginning of the array. This parameter may
98 * be {@code null} if the current execution Thread
99 * has no associated ProtectionDomains.<p>
100 *
101 * @param assignedDomains an array of inherited ProtectionDomains.
102 * ProtectionDomains may be inherited from a parent Thread,
103 * or from a privileged {@code AccessControlContext}.
104 * This parameter may be {@code null}
105 * if there are no inherited ProtectionDomains.
106 *
107 * @return a new array consisting of the updated ProtectionDomains,
108 * or {@code null}.
109 */
110 ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
111 ProtectionDomain[] assignedDomains);
112 }