View Javadoc
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 }