001/*
002 * Copyright 2002-2016 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.beans.factory.config;
018
019import org.springframework.beans.factory.ObjectFactory;
020import org.springframework.lang.Nullable;
021
022/**
023 * Strategy interface used by a {@link ConfigurableBeanFactory},
024 * representing a target scope to hold bean instances in.
025 * This allows for extending the BeanFactory's standard scopes
026 * {@link ConfigurableBeanFactory#SCOPE_SINGLETON "singleton"} and
027 * {@link ConfigurableBeanFactory#SCOPE_PROTOTYPE "prototype"}
028 * with custom further scopes, registered for a
029 * {@link ConfigurableBeanFactory#registerScope(String, Scope) specific key}.
030 *
031 * <p>{@link org.springframework.context.ApplicationContext} implementations
032 * such as a {@link org.springframework.web.context.WebApplicationContext}
033 * may register additional standard scopes specific to their environment,
034 * e.g. {@link org.springframework.web.context.WebApplicationContext#SCOPE_REQUEST "request"}
035 * and {@link org.springframework.web.context.WebApplicationContext#SCOPE_SESSION "session"},
036 * based on this Scope SPI.
037 *
038 * <p>Even if its primary use is for extended scopes in a web environment,
039 * this SPI is completely generic: It provides the ability to get and put
040 * objects from any underlying storage mechanism, such as an HTTP session
041 * or a custom conversation mechanism. The name passed into this class's
042 * {@code get} and {@code remove} methods will identify the
043 * target object in the current scope.
044 *
045 * <p>{@code Scope} implementations are expected to be thread-safe.
046 * One {@code Scope} instance can be used with multiple bean factories
047 * at the same time, if desired (unless it explicitly wants to be aware of
048 * the containing BeanFactory), with any number of threads accessing
049 * the {@code Scope} concurrently from any number of factories.
050 *
051 * @author Juergen Hoeller
052 * @author Rob Harrop
053 * @since 2.0
054 * @see ConfigurableBeanFactory#registerScope
055 * @see CustomScopeConfigurer
056 * @see org.springframework.aop.scope.ScopedProxyFactoryBean
057 * @see org.springframework.web.context.request.RequestScope
058 * @see org.springframework.web.context.request.SessionScope
059 */
060public interface Scope {
061
062        /**
063         * Return the object with the given name from the underlying scope,
064         * {@link org.springframework.beans.factory.ObjectFactory#getObject() creating it}
065         * if not found in the underlying storage mechanism.
066         * <p>This is the central operation of a Scope, and the only operation
067         * that is absolutely required.
068         * @param name the name of the object to retrieve
069         * @param objectFactory the {@link ObjectFactory} to use to create the scoped
070         * object if it is not present in the underlying storage mechanism
071         * @return the desired object (never {@code null})
072         * @throws IllegalStateException if the underlying scope is not currently active
073         */
074        Object get(String name, ObjectFactory<?> objectFactory);
075
076        /**
077         * Remove the object with the given {@code name} from the underlying scope.
078         * <p>Returns {@code null} if no object was found; otherwise
079         * returns the removed {@code Object}.
080         * <p>Note that an implementation should also remove a registered destruction
081         * callback for the specified object, if any. It does, however, <i>not</i>
082         * need to <i>execute</i> a registered destruction callback in this case,
083         * since the object will be destroyed by the caller (if appropriate).
084         * <p><b>Note: This is an optional operation.</b> Implementations may throw
085         * {@link UnsupportedOperationException} if they do not support explicitly
086         * removing an object.
087         * @param name the name of the object to remove
088         * @return the removed object, or {@code null} if no object was present
089         * @throws IllegalStateException if the underlying scope is not currently active
090         * @see #registerDestructionCallback
091         */
092        @Nullable
093        Object remove(String name);
094
095        /**
096         * Register a callback to be executed on destruction of the specified
097         * object in the scope (or at destruction of the entire scope, if the
098         * scope does not destroy individual objects but rather only terminates
099         * in its entirety).
100         * <p><b>Note: This is an optional operation.</b> This method will only
101         * be called for scoped beans with actual destruction configuration
102         * (DisposableBean, destroy-method, DestructionAwareBeanPostProcessor).
103         * Implementations should do their best to execute a given callback
104         * at the appropriate time. If such a callback is not supported by the
105         * underlying runtime environment at all, the callback <i>must be
106         * ignored and a corresponding warning should be logged</i>.
107         * <p>Note that 'destruction' refers to automatic destruction of
108         * the object as part of the scope's own lifecycle, not to the individual
109         * scoped object having been explicitly removed by the application.
110         * If a scoped object gets removed via this facade's {@link #remove(String)}
111         * method, any registered destruction callback should be removed as well,
112         * assuming that the removed object will be reused or manually destroyed.
113         * @param name the name of the object to execute the destruction callback for
114         * @param callback the destruction callback to be executed.
115         * Note that the passed-in Runnable will never throw an exception,
116         * so it can safely be executed without an enclosing try-catch block.
117         * Furthermore, the Runnable will usually be serializable, provided
118         * that its target object is serializable as well.
119         * @throws IllegalStateException if the underlying scope is not currently active
120         * @see org.springframework.beans.factory.DisposableBean
121         * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getDestroyMethodName()
122         * @see DestructionAwareBeanPostProcessor
123         */
124        void registerDestructionCallback(String name, Runnable callback);
125
126        /**
127         * Resolve the contextual object for the given key, if any.
128         * E.g. the HttpServletRequest object for key "request".
129         * @param key the contextual key
130         * @return the corresponding object, or {@code null} if none found
131         * @throws IllegalStateException if the underlying scope is not currently active
132         */
133        @Nullable
134        Object resolveContextualObject(String key);
135
136        /**
137         * Return the <em>conversation ID</em> for the current underlying scope, if any.
138         * <p>The exact meaning of the conversation ID depends on the underlying
139         * storage mechanism. In the case of session-scoped objects, the
140         * conversation ID would typically be equal to (or derived from) the
141         * {@link javax.servlet.http.HttpSession#getId() session ID}; in the
142         * case of a custom conversation that sits within the overall session,
143         * the specific ID for the current conversation would be appropriate.
144         * <p><b>Note: This is an optional operation.</b> It is perfectly valid to
145         * return {@code null} in an implementation of this method if the
146         * underlying storage mechanism has no obvious candidate for such an ID.
147         * @return the conversation ID, or {@code null} if there is no
148         * conversation ID for the current scope
149         * @throws IllegalStateException if the underlying scope is not currently active
150         */
151        @Nullable
152        String getConversationId();
153
154}