A simple application

Let's start by the simplest Mentawai application so that you can easily grasp the basics.

We first start by preparing the inescapable web.xml file that belongs to the Java Servlet API. You will not be configuring anything in this XML file. We will just setup the Mentawai controller and that's it. Unfortunately this is a requirement of the Servlet API and no framework can escape from it. But rest assured that you will not be coming back to this file again.

What we are doing here is setting up the Mentawai controller to handle all requests ending with .mtw, which is the default extension for the Mentawai action. We are also setting up our ApplicationManager (remember that the ApplicationManager is the central Java class responsible for the programmatic configuration of our web application) to be the class examples.helloworld.ApplicationManager. Obs: Starting from version 1.13 you do not need to especify the ApplicationManager class anymore. Mentawai will scan the classes directory looking for it.

Now let's code our action: examples/helloworld/action/HelloMenta.java

Our simple action hello receives an username parameter, checks if it is null or empty, changes it to uppercase and passes it up to the action output. It also places the current time in the action output to be displayed to the user. It can return two results: SUCCESS or ERROR. I will give you a full explanation about the Mentawai architecture later on, but for now let's just go on coding.

We have two JSP pages: index.jsp and /HelloMenta/hello.jsp

index.jsp, which contains the HTML form:

/HelloMenta/hello.jsp, which displays the action result:

The first thing we do on both is to declare that we will use the Mentawai Tags (MentaTags for short) with the "mtw" prefix. On index.jsp we use the mtw:form together with the mtw:submit to create a HTML form. Notice that the action attribute of the mtw:submit tag is "/HelloMenta.hello.mtw". This is the URL (or part of it) that the browser will use to request our action. On hello.jsp we are just using the mtw:out tag to print some action results. As you may have suspected, this tag will print values from the action output.

Now comes the last part, which is our web application configuration. We will start by ignoring the Mentawai conventions (Convention Over Configuration) and configure everything by hand. Then we will use the Mentawai conventions. It is important to know what the conventions are as well as how to escape from them whenever you need or desire.

examples/helloworld/ApplicationManager.java

First recall that this is the class that we have specified in the web.xml file, in other words, this is the class that our application will use as its ApplicationManager. We are overriding the method loadActions to load the action "/HelloMenta". The implementation used is the HelloMenta.class and the method that will be called is the "hello()" method. If the action returns the result SUCCESS the consequence will be a forward to "/HelloMenta/hello.jsp". If the action returns the result ERROR the consequence will be a redirect to "/index.jsp".

That's it. Let's put everything together and run our first Mentawai application. Create a new directory inside your tomcat webapps directory. I used "webapps/HelloWorld". This directory is also called your context path and it separates your application from other ones that might be running in the same tomcat. Place the web.xml file inside the webapps/HelloWorld/WEB-INF directory. Place the mentawai.jar file inside webapps/HelloWorld/WEB-INF/lib directory. Compile your action and application manager (you will need the mentawai.jar in the classpath) and put your classes inside webapps/HelloWorld/WEB-INF/classes. Put your JSP pages inside the webapps/HelloWorld. Remember that the page hello.jsp goes inside webapps/HelloWorld/HelloMenta directory. Alternatively you can click here to download a war file with this example.

Fire up your tomcat, open up your browser and type in the address bar: http://localhost:8080/HelloWorld/

You should now (hopefully!) be seeing your first Mentawai web application.

Now let's check out the Mentawai conventions so that you can see for yourself that you only need to configure when you want to or when you need to. On line 10 of ApplicationManager.java your wrote the action name as being "/HelloMenta" but that could have been omitted as Mentawai assumes the name of the action to be the same name as the action class. As the action class is HelloMenta.class, writing "/HelloMenta" for your action name is redundant. So let's remove it:

The method "hello" is not redundant, but it is definitely not necessary here. If you do not specify the method, Mentawai assumes that the configuration should be applied to all methods (or actions) inside the HelloMenta class. If you specify the method name, then it assumes that the configuration should be applied only for that method (or action). So let's remove it for now:

Now talking about the consequences, which in our case were the forward and redirect to the appropriate JSP pages, Mentawai provides conventions for the consequences as well. If you do not specify the consequence for an action, Mentawai assumes that you want a forward (not a redirect) to a JSP page that will be in the location /action_class/action_method.jsp. So in our example, the convention for the action /HelloMenta.hello.mtw would be to forward to /HelloMenta/hello.jsp, which is exactly the path to our hello.jsp page. (Now you see that choosing /HelloMenta/hello.jsp instead of /hello.jsp had a reason

)

So you can remove the consequence for SUCCESS and let Mentawai use its conventions:

We are left with only one consequence configured for the result ERROR. If you remove that consequence, Mentawai will again use its conventions for the ERROR result, the same way it did for the SUCCESS result: it will forward to /HelloMenta/hello.jsp. This is probably not what you want and that's a good example of a case where conventions will not work. The moral of the story is that you should use conventions to save typing and configuration, but you should be ready to configure by hand when the need arises or because you want to take control instead of letting Mentawai decides by itself through its conventions.