Mentawai Web Framework

One Minute Start

  • Click here to download the latest Mentawai binaries.


  • Extract the contents of this zip file inside any empty directory.


  • Grab the file mentawai.jar and place it inside the /WEB-INF/lib directory of your web application. You can create this directory if it does not already exist.


  • Grab the file mentacontainer-X.X.X.jar and place it inside the /WEB-INF/lib directory of your web application.


  • Create the /WEB-INF/web.xml file of your web application so it can handle mentawai actions. (include the lines below)
    (OBS: there is no escape from this file, but it is the last XML you will see!)
    • <!-- The Mentawai controller -->
<web-app>
<servlet>
	<servlet-name>Controller</servlet-name>
	<servlet-class>org.mentawai.core.Controller</servlet-class>
	<load-on-startup>1</load-on-startup>		
</servlet>

<!-- You must choose an extension to indicate a mentawai action -->
<servlet-mapping>
	<servlet-name>Controller</servlet-name>
	<url-pattern>*.mtw</url-pattern>
</servlet-mapping>
</web-app>

  • All we are doing is mapping requests ending with *.mtw to the Mentawai controller.


  • That's it. You are ready to start using the mentawai framework!

Action Lifecycle

The lifecyle of a mentawai action is:

  • The controller receives a request (javax.servlet.http.HttpServletRequest).

  • The controller looks for the corresponding mentawai action.

  • The controller prepares the Input, Output, Contexts (Session, Application, Cookies, etc.) and inject in the action.

  • The controller executes the action together with any filters it might have.

  • The action returns a result (java.lang.String), usually SUCCESS or ERROR.

  • For each result, there is a consequence (org.mentawai.core.Consequence), usually a FORWARD or a REDIRECT.

  • The controller handles/executes the consequence.

That's just for your understanding of what goes on behind the scenes, but you really don't have to care about it. All you have to do is write your actions and filters.

My first project: Hello World

If you want to deploy this simple Mentawai web application in your web container, click here to download the HelloMentawai war. To deploy a war file, all you need to do is place it in the webapps directory. (Note: Some browsers, like mine, will change the extension to .zip when you try to save the file. Rename the file to .war if you need to.) 


package examples.helloworld;

import java.util.*;

import org.mentawai.core.*;

public class HelloMentawai extends BaseAction {
	
	public String execute() throws Exception {
		String username = input.getString("username");
		if (username == null || username.trim().equals("")) {
			return ERROR;
		}
		output.setValue("username", username.toUpperCase());
		return SUCCESS;
	}
	
}

When you extend org.mentawai.core.BaseAction, your class gets access to some useful protected data members. In the HelloMentawai action we are using two of them:
  • input: The input (org.mentawai.core.Input) with header and parameters values. You can access http request information through this interface. Parameters can be any Java object, not just Strings.


  • output: The output (org.mentawai.core.Output) of the action. For example, your action may go to a database and fetch a list of users.You can put this list in the output of the action. Later on, if the consequence of the action is a FORWARD, you can access the action output in the view layer.


In this simple action, we are just returning the uppercase version of an username. The result is either SUCCESS or ERROR if the user did not type anything in the form field.

An action must have a name (or alias) and consequences for its results. Instead of using a boring XML file, Mentawai will let you do that with java code.

// no package (root package)

import org.mentawai.core.*;

public class ApplicationManager extends org.mentawai.core.ApplicationManager {
	
    public void loadActions() {
        
        // Ruby style: less verbose and less clear
        
        action("/HelloWorld", HelloMentawai.class)
            
            .on(SUCCESS, fwd("/hello.jsp"))
            .on(ERROR, fwd("/username.jsp"));
            
        // Java style: more verbose and more clear
        
        ActionConfig ac = new ActionConfig("/HelloWorld", HelloMentawai.class);
        ac.addConsequence(SUCCESS, new Forward("/hello.jsp"));
        ac.addConsequence(ERROR, new Forward("/username.jsp"));
        addActionConfig(ac); // add this action to the application manager
            
    }
}
The name of the action defines how you can call the action from a browser or html page.Therefore the above action can be called through the link http://www.yourapp.com/HelloWorld.mtw or, if you are using an application context different than ROOT, http://www.yourapp.com/YOUR_APP_CONTEXT/HelloWorld.mtw.

Our action /HelloWorld will use the HelloMentawai class as its implementation.

The consequence for a SUCCESS will be a forward to /hello.jsp. The consequence for a ERROR will be a forward to /username.jsp.

You should put the above class (ApplicationManager.class) in the /WEB-INF/classes directory or your web application. This makes sence because we did not define any package for the class.By default, Mentawai looks for this class when the container starts, but you can specify another class name with the following lines in your web.xml file:

<web-app>
<!-- The Mentawai controller -->
<servlet>
    <servlet-name>Controller</servlet-name>
    <servlet-class>org.mentawai.core.Controller</servlet-class>
    <init-param>
        <param-name>applicationManager</param-name>
        <param-value>examples.helloworld.ApplicationManager</param-value>
    </init-param>        
    <load-on-startup>1</load-on-startup>		
</servlet>

<!-- You must choose an extension to indicate a mentawai action -->
<servlet-mapping>
    <servlet-name>Controller</servlet-name>
    <url-pattern>*.mtw</url-pattern>
</servlet-mapping>
</web-app>

Above we are specifying that our ApplicationManager class is examples.helloworld.ApplicationManager, overriding the default.Notice that it is a good idea to stick with the Mentawai default and keep your ApplicationManager class with an empty package, in other words, apart from the rest of your application.

The contents of the file username.jsp are below.It is just a HTML form to submit the username to our HelloMentawai action. 

<html>
<body>
<h1>Hello Metawai!</h1>
<mtw:form>
Type your username: <mtw:input name="username" size="25" />
<mtw:submit value="Send" action="/HelloWorld.mtw" method="post" />
</mtw:form>
</body>
</html>

The contents of the file hello.jsp are below. Note the use of a Mentawai tag to display an output. 
<%@ taglib uri="/WEB-INF/lib/mentawai.jar" prefix="mtw" %>
<html>
<body>
<h3>Hello <mtw:out value="username" /> from Mentawai!</h3><!-- Menta Tag -->
<!-- or, if you prefer... -->
<%--
<h3>Hello <c:out value="${username}" /> from Mentawai!</h3><!-- JSTL -->
<h3>Hello ${username} from Mentawai!</h3><!-- EL -->
<h3>Hello $username from Mentawai!</h3><!-- Velocity -->
--%>
</body>
</html>
Because the success consequence is a FORWARD, all the action information is available in the view layer and we can use the handy <mtw:out> tag to display a value in the action output. This tag works pretty much like a JSP EL (Expression Language) looking for the value in the page, output (request), session and application scopes. You can also use the dot operator (.) to access properties like in user.name.firstName.