From 5cc81fd0178206d4291255223d5755907589ee70 Mon Sep 17 00:00:00 2001
From: Greg Wilkins <greg@webtide.com>
Date: Thu, 28 Oct 2010 02:29:13 +0000
Subject: [PATCH] 328778 Improved javadoc for secure session cookies

git-svn-id: svn+ssh://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk@2425 7e9141cc-0065-0410-87d8-b60c137991c4
---
 VERSION.txt                                       |  1 +
 .../server/session/AbstractSessionManager.java    | 15 +++++++++++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/VERSION.txt b/VERSION.txt
index 3b73bf1c0c7..d839c531727 100644
--- a/VERSION.txt
+++ b/VERSION.txt
@@ -5,6 +5,7 @@
  + 328332 Response.getContentType works with setHeader
  + 328523 Fixed overloaded setters in AppProvider
  + 328008 Handle update to Servlet Spec 3 Section 8.2.3.h.ii
+ + 328778 Improved javadoc for secure session cookies
  + 328782 allow per connection max idle time to be set
  + 328885 web overrides do not override
 
diff --git a/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java b/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
index dc0db866b22..51561f12f8e 100644
--- a/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
+++ b/jetty-server/src/main/java/org/eclipse/jetty/server/session/AbstractSessionManager.java
@@ -26,6 +26,7 @@ import java.util.List;
 import java.util.Map;
 
 import javax.servlet.ServletContext;
+import javax.servlet.ServletRequest;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 import javax.servlet.http.HttpSession;
@@ -38,6 +39,7 @@ import javax.servlet.http.HttpSessionEvent;
 import javax.servlet.http.HttpSessionListener;
 
 import org.eclipse.jetty.http.HttpCookie;
+import org.eclipse.jetty.server.AbstractConnector;
 import org.eclipse.jetty.server.HttpConnection;
 import org.eclipse.jetty.server.Request;
 import org.eclipse.jetty.server.Server;
@@ -532,8 +534,17 @@ public abstract class AbstractSessionManager extends AbstractLifeCycle implement
 
     /* ------------------------------------------------------------ */
     /**
-     * @param secureCookies
-     *            The secureCookies to set.
+     * Set if the session manager should use SecureCookies.
+     * A secure cookie will only be sent by a browser on a secure (https) connection to 
+     * avoid the concern of cookies being intercepted on non secure channels.
+     * For the cookie to be issued as secure, the {@link ServletRequest#isSecure()} method must return true.
+     * If SSL offload is used, then the {@link AbstractConnector#customize(org.eclipse.jetty.io.EndPoint, Request)
+     * method can be used to force the request to be https, or the {@link AbstractConnector#setForwarded(boolean)}
+     * can be set to true, so that the X-Forwarded-Proto header is respected.
+     * <p>
+     * If secure session cookies are used, then a session may not be shared between http and https requests.
+     * 
+     * @param secureCookies If true, use secure cookies.
      */
     public void setSecureCookies(boolean secureCookies)
     {