session: doc + bugs

Author: jknack

TODO

@@ -1,6 +1,5 @@
 * tests and coverage
 
-* cookie (request and response)
 * rename application.port and server related properties to server.port
-* allow to configure context path and port + server properties from configuration file.
+* allow to configure context pa./javath and port + server properties from configuration file.
 * websockets

etc/source/jooby-style.xml

@@ -85,7 +85,9 @@
     <module name="JavadocMethod">
       <property name="scope" value="public" />
     </module>
-    <module name="JavadocType"/>
+    <module name="JavadocType">
+      <property name="scope" value="public" />
+    </module>
     <module name="JavadocVariable">
       <property name="scope" value="public" />
     </module>

jooby/src/main/java/io/jooby/Context.java

@@ -17,8 +17,6 @@
 
 import io.jooby.internal.HashValue;
 import io.jooby.internal.MissingValue;
-import io.jooby.internal.RequestSessionStore;
-import io.jooby.internal.SessionImpl;
 import io.jooby.internal.SingleValue;
 import io.jooby.internal.UrlParser;
 import io.netty.buffer.ByteBuf;
@@ -122,6 +120,11 @@ public interface Context {
    * **********************************************************************************************
    */
 
+  /**
+   * Find a session or creates a new session.
+   *
+   * @return Session.
+   */
   default @Nonnull Session session() {
     Session session = sessionOrNull();
     if (session == null) {
@@ -135,12 +138,15 @@ public interface Context {
       setResponseCookie(sessionOptions.getCookie().setValue(newSession.getId()));
 
       session = Session.create(this, newSession);
-
-      attribute("session", session);
     }
     return session;
   }
 
+  /**
+   * Find an existing session.
+   *
+   * @return Exsiting session or <code>null</code>.
+   */
   default @Nullable Session sessionOrNull() {
     Session session = (Session) getAttributes().get("session");
     if (session == null) {
@@ -162,11 +168,16 @@ public interface Context {
         setResponseCookie(cookie.setValue(id));
       }
       session = Session.create(this, session);
-      attribute("session", session);
     }
     return session;
   }
 
+  /**
+   * Get a cookie matching the given name.
+   *
+   * @param name Cookie's name.
+   * @return Cookie value.
+   */
   default @Nonnull Value cookie(@Nonnull String name) {
     String value = cookieMap().get(name);
     return value == null ? Value.missing(name) : Value.value(name, value);
@@ -933,6 +944,12 @@ default long getRequestLength() {
    */
   @Nonnull Context setResponseLength(long length);
 
+  /**
+   * Set/add a cookie to response.
+   *
+   * @param cookie Cookie to add.
+   * @return This context.
+   */
   @Nonnull Context setResponseCookie(@Nonnull Cookie cookie);
 
   /**

jooby/src/main/java/io/jooby/Cookie.java

@@ -45,16 +45,27 @@ public class Cookie {
    */
   private long maxAge = -1;
 
+  /**
+   * Creates a response cookie.
+   *
+   * @param name Cookie's name.
+   * @param value Cookie's value or <code>null</code>.
+   */
   public Cookie(@Nonnull String name, @Nullable String value) {
     this.name = name;
     this.value = value;
   }
 
+  /**
+   * Creates a response cookie without a value.
+   *
+   * @param name Cookie's name.
+   */
   public Cookie(@Nonnull String name) {
     this(name, null);
   }
 
-  public Cookie(@Nonnull Cookie cookie) {
+  private Cookie(@Nonnull Cookie cookie) {
     this.domain = cookie.domain;
     this.value = cookie.value;
     this.name = cookie.name;
@@ -64,90 +75,220 @@ public Cookie(@Nonnull Cookie cookie) {
     this.httpOnly = cookie.httpOnly;
   }
 
-  public Cookie clone() {
+  /**
+   * Copy all state from this cookie and creates a new cookie.
+   *
+   * @return New cookie.
+   */
+  public @Nonnull Cookie clone() {
     return new Cookie(this);
   }
 
+  /**
+   * Cookie's name.
+   *
+   * @return Cookie's name.
+   */
   public @Nonnull String getName() {
     return name;
   }
 
+  /**
+   * Set cookie's name.
+   *
+   * @param name Cookie's name.
+   * @return This cookie.
+   */
   public @Nonnull Cookie setName(@Nonnull String name) {
     this.name = name;
     return this;
   }
 
+  /**
+   * Cookie's value.
+   *
+   * @return Cookie's value.
+   */
   public @Nullable String getValue() {
     return value;
   }
 
+  /**
+   * Set cookie's value.
+   *
+   * @param value Cookie's value.
+   * @return This cookie.
+   */
   public @Nonnull Cookie setValue(@Nonnull String value) {
     this.value = value;
     return this;
   }
 
+  /**
+   * Cookie's domain.
+   *
+   * @return Cookie's domain.
+   */
   public @Nullable String getDomain() {
     return domain;
   }
 
+  /**
+   * Get cookie's domain.
+   *
+   * @param domain Defaults cookie's domain.
+   * @return Cookie's domain..
+   */
   public @Nonnull String getDomain(@Nonnull String domain) {
     return this.domain == null ? domain : domain;
   }
 
+  /**
+   * Set cookie's domain.
+   *
+   * @param domain Cookie's domain.
+   * @return This cookie.
+   */
   public @Nonnull Cookie setDomain(@Nonnull String domain) {
     this.domain = domain;
     return this;
   }
 
+  /**
+   * Cookie's path.
+   *
+   * @return Cookie's path.
+   */
   public @Nullable String getPath() {
     return path;
   }
 
+  /**
+   * Cookie's path.
+   *
+   * @param path Defaults path.
+   * @return Cookie's path.
+   */
   public @Nonnull String getPath(@Nonnull String path) {
     return this.path == null ? path : this.path;
   }
 
+  /**
+   * Set cookie's path.
+   *
+   * @param path Cookie's path.
+   * @return This cookie.
+   */
   public @Nonnull Cookie setPath(@Nonnull String path) {
     this.path = path;
     return this;
   }
 
+  /**
+   * Cookie's http-only flag.
+   *
+   * @return Htto-only flag.
+   */
   public boolean isHttpOnly() {
     return httpOnly;
   }
 
+  /**
+   * Set cookie's http-only.
+   *
+   * @param httpOnly Cookie's http-only.
+   * @return This cookie.
+   */
   public Cookie setHttpOnly(boolean httpOnly) {
     this.httpOnly = httpOnly;
     return this;
   }
 
+  /**
+   * Secure cookie.
+   *
+   * @return Secure cookie flag.
+   */
   public boolean isSecure() {
     return secure;
   }
 
+  /**
+   * Set cookie secure flag..
+   *
+   * @param secure Cookie's secure.
+   * @return This cookie.
+   */
   public @Nonnull Cookie setSecure(boolean secure) {
     this.secure = secure;
     return this;
   }
 
+  /**
+   * Max age value:
+   *
+   * - <code>-1</code>: indicates a browser session. It is deleted when user closed the browser.
+   * - <code>0</code>: indicates a cookie has expired and browser must delete the cookie.
+   * - <code>positive value</code>: indicates the number of seconds from current date, where browser
+   *   must expires the cookie.
+   *
+   * @return Max age, in seconds.
+   */
   public long getMaxAge() {
     return maxAge;
   }
 
-  public @Nonnull Cookie setMaxAge(long maxAge) {
-    this.maxAge = maxAge;
-    return this;
-  }
-
+  /**
+   * Set max age value:
+   *
+   * - <code>-1</code>: indicates a browser session. It is deleted when user closed the browser.
+   * - <code>0</code>: indicates a cookie has expired and browser must delete the cookie.
+   * - <code>positive value</code>: indicates the number of seconds from current date, where browser
+   *   must expires the cookie.
+   *
+   * @param maxAge Cookie max age.
+   * @return This options.
+   */
   public @Nonnull Cookie setMaxAge(@Nonnull Duration maxAge) {
     return setMaxAge(maxAge.getSeconds());
   }
 
+  /**
+   * Set max age value:
+   *
+   * - <code>-1</code>: indicates a browser session. It is deleted when user closed the browser.
+   * - <code>0</code>: indicates a cookie has expired and browser must delete the cookie.
+   * - <code>positive value</code>: indicates the number of seconds from current date, where browser
+   *   must expires the cookie.
+   *
+   * @param maxAge Cookie max age, in seconds.
+   * @return This options.
+   */
+  public @Nonnull Cookie setMaxAge(long maxAge) {
+    if (maxAge >= 0) {
+      this.maxAge = maxAge;
+    } else {
+      this.maxAge = -1;
+    }
+    return this;
+  }
+
   @Override public String toString() {
-    return name;
+    StringBuilder buff = new StringBuilder();
+    buff.append(name).append("=");
+    if (value != null) {
+      buff.append(value);
+    }
+    return buff.toString();
   }
 
-  public String toCookieString() {
+  /**
+   * Generates a cookie string. This is the value we sent to the client as <code>Set-Cookie</code>
+   * header.
+   *
+   * @return Cookie string.
+   */
+  public @Nonnull String toCookieString() {
     StringBuilder sb = new StringBuilder();
 
     // name = value

jooby/src/main/java/io/jooby/Router.java

@@ -18,7 +18,6 @@
 import org.slf4j.Logger;
 
 import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import javax.inject.Provider;
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -657,8 +656,19 @@ default Router error(@Nonnull Predicate<StatusCode> predicate,
    */
   @Nonnull Router setRouterOptions(@Nonnull RouterOptions options);
 
+  /**
+   * Get session options. Session store defines how HTTP session is managed it.
+   *
+   * @return Session options.
+   */
   @Nonnull SessionOptions getSessionOptions();
 
+  /**
+   * Set session options.
+   *
+   * @param options Session options.
+   * @return This router.
+   */
   @Nonnull Router setSessionOptions(@Nonnull SessionOptions options);
 
   /**