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

@@ -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
 

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)
     {