SubjectRunnable.java

/*
 * 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, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.shiro.subject.support;

import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.ThreadState;

/**
 * A {@code SubjectRunnable} ensures that a target/delegate {@link Runnable Runnable} will execute such that any
 * call to {@code SecurityUtils.}{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()} during the
 * {@code Runnable}'s execution will return the associated {@code Subject} instance.  The {@code SubjectRunnable}
 * instance can be run on any thread (the current thread or asynchronously on another thread) and the
 * {@code SecurityUtils.getSubject()} call will still work properly.  This implementation also guarantees that Shiro's
 * thread state will be identical before and after execution to ensure threads remain clean in any thread-pooled
 * environment.
 * <p/>
 * When instances of this class {@link Runnable#run() run()}, the following occurs:
 * <ol>
 * <li>The Subject and any of its associated thread state is first bound to the thread that executes the
 * {@code Runnable}.</li>
 * <li>The delegate/target {@code Runnable} is {@link #doRun(Runnable) run}</li>
 * <li>Any previous thread state that might have existed before the {@code Subject} was bound is fully restored</li>
 * </ol>
 * <p/>
 *
 * <h3>Usage</h3>
 *
 * This is typically considered a support class and is not often directly referenced.  Most people prefer to use
 * the {@code Subject.}{@link Subject#execute(Runnable) execute} or
 * {@code Subject.}{@link Subject#associateWith(Runnable) associateWith} methods, which transparently perform the
 * necessary association logic.
 * <p/>
 * An even more convenient alternative is to use a
 * {@link org.apache.shiro.concurrent.SubjectAwareExecutor SubjectAwareExecutor}, which transparently uses
 * instances of this class but does not require referencing Shiro's API at all.
 *
 * @see Subject#associateWith(Runnable)
 * @see org.apache.shiro.concurrent.SubjectAwareExecutor SubjectAwareExecutor
 * @since 1.0
 */
public class SubjectRunnable implements Runnable {

    protected final ThreadState threadState;
    private final Runnable runnable;

    /**
     * Creates a new {@code SubjectRunnable} that, when executed, will execute the target {@code delegate}, but
     * guarantees that it will run associated with the specified {@code Subject}.
     *
     * @param subject  the Subject to associate with the delegate's execution.
     * @param delegate the runnable to run.
     */
    public SubjectRunnable(Subject subject, Runnable delegate) {
        this(new SubjectThreadState(subject), delegate);
    }

    /**
     * Creates a new {@code SubjectRunnable} that, when executed, will perform thread state
     * {@link ThreadState#bind binding} and guaranteed {@link ThreadState#restore restoration} before and after the
     * {@link Runnable Runnable}'s execution, respectively.
     *
     * @param threadState the thread state to bind and unbind before and after the runnable's execution.
     * @param delegate    the delegate {@code Runnable} to execute when this instance is {@link #run() run()}.
     * @throws IllegalArgumentException if either the {@code ThreadState} or {@link Runnable} arguments are {@code null}.
     */
    protected SubjectRunnable(ThreadState threadState, Runnable delegate) throws IllegalArgumentException {
        if (threadState == null) {
            throw new IllegalArgumentException("ThreadState argument cannot be null.");
        }
        this.threadState = threadState;
        if (delegate == null) {
            throw new IllegalArgumentException("Runnable argument cannot be null.");
        }
        this.runnable = delegate;
    }

    /**
     * {@link ThreadState#bind Bind}s the Subject thread state, executes the target {@code Runnable} and then guarantees
     * the previous thread state's {@link ThreadState#restore restoration}:
     * <pre>
     * try {
     *     threadState.{@link ThreadState#bind bind()};
     *     {@link #doRun doRun}(targetRunnable);
     * } finally {
     *     threadState.{@link ThreadState#restore restore()}
     * }
     * </pre>
     */
    public void run() {
        try {
            threadState.bind();
            doRun(this.runnable);
        } finally {
            threadState.restore();
        }
    }

    /**
     * Simply calls the target {@link Runnable Runnable}'s {@link Runnable#run run()} method.
     *
     * @param runnable the target runnable to run.
     */
    protected void doRun(Runnable runnable) {
        runnable.run();
    }
}