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}