1. /*

  2.  * @(#)DomainCombiner.java	1.3 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.security;

  12. 

  13. /**

  14.  * A <code>DomainCombiner</code> provides a means to dynamically

  15.  * update the ProtectionDomains associated with the current

  16.  * <code>AccessControlContext</code>.

  17.  *

  18.  * <p> A <code>DomainCombiner</code> is passed as a parameter to the

  19.  * appropriate constructor for <code>AccessControlContext</code>.

  20.  * The newly constructed context is then passed to the

  21.  * <code>AccessController.doPrivileged(..., context)</code> method

  22.  * to bind the provided context (and associated <code>DomainCombiner</code>)

  23.  * with the current execution Thread.  Subsequent calls to

  24.  * <code>AccessController.getContext</code> or

  25.  * <code>AccessController.checkPermission</code>

  26.  * cause the <code>DomainCombiner.combine</code> to get invoked.

  27.  *

  28.  * <p> The <code>combine</code> method takes two arguments.

  29.  * The ProtectionDomains on the current execution Thread, since the

  30.  * most recent call to <code>AccessController.doPrivileged</code>,

  31.  * get passed to the first argument in an array.

  32.  * If no call to <code>doPrivileged</code> was made, then all the

  33.  * ProtectionDomains from the current execution Thread get passed

  34.  * to the first argument.  The ProtectionDomains inherited

  35.  * from the parent Thread get passed to the second argument,

  36.  * unless a call to doPrivileged(..., <i>context</i>)

  37.  * had occurred.  In that case, the ProtectionDomains from the

  38.  * privileged <i>context</i> are passed to the second argument.

  39.  *

  40.  * <p> The <code>combine</code> method investigates the two input arrays

  41.  * of ProtectionDomains and returns a single array containing the updated

  42.  * ProtectionDomains.  In the simplest case, the <code>combine</code>

  43.  * method merges the two stacks into one.  In more complex cases,

  44.  * the <code>combine</code> method returns a modified

  45.  * stack of ProtectionDomains.  The modification may have added new

  46.  * ProtectionDomains, removed certain ProtectionDomains, or simply

  47.  * updated existing ProtectionDomains.  Re-ordering and other optimizations

  48.  * to the ProtectionDomains are also permitted.  Typically the

  49.  * <code>combine</code> method bases its updates on the information

  50.  * encapsulated in the <code>DomainCombiner</code>.

  51.  *

  52.  * <p> After the <code>AccessController.getContext</code> method

  53.  * receives the combined stack of ProtectionDomains back from

  54.  * the <code>DomainCombiner</code>, it returns a new

  55.  * AccessControlContext that has both the combined ProtectionDomains

  56.  * as well as the <code>DomainCombiner</code>.

  57.  * 

  58.  * @see AccessController

  59.  * @see AccessControlContext

  60.  * @version 1.3, 02/02/00

  61.  */

  62. public interface DomainCombiner {

  63. 

  64.     /**

  65.      * Modify or update the provided ProtectionDomains.

  66.      * ProtectionDomains may be added to or removed from the given

  67.      * ProtectionDomains.  The ProtectionDomains may be re-ordered.

  68.      * Individual ProtectionDomains may be may be modified (with a new

  69.      * set of Permissions, for example).

  70.      *

  71.      * <p>

  72.      *

  73.      * @param currentDomains the ProtectionDomains associated with the

  74.      *		current execution Thread, up to the most recent

  75.      *		privileged <code>ProtectionDomain</code>.

  76.      *		The ProtectionDomains are are listed in order of execution,

  77.      *		with the most recently executing <code>ProtectionDomain</code>

  78.      *		residing at the beginning of the array. This parameter may

  79.      *		be <code>null</code> if the current execution Thread

  80.      *		has no associated ProtectionDomains.<p>

  81.      *

  82.      * @param assignedDomains the ProtectionDomains inherited from the

  83.      *		parent Thread, or the ProtectionDomains from the

  84.      *		privileged <i>context</i>, if a call to

  85.      *		AccessController.doPrivileged(..., <i>context</i>)

  86.      *		had occurred  This parameter may be <code>null</code>

  87.      *		if there were no ProtectionDomains inherited from the

  88.      *		parent Thread, or from the privileged <i>context</i>.

  89.      *

  90.      * @return a new array consisting of the updated ProtectionDomains,

  91.      *		or <code>null</code>.

  92.      */

  93.     ProtectionDomain[] combine(ProtectionDomain[] currentDomains,

  94. 				ProtectionDomain[] assignedDomains);

  95. }