/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.context.request;

import org.springframework.lang.Nullable;

Abstraction for accessing attribute objects associated with a request.
Supports access to request-scoped attributes as well as to session-scoped
attributes, with the optional notion of a "global session".
Can be implemented for any kind of request/session mechanism,
in particular for servlet requests.
Author:
Juergen Hoeller
See Also:
ServletRequestAttributes
Since:
2.0/**
 * Abstraction for accessing attribute objects associated with a request.
 * Supports access to request-scoped attributes as well as to session-scoped
 * attributes, with the optional notion of a "global session".
 *
 * <p>Can be implemented for any kind of request/session mechanism,
 * in particular for servlet requests.
 *
 * @author Juergen Hoeller
 * @since 2.0
 * @see ServletRequestAttributes
 */
public interface RequestAttributes {

	
Constant that indicates request scope.
/**
	 * Constant that indicates request scope.
	 */
	int SCOPE_REQUEST = 0;

	
Constant that indicates session scope.
This preferably refers to a locally isolated session, if such
a distinction is available.
Else, it simply refers to the common session.
/**
	 * Constant that indicates session scope.
	 * <p>This preferably refers to a locally isolated session, if such
	 * a distinction is available.
	 * Else, it simply refers to the common session.
	 */
	int SCOPE_SESSION = 1;


	
Name of the standard reference to the request object: "request".
See Also:
resolveReference/**
	 * Name of the standard reference to the request object: "request".
	 * @see #resolveReference
	 */
	String REFERENCE_REQUEST = "request";

	
Name of the standard reference to the session object: "session".
See Also:
resolveReference/**
	 * Name of the standard reference to the session object: "session".
	 * @see #resolveReference
	 */
	String REFERENCE_SESSION = "session";


	
Return the value for the scoped attribute of the given name, if any.
Params:
name – the name of the attribute
scope – the scope identifier
Returns:
the current attribute value, or null if not found/**
	 * Return the value for the scoped attribute of the given name, if any.
	 * @param name the name of the attribute
	 * @param scope the scope identifier
	 * @return the current attribute value, or {@code null} if not found
	 */
	@Nullable
	Object getAttribute(String name, int scope);

	
Set the value for the scoped attribute of the given name,
replacing an existing value (if any).
Params:
name – the name of the attribute
scope – the scope identifier
value – the value for the attribute/**
	 * Set the value for the scoped attribute of the given name,
	 * replacing an existing value (if any).
	 * @param name the name of the attribute
	 * @param scope the scope identifier
	 * @param value the value for the attribute
	 */
	void setAttribute(String name, Object value, int scope);

	
Remove the scoped attribute of the given name, if it exists.
Note that an implementation should also remove a registered destruction
callback for the specified attribute, if any. It does, however, not
need to execute a registered destruction callback in this case,
since the object will be destroyed by the caller (if appropriate).
Params:
name – the name of the attribute
scope – the scope identifier/**
	 * Remove the scoped attribute of the given name, if it exists.
	 * <p>Note that an implementation should also remove a registered destruction
	 * callback for the specified attribute, if any. It does, however, <i>not</i>
	 * need to <i>execute</i> a registered destruction callback in this case,
	 * since the object will be destroyed by the caller (if appropriate).
	 * @param name the name of the attribute
	 * @param scope the scope identifier
	 */
	void removeAttribute(String name, int scope);

	
Retrieve the names of all attributes in the scope.
Params:
scope – the scope identifier
Returns:
the attribute names as String array/**
	 * Retrieve the names of all attributes in the scope.
	 * @param scope the scope identifier
	 * @return the attribute names as String array
	 */
	String[] getAttributeNames(int scope);

	
Register a callback to be executed on destruction of the
specified attribute in the given scope.
Implementations should do their best to execute the callback
at the appropriate time: that is, at request completion or session
termination, respectively. If such a callback is not supported by the
underlying runtime environment, the callback must be ignored
and a corresponding warning should be logged.
Note that 'destruction' usually corresponds to destruction of the entire scope, not to the individual attribute having been explicitly removed by the application. If an attribute gets removed via this facade's removeAttribute(String, int) method, any registered destruction callback should be disabled as well, assuming that the removed object will be reused or manually destroyed. 
NOTE: Callback objects should generally be serializable if
they are being registered for a session scope. Otherwise the callback
(or even the entire session) might not survive web app restarts.
Params:
name – the name of the attribute to register the callback for
callback – the destruction callback to be executed
scope – the scope identifier/**
	 * Register a callback to be executed on destruction of the
	 * specified attribute in the given scope.
	 * <p>Implementations should do their best to execute the callback
	 * at the appropriate time: that is, at request completion or session
	 * termination, respectively. If such a callback is not supported by the
	 * underlying runtime environment, the callback <i>must be ignored</i>
	 * and a corresponding warning should be logged.
	 * <p>Note that 'destruction' usually corresponds to destruction of the
	 * entire scope, not to the individual attribute having been explicitly
	 * removed by the application. If an attribute gets removed via this
	 * facade's {@link #removeAttribute(String, int)} method, any registered
	 * destruction callback should be disabled as well, assuming that the
	 * removed object will be reused or manually destroyed.
	 * <p><b>NOTE:</b> Callback objects should generally be serializable if
	 * they are being registered for a session scope. Otherwise the callback
	 * (or even the entire session) might not survive web app restarts.
	 * @param name the name of the attribute to register the callback for
	 * @param callback the destruction callback to be executed
	 * @param scope the scope identifier
	 */
	void registerDestructionCallback(String name, Runnable callback, int scope);

	
Resolve the contextual reference for the given key, if any.
At a minimum: the HttpServletRequest reference for key "request", and
the HttpSession reference for key "session".
Params:
key – the contextual key
Returns:
the corresponding object, or null if none found/**
	 * Resolve the contextual reference for the given key, if any.
	 * <p>At a minimum: the HttpServletRequest reference for key "request", and
	 * the HttpSession reference for key "session".
	 * @param key the contextual key
	 * @return the corresponding object, or {@code null} if none found
	 */
	@Nullable
	Object resolveReference(String key);

	
Return an id for the current underlying session.
Returns:
the session id as String (never null)/**
	 * Return an id for the current underlying session.
	 * @return the session id as String (never {@code null})
	 */
	String getSessionId();

	
Expose the best available mutex for the underlying session:
that is, an object to synchronize on for the underlying session.
Returns:
the session mutex to use (never null)/**
	 * Expose the best available mutex for the underlying session:
	 * that is, an object to synchronize on for the underlying session.
	 * @return the session mutex to use (never {@code null})
	 */
	Object getSessionMutex();

}