Consequences (Forward, Redirect, Chain, Stream, etc.)

Forwarding to JSP pages

The basic and most common consequence you will use in your web projects is the Forward. In Mentawai, this is the org.mentawai.core.Forward class, which implements the org.mentawai.core.Consequence interface. The interesting aspects about a forward are listed below:

A forward always happens in the server-side, in other words, the client (the browser) does not realize that a forward is happening. For example, if you make a call to the action http://www.mysite.com/Hello.mtw and the result of the action Hello.class is a forward to /hello.jsp, the location in the address bar of your browser will not change to /hello.jsp. That's because the forward is really happening on the server-side. No other request is needed from the browser. The request is passed over to the JSP page and the result is returned in the same request that asked for the Hello action. This is exactly the opposite of what happens when you do a Redirect.

A forward will always pass the action and all its contexts (Input, Output, Session, Cookies, etc.) to the JSP page. When you do a forward, the results of the action execution are made available to the JSP page. This is the opposite of what happens when you do a Redirect. When you do a redirect, a new request is done by the browser to a new action or JSP page. All the previous action information before the redirect is discarded.

The classic scenario is:
<ul>WebRequest ---------> Action generates some results ----------> Forward to JSP to display the results</ul>
For example for the simple action below you can configure some forwards:

Inside the application manager:

Just keep in mind that whenever you want the action information to be displayed in the JSP page you will most likely want a Forward consequence. Another point to keep in mind is that if the user hits the Reload button in the browser, the whole action is executed again.

Redirecting to a new URL

In Mentawai, the Redirect consequence is implemented by the core class org.mentawai.core.Redirect, which implements the core interface org.mentawai.core.Consequence. When you issue a Redirect consequence, you are really telling the browser: "Hey! Please do another web request to the this URL here!". As a result, the URL location in the address bar of the browser will change to the redirect URL and all the information about the action that performed the redirect will be discarded.

Contrary to the Forward, a Redirect happens in the client-side, in other words, it is the browser that performs another web request to the JSP page or action. You could use a redirect, for example, when you want to avoid having the user accidentally hitting the reload button and executing the action again.

There are many ways to a redirect in Mentawai. Below I will explain each one:

Regular redirect

This is the redirect you will be using 99% of the time and it is always related to the context path of your web application. The context path is the directory where your application is located inside the Tomcat webapps directory. It is what allows the same Tomcat to run a bunch of different web applications together and independently.

Below are some examples:

The first redirect will tell the browser to perform another web request to the following URL:

http://www.mysite.com/DVDStore/congrats.jsp

The second redirect will tell the browser to perform another web request to the following URL:

http://www.mysite.com/DVDStore/user/users.jsp

This is assuming that your context path is "DVDStore". If your context path was the ROOT context path, which is the ROOT directory inside the Tomcat webapps directory, your redirect URLs would be:

http://www.mysite.com/congrats.jsp

http://www.mysite.com/user/users.jsp

Redirect relative to the web server

You can use this redirect when you want to perform a redirect to another web application running in the same web server. For example:

When you start the redirect with a double slash ("//"), you are just saying: "Hey, I don't want to be relative to the context path!" Therefore, even if you context path is "DVDStore", the resulting redirect URLs for the examples above will be:

http://www.mysite.com/BookStore/showBooks.mtw

http://www.mysite.com/index.jsp

This type of redirect is rare. It is only needed when you are running two different applications in the same servlet container that are somehow related to each other.

Redirect with dynamic parameters

Sometimes you want to perform a redirect, but you will only know the parameters of the URL at runtime. For example, you want to redirect the browser to the action that shows all the books for a certain category. This could be something like:

http://www.mysite.com/BookStore/Book.show.mtw?cat=<CATEGORY_ID>

To setup this redirect with a dynamic parameter, you can do this:

The true above indicates that this is a redirect with dynamic parameters that will come from the action output. So our action will just do something like this:

Assuming that book.getCategory() returns 43, the resulting URL would be:

http://www.mysite.com/BookStore/Bood.show.mtw?cat=43

Note that all the values from the action output will be added as parameters to the redirect URL.

Redirect to a dynamic URL

Sometimes you will not even know the URL you want to redirect to. This is rare, but can happen, for example, when you want to redirect your user to a URL saved in a database. Here is how it works:

When you create a redirect using the constructor with empty parameters (or make use of the helper method redir() with empty parameters), the redirect will expect the URL to come from the action output. Here is an example of an action:

Note that you are using the REDIRURL_PARAM from the Redirect consequence to place the dynamic URL inside the action output. You may have other values inside the action output and that's how the redirect class knows how to find the dynamic URL.

Last but not least about the Redirect consequence:

If you redirect contains the string "://" inside it, it is assumed that you want to do a redirect to a absolute address. Examples:

The redirect understands that the above redirect are all absolute URLs, not relative to anything.

There are no redirects relative to the request

This is on purpose. If you try to do something like on(SUCCESS, redir("loosepage.jsp")), Mentawai will automatically assume that you meant on(SUCCESS, redir("/loosepage.jsp")). Redirects relative to the request are not needed and only introduce confusion.

You can also use a dynamic URL with dynamic parameters. Below is how to configure this redirect in the application manager:

Dynamic parameters will be automatically encoded. Dynamic URLs will not be encoded, in other words, if they have any hardcoded parameter it is assumed that it is already encoded.

Chaining actions

For a single web request you can chain different actions in the server-side before invoking a consequence that will return a result to the browser. For example you can have a request handled by action A chained to action B chained to action C and then action C returns a result that will invoke a consequence. You should note that like a forward, chaining actions happens in the server-side. Below is an example of how to configure a chain consequence:

Or you can use the less verbose style:

Before you configure any chain consequence, you must understand that action chaining is rare and in most cases there is no need for you to make use of it. Let's take a classic example where you have an action that adds an user and another action that lists all the users. You may get tempted to do a chain like:

Although definitely not a sin, this could have been done much better with a redirect consequence:

So now after the add inner action is done, it will redirect (not chain) to the show inner action. <u>If the user hits the reload button, only the show inner action will be executed again, and not the whole chain.</u> Note that we are supporting dynamic parameters for the redirect, that's because we may need to add some parameters to the URL before redirecting, for example:

http://www.mysite.com/User.add.mtw?category=34

As we saw in the previous chapter about redirect, these parameters will come from the action output.

To conclude, here is what you should keep in mind when using a chain consequence:

Think if you don't really want a redirect to an action instead of a chain. The question you should ask yourself is: Do you want to execute everything again if the user press the reload button?

When two actions are chained, the input and output of the first are passed to the second.

Each action will be executed with its own set of filters. If we have a global filter, then it will be executed twice, one time for each action.

You can also pass an inner action to the chain controller:

Other consequences

Mentawai comes with other consequences and you can also code your own consequences. For example, to return an image or a binary file you can use the StreamConsequence:

In the action:

In the ApplicationManager:

You can place a byte array or a InputStream as the stream key in the action output. If for example the file is a PDF, you don't want to load everything in memory in a byte array:

An in the ApplicationManager:

For Ajax, you can use the AjaxConsequence that uses a renderer to format the action response into an ajax response (JSON, XML, etc.)

Action:

ApplicationManager: