Last Updates | Login      

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.

Bypassing the action

In this chapter I want to give you a taste for POJO actions. In a web application, actions are meant to process the HTTP request and to invoke the business model of your application. A common misconception is to assume that your action is implementing your business model. Although this is possible, it is not recommended for serious applications for the reason that it will couple (tie) your business model to the framework being used, making testing and re-use in another application or environment more difficult. It is considered a good practice to keep your business model as decoupled as possible from the framework being used as well as from the rest of your application.

The common scenario is to have your actions performing a link, a glue or a bridge between the HTTP web request and the application business model. However, in some cases but not in all cases, the role of the action becomes predictable as it is just passing data back and forth to the business model. That's the reason, in my opinion, that frameworks like JSF want to make web development become desktop development by eliminating the need for actions and making use of event-based components instead.

Although Mentawai is an action-based framework (in contrast of a component-based or event-based framework), it allows the use of an action to be bypassed when desired. In our previous example we have coded the action HelloMenta.java and, because it was a simple example, we did not code any business logic outside the action. A more desirable approach would have been to have a separate class implementing the business model. I like to call it HelloService, but you can call it HelloFacade or HelloLogic or anything else if you prefer.

The code for our examples/helloworld/service/HelloService.java can look like this:


Note that it is not coupled to any Mentawai class or annotation. It is a simple POJO (Plain Old Java Object) that implements the logic of our application.

Now let's modify our action to make use of the HelloService class (our business model):


Notice how our action now creates an instance of HelloService to perform its duties. You can now say that the action is using the business model and not implementing it.

If you stop for some time to contemplate our code (yes, source code is a form of art!) you may come to the conclusion that the action here is not really necessary. It is just passing data back and forth to the business model. Let's try to eliminate our action and use the HelloService as a Mentawai Pojo Action. In the application manager, let's specify that our action will be the HelloService.class and not the HelloMenta.class anymore.


What happened here? Clearly the username was null when the method hello() from HelloService was called. But why? Probably because nobody called the method setUsername to set this variable before the method hello() was called. Remember that this was a duty of our action HelloMenta, which is not in the picture anymore. But don't dispair, Mentawai can easily solve this injection problem for you through its InjectionFilter. We will come back to the topic Filters later on, but for now it should be enough for you to know that a filter gets executed before the action so that you can perform any task before the action gets executed. Let's add a global filter that is applied to all actions in our application manager:


We have added two global filters. They are global because they are not associated with any action in particular, so they will be applied to all actions defined in the application manager. The job of the InjectionFilter is to inject all values from the action input inside the action (or POJO action). That's exactly what we want, in other words, we want the username value inside the action input to be injected inside the HelloService POJO action. The job of the OutjectionFilter is to take (or outject) all properties from the HelloService POJO action and to place them in the action output. That's exactly what we want, in other words, we want to take the "time" and "username" properties of HelloService and place them in the action output so that the tag mtw:out can display them in the JSP.

Redeploy your web application with the latest changes and double check that everything is working! Great! We have just used a POJO action with Mentawai! Before we conclude this chapter, let's make some improvements to the HelloService class.

You should know that the InjectionFilter is capable of injecting a value straight into a public or private instance variable, in other words, it does not need the setter method (setUsername) to perform the injection. So let's get rid of that method.


Another possibility is that you want to pass the action input values as parameters of the HelloService method hello(). Let's give it a try:


We will come back to all these neat features in later chapters, but for now you should realize that Mentawai offers you a great deal of flexibility to do things the way you want. You can download the complete war file for our final HelloWorld application by clicking here.

Conclusion

In this chapter you saw how to create a simple Mentawai web application and touched the surface of topics such as actions, input, output, consequence, results, filters, tags, html forms, etc. All these topics will be explored in greater details in later chapters.

You learned that an action (unless it is a POJO action, which can be a misleading name) should not implement the business model of an application. The action should provide the link between the HTTP web request and the business model of a web application.

You also learned about POJO actions, which are actions that are not coupled in any way to the Mentawai framework. The classic scenario is to make your business model become a POJO action so that it will handle the HTTP web requests with the help of filters and without any need for an action.

Before we start exploring some of the Mentawai main features, let's discuss in greater detail the Mentawai architecture so you can have a better foundation to move on.