001/*
002 * Copyright 2002-2017 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
019import org.springframework.lang.Nullable;
020
021/**
022 * Abstraction for accessing attribute objects associated with a request.
023 * Supports access to request-scoped attributes as well as to session-scoped
024 * attributes, with the optional notion of a "global session".
025 *
026 * <p>Can be implemented for any kind of request/session mechanism,
027 * in particular for servlet requests.
028 *
029 * @author Juergen Hoeller
030 * @since 2.0
031 * @see ServletRequestAttributes
032 */
033public interface RequestAttributes {
034
035        /**
036         * Constant that indicates request scope.
037         */
038        int SCOPE_REQUEST = 0;
039
040        /**
041         * Constant that indicates session scope.
042         * <p>This preferably refers to a locally isolated session, if such
043         * a distinction is available.
044         * Else, it simply refers to the common session.
045         */
046        int SCOPE_SESSION = 1;
047
048
049        /**
050         * Name of the standard reference to the request object: "request".
051         * @see #resolveReference
052         */
053        String REFERENCE_REQUEST = "request";
054
055        /**
056         * Name of the standard reference to the session object: "session".
057         * @see #resolveReference
058         */
059        String REFERENCE_SESSION = "session";
060
061
062        /**
063         * Return the value for the scoped attribute of the given name, if any.
064         * @param name the name of the attribute
065         * @param scope the scope identifier
066         * @return the current attribute value, or {@code null} if not found
067         */
068        @Nullable
069        Object getAttribute(String name, int scope);
070
071        /**
072         * Set the value for the scoped attribute of the given name,
073         * replacing an existing value (if any).
074         * @param name the name of the attribute
075         * @param scope the scope identifier
076         * @param value the value for the attribute
077         */
078        void setAttribute(String name, Object value, int scope);
079
080        /**
081         * Remove the scoped attribute of the given name, if it exists.
082         * <p>Note that an implementation should also remove a registered destruction
083         * callback for the specified attribute, if any. It does, however, <i>not</i>
084         * need to <i>execute</i> a registered destruction callback in this case,
085         * since the object will be destroyed by the caller (if appropriate).
086         * @param name the name of the attribute
087         * @param scope the scope identifier
088         */
089        void removeAttribute(String name, int scope);
090
091        /**
092         * Retrieve the names of all attributes in the scope.
093         * @param scope the scope identifier
094         * @return the attribute names as String array
095         */
096        String[] getAttributeNames(int scope);
097
098        /**
099         * Register a callback to be executed on destruction of the
100         * specified attribute in the given scope.
101         * <p>Implementations should do their best to execute the callback
102         * at the appropriate time: that is, at request completion or session
103         * termination, respectively. If such a callback is not supported by the
104         * underlying runtime environment, the callback <i>must be ignored</i>
105         * and a corresponding warning should be logged.
106         * <p>Note that 'destruction' usually corresponds to destruction of the
107         * entire scope, not to the individual attribute having been explicitly
108         * removed by the application. If an attribute gets removed via this
109         * facade's {@link #removeAttribute(String, int)} method, any registered
110         * destruction callback should be disabled as well, assuming that the
111         * removed object will be reused or manually destroyed.
112         * <p><b>NOTE:</b> Callback objects should generally be serializable if
113         * they are being registered for a session scope. Otherwise the callback
114         * (or even the entire session) might not survive web app restarts.
115         * @param name the name of the attribute to register the callback for
116         * @param callback the destruction callback to be executed
117         * @param scope the scope identifier
118         */
119        void registerDestructionCallback(String name, Runnable callback, int scope);
120
121        /**
122         * Resolve the contextual reference for the given key, if any.
123         * <p>At a minimum: the HttpServletRequest reference for key "request", and
124         * the HttpSession reference for key "session".
125         * @param key the contextual key
126         * @return the corresponding object, or {@code null} if none found
127         */
128        @Nullable
129        Object resolveReference(String key);
130
131        /**
132         * Return an id for the current underlying session.
133         * @return the session id as String (never {@code null})
134         */
135        String getSessionId();
136
137        /**
138         * Expose the best available mutex for the underlying session:
139         * that is, an object to synchronize on for the underlying session.
140         * @return the session mutex to use (never {@code null})
141         */
142        Object getSessionMutex();
143
144}