This class helps you to automate flash message mechanism, by - * adding flash messages to your responses, for example: + *
This class helps you to automate the flash message mechanism, by + * adding flash messages to your responses. + * + *
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. + * + *
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. + * + *
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. + * + *
Here is a simple example that shows how to properly use it: * *
public final class TkDiscussion implements Take {
* @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"));
* }
* }
*
@@ -62,14 +74,13 @@
*
* public final class TkDiscussion implements Take {
* @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
- * );
- * }
+ * )
+ * );
* }
* }
*
@@ -79,8 +90,10 @@
* Set-Cookie: RsFlash=can%27t%20save%20your%20post%2C%20sorry/SEVERE
*
* 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}. + * + *
To clean up the cookie in the following requests, you will need to + * decorate your {@code Take} with {@link TkFlash}. * *
The class is immutable and thread-safe. * @@ -99,9 +112,12 @@ 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 { @@ -109,9 +125,14 @@ public RsFlash(final String msg) } /** - * 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 { @@ -119,10 +140,15 @@ public RsFlash(final Throwable err) } /** - * 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,10 +157,14 @@ 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 { @@ -142,11 +172,13 @@ public RsFlash(final String msg, final Level level) } /** - * 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 {