001: /*
002: * @(#)DomainCombiner.java 1.10 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: /**
031: * A <code>DomainCombiner</code> provides a means to dynamically
032: * update the ProtectionDomains associated with the current
033: * <code>AccessControlContext</code>.
034: *
035: * <p> A <code>DomainCombiner</code> is passed as a parameter to the
036: * appropriate constructor for <code>AccessControlContext</code>.
037: * The newly constructed context is then passed to the
038: * <code>AccessController.doPrivileged(..., context)</code> method
039: * to bind the provided context (and associated <code>DomainCombiner</code>)
040: * with the current execution Thread. Subsequent calls to
041: * <code>AccessController.getContext</code> or
042: * <code>AccessController.checkPermission</code>
043: * cause the <code>DomainCombiner.combine</code> to get invoked.
044: *
045: * <p> The combine method takes two arguments. The first argument represents
046: * an array of ProtectionDomains from the current execution Thread,
047: * since the most recent call to <code>AccessController.doPrivileged</code>.
048: * If no call to doPrivileged was made, then the first argument will contain
049: * all the ProtectionDomains from the current execution Thread.
050: * The second argument represents an array of inherited ProtectionDomains,
051: * which may be <code>null</code>. ProtectionDomains may be inherited
052: * from a parent Thread, or from a privileged context. If no call to
053: * doPrivileged was made, then the second argument will contain the
054: * ProtectionDomains inherited from the parent Thread. If one or more calls
055: * to doPrivileged were made, and the most recent call was to
056: * doPrivileged(action, context), then the second argument will contain the
057: * ProtectionDomains from the privileged context. If the most recent call
058: * was to doPrivileged(action), then there is no privileged context,
059: * and the second argument will be <code>null</code>.
060: *
061: * <p> The <code>combine</code> method investigates the two input arrays
062: * of ProtectionDomains and returns a single array containing the updated
063: * ProtectionDomains. In the simplest case, the <code>combine</code>
064: * method merges the two stacks into one. In more complex cases,
065: * the <code>combine</code> method returns a modified
066: * stack of ProtectionDomains. The modification may have added new
067: * ProtectionDomains, removed certain ProtectionDomains, or simply
068: * updated existing ProtectionDomains. Re-ordering and other optimizations
069: * to the ProtectionDomains are also permitted. Typically the
070: * <code>combine</code> method bases its updates on the information
071: * encapsulated in the <code>DomainCombiner</code>.
072: *
073: * <p> After the <code>AccessController.getContext</code> method
074: * receives the combined stack of ProtectionDomains back from
075: * the <code>DomainCombiner</code>, it returns a new
076: * AccessControlContext that has both the combined ProtectionDomains
077: * as well as the <code>DomainCombiner</code>.
078: *
079: * @see AccessController
080: * @see AccessControlContext
081: * @version 1.3, 02/02/00
082: */
083: public interface DomainCombiner {
084:
085: /**
086: * Modify or update the provided ProtectionDomains.
087: * ProtectionDomains may be added to or removed from the given
088: * ProtectionDomains. The ProtectionDomains may be re-ordered.
089: * Individual ProtectionDomains may be may be modified (with a new
090: * set of Permissions, for example).
091: *
092: * <p>
093: *
094: * @param currentDomains the ProtectionDomains associated with the
095: * current execution Thread, up to the most recent
096: * privileged <code>ProtectionDomain</code>.
097: * The ProtectionDomains are are listed in order of execution,
098: * with the most recently executing <code>ProtectionDomain</code>
099: * residing at the beginning of the array. This parameter may
100: * be <code>null</code> if the current execution Thread
101: * has no associated ProtectionDomains.<p>
102: *
103: * @param assignedDomains an array of inherited ProtectionDomains.
104: * ProtectionDomains may be inherited from a parent Thread,
105: * or from a privileged <code>AccessControlContext</code>.
106: * This parameter may be <code>null</code>
107: * if there are no inherited ProtectionDomains.
108: *
109: * @return a new array consisting of the updated ProtectionDomains,
110: * or <code>null</code>.
111: */
112: ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
113: ProtectionDomain[] assignedDomains);
114: }
|