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}