Merge branch '__rultor'

src/main/java/org/takes/facets/flash/RsFlash.java

@@ -40,17 +40,29 @@
 /**
  * Forwarding response.
  *
- * <p>This class helps you to automate flash message mechanism, by
- * adding flash messages to your responses, for example:
+ * <p>This class helps you to automate the flash message mechanism, by
+ * adding flash messages to your responses.
+ *
+ * <p>The flash concept is taken from Ruby on Rails, it is actually the ability
+ * to pass temporary variables between requests which is particularly helpful
+ * especially in case of a redirect.
+ *
+ * <p>The flash message mechanism is meant to be used in case you have a
+ * dynamic content to render in which you want to add success or error
+ * messages. The typical use case is when you have a form that the user can
+ * submit and you want to be able to indicate whether the request was
+ * successful or not.
+ *
+ * <p>The flash mechanism is a stateful mechanism based on a cookie so it is
+ * not meant to be used to implement stateless components such as a RESTful
+ * service.
+ *
+ * <p>Here is a simple example that shows how to properly use it:
  *
  * <pre>public final class TkDiscussion implements Take {
  *   &#64;Override
- *   public Response act(final Request req) {
- *     // save the post to the database
- *     return new RsFlash(
- *       new RsForward(),
- *       "thanks for the post"
- *     );
+ *   public Response act(final Request req) throws IOException {
+ *     return new RsForward(new RsFlash("thanks for the post"));
  *   }
  * }</pre>
  *
@@ -62,14 +74,13 @@
  *
  * <pre>public final class TkDiscussion implements Take {
  *   &#64;Override
- *   public Response act(final Request req) {
- *     if (failed) {
- *       throw new RsFlash(
- *         new RsForward(),
+ *   public Response act(final Request req) throws IOException {
+ *     return new RsForward(
+ *       new RsFlash(
  *         "can't save your post, sorry",
  *         java.util.logging.Level.SEVERE
- *       );
- *     }
+ *       )
+ *     );
  *   }
  * }</pre>
  *
@@ -79,8 +90,10 @@
  * Set-Cookie: RsFlash=can%27t%20save%20your%20post%2C%20sorry/SEVERE</pre>
  *
  * <p>Here, the name of the cookie is {@code RsFlash}. You can change this
- * default name using a constructor of {@link org.takes.facets.flash.RsFlash},
- * but it's not recommended. It's better to use the default name.
+ * default name using a constructor of {@link org.takes.facets.flash.RsFlash}.
+ *
+ * <p>To clean up the cookie in the following requests, you will need to
+ * decorate your {@code Take} with {@link TkFlash}.
  *
  * <p>The class is immutable and thread-safe.
  *
@@ -99,30 +112,43 @@ public final class RsFlash extends RsWrap {
     private final transient String text;
 
     /**
-     * Ctor.
+     * Constructs a {@code RsFlash} with the specified message.
+     * By default it will use {@code RsFlash} as cookie name.
+     *
      * @param msg Message to show
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      */
     public RsFlash(final String msg)
         throws UnsupportedEncodingException {
         this(msg, Level.INFO);
     }
 
     /**
-     * Ctor.
+     * Constructs a {@code RsFlash} with the specified error. The error is
+     * converted into a flash message by calling
+     * {@link Throwable#getLocalizedMessage()}}.
+     * By default it will use {@code RsFlash} as cookie name.
+     *
      * @param err Error
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      */
     public RsFlash(final Throwable err)
         throws UnsupportedEncodingException {
         this(err, Level.SEVERE);
     }
 
     /**
-     * Ctor.
+     * Constructs a {@code RsFlash} with the specified error and logging level.
+     * The error is converted into a flash message by calling
+     * {@link Throwable#getLocalizedMessage()}}.
+     * By default it will use {@code RsFlash} as cookie name.
+     *
      * @param err Error
      * @param level Level
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      * @since 0.17
      */
     public RsFlash(final Throwable err, final Level level)
@@ -131,22 +157,28 @@ public RsFlash(final Throwable err, final Level level)
     }
 
     /**
-     * Ctor.
+     * Constructs a {@code RsFlash} with the specified message and logging
+     * level.
+     * By default it will use {@code RsFlash} as cookie name.
+     *
      * @param msg Message
      * @param level Level
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      */
     public RsFlash(final String msg, final Level level)
         throws UnsupportedEncodingException {
         this(msg, level, RsFlash.class.getSimpleName());
     }
 
     /**
-     * Ctor.
+     * Constructs a {@code RsFlash} with the specified message, logging level
+     * and cookie name.
      * @param msg Message
      * @param level Level
      * @param cookie Cookie name
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      */
     public RsFlash(final String msg, final Level level, final String cookie)
         throws UnsupportedEncodingException {
@@ -161,7 +193,8 @@ public RsFlash(final String msg, final Level level, final String cookie)
      * @param level Level
      * @param cookie Cookie name
      * @return Response
-     * @throws UnsupportedEncodingException If fails
+     * @throws UnsupportedEncodingException In case the default encoding is not
+     *  supported
      */
     private static Response make(final String msg, final Level level,
         final String cookie) throws UnsupportedEncodingException {