Package org.takes.facets.flash

Flash messages.

See: Description

Class Summary

Class	Description
RsFlash	Forwarding response.
TkFlash	Take that understands Flash cookie and converts it into a HTTP header.
XeFlash	Xembly source to show flash message in XML.

Package org.takes.facets.flash Description

Flash messages.

Flash messages is a useful technique that allows us to send short texts from one web page to another without any persistence on the server. Here is how it works. A web page performs some operation, for example making a post to a discussion thread. Then, the page returns a HTTP response with a redirection status 303. The response contains a "Set-Cookie" HTTP header with a flash message "thanks for the post".

The browser preserves the cookie and redirects to the page with the discussion thread. The browser makes a new HTTP request, to render the content of the discussion thread. This HTTP GET request contains a "Cookie" HTTP header with that message "thanks for the post". The server adds this message to the HTML page, informing the user about the action just completed, and returns a HTTP response. This response contains a "Set-Cookie" HTTP header with an empty value, which is a signal for the browser to remove the cookie.

The browser won't send the flash message twice, because it is deleted after the first time it was rendered in HTML by the server. The deletion is controlled by the server, when it returns an HTTP response with "Set-Cookie" header with an empty value.

Classes in this package helps to automate this mechanism. First, you add flash messages to your responses using RsFlash:

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"
     );
   }
 }

This RsFlash decorator will add the required "Set-Cookie" header to the response. This is all it is doing. The response is added to the cookie in URL-encoded format, together with the logging level. Flash messages could be of different severity, we're using Java logging levels for that, for example:

public final class TkDiscussion implements Take {
   @Override
   public Response act(final Request req) {
     if (failed) {
       throw new RsFlash(
         new RsForward(),
         "can't save your post, sorry",
         java.util.logging.Level.SEVERE
       );
     }
   }
 }

This is how the HTTP response will look like (simplified):

 HTTP/1.1 303 See Other
 Set-Cookie: RsFlash=can%27t%20save%20your%20post%2C%20sorry/SEVERE

Here, the name of the cookie is RsFlash. You can change this default name using a constructor of RsFlash, but it's not recommended. It's better to use the default name.

The next step is to understand that cookie on its way back, from the browser to the server. This is what a browser will send back:

 GET / HTTP/1.1
 Host: www.example.com
 Cookie: RsFlash=can%27t%20save%20your%20post%2C%20sorry/SEVERE

There is a class TkFlash, that decorates your existing "take" and adds "Set-Cookie" with an empty value to the response. That's all it's doing. All you need to do is to decorate your existing "take", for example:

 new FtBasic(
   new TkFlash(TkFork(new FkRegex("/", "hello, world!"))), 8080
  ).start(Exit.NEVER);
 }

The last step is to fetch that cookie from the request and add to the HTML page. You can use RqCookies for that (it's a pseudo-code, don't build HTML like this!):

public final class TkDiscussion implements Take {
   @Override
   public Response act(final Request req) {
     String html = "this is our discussion thread...";
     final Iterator<String> cookies =
       new RqCookies(req).cookie("RsFlash").iterator();
       if (cookies.hasNext()) {
         html = cookies.next() + html;
       }
       return new RsHTML(html);
     }
   }
 }

If you're using Xembly to build XML output, you can use XeFlash for fetching flash messages from cookies and adding them to XML:

public final class TkDiscussion implements Take {
   private final Request req;
   @Override
   public Response act(final Request req) {
     return new RsXembly(
       new XeAppend(
         "page",
         new XeFlash(req),
         // your other Xembly sources
       )
     );
   }
 }

Don't forget that the cookie you receive is not just a flash message, but also other parameters, URL-encoded and separated by "slash".

Since:

0.1

Version:

$Id$

Author:

Yegor Bugayenko ([email protected])