001/*
002 * Copyright 2002-2013 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.web.context.request;
018
019/**
020 * Abstraction for accessing attribute objects associated with a request.
021 * Supports access to request-scoped attributes as well as to session-scoped
022 * attributes, with the optional notion of a "global session".
023 *
024 * <p>Can be implemented for any kind of request/session mechanism,
025 * in particular for servlet requests and portlet requests.
026 *
027 * @author Juergen Hoeller
028 * @since 2.0
029 * @see ServletRequestAttributes
030 * @see org.springframework.web.portlet.context.PortletRequestAttributes
031 */
032public interface RequestAttributes {
033
034        /**
035         * Constant that indicates request scope.
036         */
037        int SCOPE_REQUEST = 0;
038
039        /**
040         * Constant that indicates session scope.
041         * <p>This preferably refers to a locally isolated session, if such
042         * a distinction is available (for example, in a Portlet environment).
043         * Else, it simply refers to the common session.
044         */
045        int SCOPE_SESSION = 1;
046
047        /**
048         * Constant that indicates global session scope.
049         * <p>This explicitly refers to a globally shared session, if such
050         * a distinction is available (for example, in a Portlet environment).
051         * Else, it simply refers to the common session.
052         */
053        int SCOPE_GLOBAL_SESSION = 2;
054
055
056        /**
057         * Name of the standard reference to the request object: "request".
058         * @see #resolveReference
059         */
060        String REFERENCE_REQUEST = "request";
061
062        /**
063         * Name of the standard reference to the session object: "session".
064         * @see #resolveReference
065         */
066        String REFERENCE_SESSION = "session";
067
068
069        /**
070         * Return the value for the scoped attribute of the given name, if any.
071         * @param name the name of the attribute
072         * @param scope the scope identifier
073         * @return the current attribute value, or {@code null} if not found
074         */
075        Object getAttribute(String name, int scope);
076
077        /**
078         * Set the value for the scoped attribute of the given name,
079         * replacing an existing value (if any).
080         * @param name the name of the attribute
081         * @param scope the scope identifier
082         * @param value the value for the attribute
083         */
084        void setAttribute(String name, Object value, int scope);
085
086        /**
087         * Remove the scoped attribute of the given name, if it exists.
088         * <p>Note that an implementation should also remove a registered destruction
089         * callback for the specified attribute, if any. It does, however, <i>not</i>
090         * need to <i>execute</i> a registered destruction callback in this case,
091         * since the object will be destroyed by the caller (if appropriate).
092         * @param name the name of the attribute
093         * @param scope the scope identifier
094         */
095        void removeAttribute(String name, int scope);
096
097        /**
098         * Retrieve the names of all attributes in the scope.
099         * @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}