DomainCombiner


1   /*
2    * @(#)DomainCombiner.java  1.7 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.security;
9   
10  /**
11   * A <code>DomainCombiner</code> provides a means to dynamically
12   * update the ProtectionDomains associated with the current
13   * <code>AccessControlContext</code>.
14   *
15   * <p> A <code>DomainCombiner</code> is passed as a parameter to the
16   * appropriate constructor for <code>AccessControlContext</code>.
17   * The newly constructed context is then passed to the
18   * <code>AccessController.doPrivileged(..., context)</code> method
19   * to bind the provided context (and associated <code>DomainCombiner</code>)
20   * with the current execution Thread.  Subsequent calls to
21   * <code>AccessController.getContext</code> or
22   * <code>AccessController.checkPermission</code>
23   * cause the <code>DomainCombiner.combine</code> to get invoked.
24   *
25   * <p> The combine method takes two arguments.  The first argument represents
26   * an array of ProtectionDomains from the current execution Thread,
27   * since the most recent call to <code>AccessController.doPrivileged</code>.
28   * If no call to doPrivileged was made, then the first argument will contain
29   * all the ProtectionDomains from the current execution Thread.
30   * The second argument represents an array of inherited ProtectionDomains,
31   * which may be <code>null</code>.  ProtectionDomains may be inherited
32   * from a parent Thread, or from a privileged context.  If no call to
33   * doPrivileged was made, then the second argument will contain the
34   * ProtectionDomains inherited from the parent Thread.  If one or more calls
35   * to doPrivileged were made, and the most recent call was to
36   * doPrivileged(action, context), then the second argument will contain the
37   * ProtectionDomains from the privileged context.  If the most recent call
38   * was to doPrivileged(action), then there is no privileged context,
39   * and the second argument will be <code>null</code>.
40   *
41   * <p> The <code>combine</code> method investigates the two input arrays
42   * of ProtectionDomains and returns a single array containing the updated
43   * ProtectionDomains.  In the simplest case, the <code>combine</code>
44   * method merges the two stacks into one.  In more complex cases,
45   * the <code>combine</code> method returns a modified
46   * stack of ProtectionDomains.  The modification may have added new
47   * ProtectionDomains, removed certain ProtectionDomains, or simply
48   * updated existing ProtectionDomains.  Re-ordering and other optimizations
49   * to the ProtectionDomains are also permitted.  Typically the
50   * <code>combine</code> method bases its updates on the information
51   * encapsulated in the <code>DomainCombiner</code>.
52   *
53   * <p> After the <code>AccessController.getContext</code> method
54   * receives the combined stack of ProtectionDomains back from
55   * the <code>DomainCombiner</code>, it returns a new
56   * AccessControlContext that has both the combined ProtectionDomains
57   * as well as the <code>DomainCombiner</code>.
58   * 
59   * @see AccessController
60   * @see AccessControlContext
61   * @version 1.7, 12/19/03
62   */
63  public interface DomainCombiner {
64  
65      /**
66       * Modify or update the provided ProtectionDomains.
67       * ProtectionDomains may be added to or removed from the given
68       * ProtectionDomains.  The ProtectionDomains may be re-ordered.
69       * Individual ProtectionDomains may be may be modified (with a new
70       * set of Permissions, for example).
71       *
72       * <p>
73       *
74       * @param currentDomains the ProtectionDomains associated with the
75       *      current execution Thread, up to the most recent
76       *      privileged <code>ProtectionDomain</code>.
77       *      The ProtectionDomains are are listed in order of execution,
78       *      with the most recently executing <code>ProtectionDomain</code>
79       *      residing at the beginning of the array. This parameter may
80       *      be <code>null</code> if the current execution Thread
81       *      has no associated ProtectionDomains.<p>
82       *
83       * @param assignedDomains an array of inherited ProtectionDomains.
84       *      ProtectionDomains may be inherited from a parent Thread,
85       *      or from a privileged <code>AccessControlContext</code>.
86       *      This parameter may be <code>null</code>
87       *      if there are no inherited ProtectionDomains.
88       *
89       * @return a new array consisting of the updated ProtectionDomains,
90       *      or <code>null</code>.
91       */
92      ProtectionDomain  [] combine(ProtectionDomain  [] currentDomains,
93                  ProtectionDomain  [] assignedDomains);
94  }
95
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags