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