river-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Firmstone <j...@zeus.net.au>
Subject Re: Learnings from a RevokeableDynamicPolicy & A Future Roadmap
Date Thu, 12 Aug 2010 09:49:34 GMT

Some minor changes to the ECM:

 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *      http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * See the License for the specific language governing permissions and
 * limitations under the License.
package org.apache.river.api.security;

import java.security.AccessControlException;
import java.security.Permission;
import java.util.Set;

 * <p>
 * An ExecutionContextManager is designed to be repeatedly called, where 
 * AccessController.checkPermission(Permission) is too great an overhead.
 * </p><p>
 * The ExecutionContextManager will only call
 * AccessControlContext.checkPermission(Permission) once, for each 
context.  This
 * ensures that checkPermission isn't called again until the context 
changes, or
 * the Permission checked by this ExecutionContextManager experiences a
 * revoke for any ProtectionDomain by the RevokeableDynamicPolicy.
 * </p><p>
 * A Runnable may be submitted to the ExecutionContextManager to be executed
 * when a Permission Revocation matching the stored Permission occurs.
 * </p><p>
 * Use of this class is not limited to Revokeable Permission's.
 * </p>
 * @author Peter Firmstone
 * @see RevokeableDynamicPolicy
 * @see Permission
 * @see AccessControlContext
public interface ExecutionContextManager {

     * <p>
     * This is a call made by a Security Delegate, or other Object used to
     * control access to privileged methods or constructors, similar to the
     * AccessControll.checkPermssion(Permission) call, but with the 
     * pre defined and unchanging.  The Permission check is optimised,
     * typically a method may only be concerned with a single Permission 
     * but in many existing cases, the AccessController check is too 
     * to be called on every method invocation.  The 
     * should optimise this call by ensuring that 
checkPermission(Permission) is only
     * called once per AccessControlContext.  In other words if the caller's
     * AccessControlContext hasn't changed, then checkPermission(Permission)
     * isn't called again as it would be assumed to succeed, unless the
     * RevokeableDynamicPolicy revokes a Permission with the same class,
     * in which case the Permission must be checked again.
     * </p><p>
     * Typically where it is not feasable to call 
     * on every invocation, those objects are usually guarded or have the
     * checkPermission method called in the constructor.
     * </p><p>
     * ExecutionContextManager provides a more thorough form of protection.
     * </p><p>
     * ExecutionContextManager should be used sparingly, the more generic
     * or widely applicable the Permission, the more efficient the
     * ExecutionContextManager is in memory usage terms.
     * </p><p>
     * This method also add's the current context to the current execution
     * cache, it is not removed from that cache until after 
     * has been called.
     * </p>
     * @param reaper - Runnable provided to clean up if Revocation 
occurs during
     * the execution that follows this call, until the try block exits,
     * the current thread is not interrupted, rather the reaper is expected
     * to know what resources need to be closed.
     * @throws java.security.AccessControlException
    public void accessControlCommence(Runnable reaper) throws 
     * <p>
     * This method is to advise the ExecutionContextManager that the
     * current method or protected region has returned, it must
     * always follow the accessControlCommence() call, in response,
     * the ECM removes the current context from the execution context cache
     * and releases the reference to the Runnable reaper.
     * </p><p>
     * If the execution context is still in the cache at the time of
     * revocation, the reaper will be run only if affected directly by the
     * revocation, the thread may be asked to wait for a short period, to
     * allow the determination to be made.
     * Revocation applicability is determined by
     * AccessControlContext.checkPermission(Permission p) where p is the
     * Permission affected.
     * </p><p>
     * This should be executed in the finally{} block of a try catch 
     * which always executes in the event of an exception or normal return.
     * </p>
     * <code>
     * try{
     *        ecm.accessControlCommence(reaper);
     *        // do something
     *        return;
     * } catch (AccessControlException e) {
     *        throw new SecurityException("Method blah caused an...", e);
     * } finally {
     *        ecm.accessControlExit();
     * }
     * </code>
     * <p>
     * This should not be confused with AccessController.doPrivileged blocks
     * </p>
    public void accessControlExit();

     * Get the Permission monitored by this ExecutionContextManager.
     * @return Permission monitored by the ExecutionContextManager
    public Permission getPermission();

View raw message