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