completed documentation on session destruction callbacks

org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/PortletRequestAttributes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -278,10 +278,12 @@ public class PortletRequestAttributes extends AbstractRequestAttributes {
 
 	/**
 	 * Register the given callback as to be executed after session termination.
+	 * <p>Note: The callback object should be serializable in order to survive
+	 * web app restarts.
 	 * @param name the name of the attribute to register the callback for
 	 * @param callback the callback to be executed for destruction
 	 */
-	private void registerSessionDestructionCallback(String name, Runnable callback) {
+	protected void registerSessionDestructionCallback(String name, Runnable callback) {
 		PortletSession session = getSession(true);
 		session.setAttribute(DESTRUCTION_CALLBACK_NAME_PREFIX + name,
 				new DestructionCallbackBindingListener(callback));

org.springframework.web/src/main/java/org/springframework/web/context/request/DestructionCallbackBindingListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -23,12 +23,22 @@ import javax.servlet.http.HttpSessionBindingListener;
 /**
  * Adapter that implements the Servlet 2.3 HttpSessionBindingListener
  * interface, wrapping a session destruction callback.
+ *
+ * @author Juergen Hoeller
+ * @since 3.0
+ * @see RequestAttributes#registerDestructionCallback
+ * @see ServletRequestAttributes#registerSessionDestructionCallback
  */
 public class DestructionCallbackBindingListener implements HttpSessionBindingListener, Serializable {
 
 	private final Runnable destructionCallback;
 
 
+	/**
+	 * Create a new DestructionCallbackBindingListener for the given callback.
+	 * @param destructionCallback the Runnable to execute when this listener
+	 * object gets unbound from the session
+	 */
 	public DestructionCallbackBindingListener(Runnable destructionCallback) {
 		this.destructionCallback = destructionCallback;
 	}

org.springframework.web/src/main/java/org/springframework/web/context/request/RequestAttributes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -53,12 +53,19 @@ public interface RequestAttributes {
 	int SCOPE_GLOBAL_SESSION = 2;
 
 
+	/**
+	 * 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 #resolveReference
+	 */
 	String REFERENCE_SESSION = "session";
 
 
-
 	/**
 	 * Return the value for the scoped attribute of the given name, if any.
 	 * @param name the name of the attribute
@@ -108,6 +115,9 @@ public interface RequestAttributes {
 	 * 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

org.springframework.web/src/main/java/org/springframework/web/context/request/ServletRequestAttributes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -243,10 +243,12 @@ public class ServletRequestAttributes extends AbstractRequestAttributes {
 
 	/**
 	 * Register the given callback as to be executed after session termination.
+	 * <p>Note: The callback object should be serializable in order to survive
+	 * web app restarts.
 	 * @param name the name of the attribute to register the callback for
 	 * @param callback the callback to be executed for destruction
 	 */
-	private void registerSessionDestructionCallback(String name, Runnable callback) {
+	protected void registerSessionDestructionCallback(String name, Runnable callback) {
 		HttpSession session = getSession(true);
 		session.setAttribute(DESTRUCTION_CALLBACK_NAME_PREFIX + name,
 				new DestructionCallbackBindingListener(callback));