WebSubject.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.web.subject;

import org.apache.shiro.SecurityUtils;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.subject.SubjectContext;
import org.apache.shiro.web.subject.support.DefaultWebSubjectContext;
import org.apache.shiro.web.util.RequestPairSource;

import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;

/**
 * A {@code WebSubject} represents a Subject instance that was acquired as a result of an incoming
 * {@link ServletRequest}.
 *
 * @since 1.0
 */
public interface WebSubject extends Subject, RequestPairSource {

    /**
     * Returns the {@code ServletRequest} accessible when the Subject instance was created.
     *
     * @return the {@code ServletRequest} accessible when the Subject instance was created.
     */
    ServletRequest getServletRequest();

    /**
     * Returns the {@code ServletResponse} accessible when the Subject instance was created.
     *
     * @return the {@code ServletResponse} accessible when the Subject instance was created.
     */
    ServletResponse getServletResponse();

    /**
     * A {@code WebSubject.Builder} performs the same function as a {@link Subject.Builder Subject.Builder}, but
     * additionally ensures that the Servlet request/response pair that is triggering the Subject instance's creation
     * is retained for use by internal Shiro components as necessary.
     */
    public static class Builder extends Subject.Builder {

        /**
         * Constructs a new {@code Web.Builder} instance using the {@link SecurityManager SecurityManager} obtained by
         * calling {@code SecurityUtils.}{@link SecurityUtils#getSecurityManager() getSecurityManager()}.  If you want
         * to specify your own SecurityManager instance, use the
         * {@link #Builder(SecurityManager, ServletRequest, ServletResponse)} constructor instead.
         *
         * @param request  the incoming ServletRequest that will be associated with the built {@code WebSubject} instance.
         * @param response the outgoing ServletRequest paired with the ServletRequest that will be associated with the
         *                 built {@code WebSubject} instance.
         */
        public Builder(ServletRequest request, ServletResponse response) {
            this(SecurityUtils.getSecurityManager(), request, response);
        }

        /**
         * Constructs a new {@code Web.Builder} instance using the specified {@code SecurityManager} instance to
         * create the {@link WebSubject WebSubject} instance.
         *
         * @param securityManager the {@code SecurityManager SecurityManager} instance to use to build the
         *                        {@code WebSubject} instance.
         * @param request         the incoming ServletRequest that will be associated with the built {@code WebSubject}
         *                        instance.
         * @param response        the outgoing ServletRequest paired with the ServletRequest that will be associated
         *                        with the built {@code WebSubject} instance.
         */
        public Builder(SecurityManager securityManager, ServletRequest request, ServletResponse response) {
            super(securityManager);
            if (request == null) {
                throw new IllegalArgumentException("ServletRequest argument cannot be null.");
            }
            if (response == null) {
                throw new IllegalArgumentException("ServletResponse argument cannot be null.");
            }
            setRequest(request);
            setResponse(response);
        }

        /**
         * Overrides the parent implementation to return a new instance of a
         * {@link DefaultWebSubjectContext DefaultWebSubjectContext} to account for the additional request/response
         * pair.
         *
         * @return a new instance of a {@link DefaultWebSubjectContext DefaultWebSubjectContext} to account for the
         *         additional request/response pair.
         */
        @Override
        protected SubjectContext newSubjectContextInstance() {
            return new DefaultWebSubjectContext();
        }

        /**
         * Called by the {@code WebSubject.Builder} constructor, this method places the request object in the
         * context map for later retrieval.
         *
         * @param request the incoming ServletRequest that triggered the creation of the {@code WebSubject} instance.
         * @return 'this' for method chaining.
         */
        protected Builder setRequest(ServletRequest request) {
            if (request != null) {
                ((WebSubjectContext) getSubjectContext()).setServletRequest(request);
            }
            return this;
        }

        /**
         * Called by the {@code WebSubject.Builder} constructor, this method places the response object in the
         * context map for later retrieval.
         *
         * @param response the outgoing ServletRequest paired with the ServletRequest that triggered the creation of
         *                 the {@code WebSubject} instance.
         * @return 'this' for method chaining.
         */
        protected Builder setResponse(ServletResponse response) {
            if (response != null) {
                ((WebSubjectContext) getSubjectContext()).setServletResponse(response);
            }
            return this;
        }

        /**
         * Returns {@link #buildSubject() super.buildSubject()}, but additionally ensures that the returned instance
         * is an {@code instanceof} {@link WebSubject WebSubject} and to support a type-safe method so a caller
         * does not have to cast.   Per the parent class's method JavaDoc, this method will return a new instance
         * each time it is called.
         *
         * @return a new {@link WebSubject WebSubject} instance built by this {@code Builder}.
         */
        public WebSubject buildWebSubject() {
            Subject subject = super.buildSubject();
            if (!(subject instanceof WebSubject)) {
                String msg = "Subject implementation returned from the SecurityManager was not a " +
                        WebSubject.class.getName() + " implementation.  Please ensure a Web-enabled SecurityManager " +
                        "has been configured and made available to this builder.";
                throw new IllegalStateException(msg);
            }
            return (WebSubject) subject;
        }
    }

}