1 /*
2 * Copyright 2002-2013 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.web.context.request;
18
19 /**
20 * Abstraction for accessing attribute objects associated with a request.
21 * Supports access to request-scoped attributes as well as to session-scoped
22 * attributes, with the optional notion of a "global session".
23 *
24 * <p>Can be implemented for any kind of request/session mechanism,
25 * in particular for servlet requests and portlet requests.
26 *
27 * @author Juergen Hoeller
28 * @since 2.0
29 * @see ServletRequestAttributes
30 * @see org.springframework.web.portlet.context.PortletRequestAttributes
31 */
32 public interface RequestAttributes {
33
34 /**
35 * Constant that indicates request scope.
36 */
37 int SCOPE_REQUEST = 0;
38
39 /**
40 * Constant that indicates session scope.
41 * <p>This preferably refers to a locally isolated session, if such
42 * a distinction is available (for example, in a Portlet environment).
43 * Else, it simply refers to the common session.
44 */
45 int SCOPE_SESSION = 1;
46
47 /**
48 * Constant that indicates global session scope.
49 * <p>This explicitly refers to a globally shared session, if such
50 * a distinction is available (for example, in a Portlet environment).
51 * Else, it simply refers to the common session.
52 */
53 int SCOPE_GLOBAL_SESSION = 2;
54
55
56 /**
57 * Name of the standard reference to the request object: "request".
58 * @see #resolveReference
59 */
60 String REFERENCE_REQUEST = "request";
61
62 /**
63 * Name of the standard reference to the session object: "session".
64 * @see #resolveReference
65 */
66 String REFERENCE_SESSION = "session";
67
68
69 /**
70 * Return the value for the scoped attribute of the given name, if any.
71 * @param name the name of the attribute
72 * @param scope the scope identifier
73 * @return the current attribute value, or {@code null} if not found
74 */
75 Object getAttribute(String name, int scope);
76
77 /**
78 * Set the value for the scoped attribute of the given name,
79 * replacing an existing value (if any).
80 * @param name the name of the attribute
81 * @param scope the scope identifier
82 * @param value the value for the attribute
83 */
84 void setAttribute(String name, Object value, int scope);
85
86 /**
87 * Remove the scoped attribute of the given name, if it exists.
88 * <p>Note that an implementation should also remove a registered destruction
89 * callback for the specified attribute, if any. It does, however, <i>not</i>
90 * need to <i>execute</i> a registered destruction callback in this case,
91 * since the object will be destroyed by the caller (if appropriate).
92 * @param name the name of the attribute
93 * @param scope the scope identifier
94 */
95 void removeAttribute(String name, int scope);
96
97 /**
98 * Retrieve the names of all attributes in the scope.
99 * @param scope the scope identifier
100 * @return the attribute names as String array
101 */
102 String[] getAttributeNames(int scope);
103
104 /**
105 * Register a callback to be executed on destruction of the
106 * specified attribute in the given scope.
107 * <p>Implementations should do their best to execute the callback
108 * at the appropriate time: that is, at request completion or session
109 * termination, respectively. If such a callback is not supported by the
110 * underlying runtime environment, the callback <i>must be ignored</i>
111 * and a corresponding warning should be logged.
112 * <p>Note that 'destruction' usually corresponds to destruction of the
113 * entire scope, not to the individual attribute having been explicitly
114 * removed by the application. If an attribute gets removed via this
115 * facade's {@link #removeAttribute(String, int)} method, any registered
116 * destruction callback should be disabled as well, assuming that the
117 * removed object will be reused or manually destroyed.
118 * <p><b>NOTE:</b> Callback objects should generally be serializable if
119 * they are being registered for a session scope. Otherwise the callback
120 * (or even the entire session) might not survive web app restarts.
121 * @param name the name of the attribute to register the callback for
122 * @param callback the destruction callback to be executed
123 * @param scope the scope identifier
124 */
125 void registerDestructionCallback(String name, Runnable callback, int scope);
126
127 /**
128 * Resolve the contextual reference for the given key, if any.
129 * <p>At a minimum: the HttpServletRequest/PortletRequest reference for key
130 * "request", and the HttpSession/PortletSession reference for key "session".
131 * @param key the contextual key
132 * @return the corresponding object, or {@code null} if none found
133 */
134 Object resolveReference(String key);
135
136 /**
137 * Return an id for the current underlying session.
138 * @return the session id as String (never {@code null})
139 */
140 String getSessionId();
141
142 /**
143 * Expose the best available mutex for the underlying session:
144 * that is, an object to synchronize on for the underlying session.
145 * @return the session mutex to use (never {@code null})
146 */
147 Object getSessionMutex();
148
149 }