Scope


1   /*
2    * Copyright 2002-2007 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.beans.factory.config;
18  
19  import org.springframework.beans.factory.ObjectFactory;
20  
21  /**
22   * Strategy interface used by a {@link ConfigurableBeanFactory},
23   * representing a target scope to hold bean instances in.
24   * This allows for extending the BeanFactory's standard scopes
25   * {@link ConfigurableBeanFactory#SCOPE_SINGLETON "singleton"} and
26   * {@link ConfigurableBeanFactory#SCOPE_PROTOTYPE "prototype"}
27   * with custom further scopes, registered for a
28   * {@link ConfigurableBeanFactory#registerScope(String, Scope) specific key}.
29   *
30   * <p>{@link org.springframework.context.ApplicationContext} implementations
31   * such as a {@link org.springframework.web.context.WebApplicationContext}
32   * may register additional standard scopes specific to their environment,
33   * e.g. {@link org.springframework.web.context.WebApplicationContext#SCOPE_REQUEST "request"}
34   * and {@link org.springframework.web.context.WebApplicationContext#SCOPE_SESSION "session"},
35   * based on this Scope SPI.
36   *
37   * <p>Even if its primary use is for extended scopes in a web environment,
38   * this SPI is completely generic: It provides the ability to get and put
39   * objects from any underlying storage mechanism, such as an HTTP session
40   * or a custom conversation mechanism. The name passed into this class's
41   * <code>get</code> and <code>remove</code> methods will identify the
42   * target object in the current scope.
43   *
44   * <p><code>Scope</code> implementations are expected to be thread-safe.
45   * One <code>Scope</code> instance can be used with multiple bean factories
46   * at the same time, if desired (unless it explicitly wants to be aware of
47   * the containing BeanFactory), with any number of threads accessing
48   * the <code>Scope</code> concurrently from any number of factories.
49   *
50   * @author Juergen Hoeller
51   * @author Rob Harrop
52   * @since 2.0
53   * @see ConfigurableBeanFactory#registerScope
54   * @see CustomScopeConfigurer
55   * @see org.springframework.aop.scope.ScopedProxyFactoryBean
56   * @see org.springframework.web.context.request.RequestScope
57   * @see org.springframework.web.context.request.SessionScope
58   */
59  public interface Scope {
60  
61      /**
62       * Return the object with the given name from the underlying scope,
63       * {@link org.springframework.beans.factory.ObjectFactory#getObject() creating it}
64       * if not found in the underlying storage mechanism.
65       * <p>This is the central operation of a Scope, and the only operation
66       * that is absolutely required.
67       * @param name the name of the object to retrieve
68       * @param objectFactory the {@link ObjectFactory} to use to create the scoped
69       * object if it is not present in the underlying storage mechanism
70       * @return the desired object (never <code>null</code>)
71       */
72      Object   get(String   name, ObjectFactory objectFactory);
73  
74      /**
75       * Remove the object with the given <code>name</code> from the underlying scope.
76       * <p>Returns <code>null</code> if no object was found; otherwise
77       * returns the removed <code>Object</code>.
78       * <p>Note that an implementation should also remove a registered destruction
79       * callback for the specified object, if any. It does, however, <i>not</i>
80       * need to <i>execute</i> a registered destruction callback in this case,
81       * since the object will be destroyed by the caller (if appropriate).
82       * <p><b>Note: This is an optional operation.</b> Implementations may throw
83       * {@link UnsupportedOperationException} if they do not support explicitly
84       * removing an object.
85       * @param name the name of the object to remove
86       * @return the removed object, or <code>null</code> if no object was present
87       * @see #registerDestructionCallback
88       */
89      Object   remove(String   name);
90  
91      /**
92       * Register a callback to be executed on destruction of the specified
93       * object in the scope (or at destruction of the entire scope, if the
94       * scope does not destroy individual objects but rather only terminates
95       * in its entirety).
96       * <p><b>Note: This is an optional operation.</b> This method will only
97       * be called for scoped beans with actual destruction configuration
98       * (DisposableBean, destroy-method, DestructionAwareBeanPostProcessor).
99       * Implementations should do their best to execute a given callback
100      * at the appropriate time. If such a callback is not supported by the
101      * underlying runtime environment at all, the callback <i>must be
102      * ignored and a corresponding warning should be logged</i>.
103      * <p>Note that 'destruction' refers to to automatic destruction of
104      * the object as part of the scope's own lifecycle, not to the individual
105      * scoped object having been explicitly removed by the application.
106      * If a scoped object gets removed via this facade's {@link #remove(String)}
107      * method, any registered destruction callback should be removed as well,
108      * assuming that the removed object will be reused or manually destroyed.
109      * @param name the name of the object to execute the destruction callback for
110      * @param callback the destruction callback to be executed.
111      * Note that the passed-in Runnable will never throw an exception,
112      * so it can safely be executed without an enclosing try-catch block.
113      * Furthermore, the Runnable will usually be serializable, provided
114      * that its target object is serializable as well.
115      * @see org.springframework.beans.factory.DisposableBean
116      * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getDestroyMethodName()
117      * @see DestructionAwareBeanPostProcessor
118      */
119     void registerDestructionCallback(String   name, Runnable   callback);
120 
121     /**
122      * Return the conversation id for the current underlying scope, if any.
123      * <p>The exact meaning of the converation id depends on the underlying
124      * storage mechanism. In the case of session-scoped objects, the
125      * conversation id would typically be equal to (or derived from) the
126      * {@link javax.servlet.http.HttpSession#getId() session id}; in the
127      * case of a custom conversation that sits within the overall session,
128      * the specific id for the current conversation would be appropriate.
129      * <p><b>Note: This is an optional operation.</b> It is perfectly valid to
130      * return <code>null</code> in an implementation of this method if the
131      * underlying storage mechanism has no obvious candidate for such an id.
132      * @return the conversation id, or <code>null</code> if there is no
133      * conversation id for the current scope
134      */
135     String   getConversationId();
136 
137 }
138
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags