Getting Started - Hello World

Mojave MVC is a framework for robust web application development in Java. You use the framework like you would use popular frameworks like Struts or Spring Web MVC. This short introduction assumes you have some familiarity with Java web development. Specifically, you should be familiar with servlets and JSP before continuing. If you are not familiar with these areas of Java development, please refer to documentation on that subject before continuing.

The Mojave MVC framework is built around the Front Controller pattern, and, not surprisingly, the Model-View-Controller pattern. All requests that come into the application arrive at a single servlet, and are processed by that servlet. In the Mojave MVC framework, that servlet is called org.mojavemvc.FrontController. The front controller receives a request, then decides where it needs to be routed. All requests are routed to controllers. A controller is simply a POJO that has been annotated with one of @StatelessController, @StatefulController, or @SingletonController. If you are familiar with EJB 3.1, you will see the similarities.

Once a request is routed to the correct controller, the next step is to invoke an action on that controller. An action is simply a public method in that controller class that has been annotated with @Action, or one of its variants. Actions return views, which are typically either renderable JSP pages, or streaming content, such as XML or JSON. But they can also be redirects, or carry a custom payload. Once the front controller receives the view from the invoked controller action, it dispatches to that view, and returns to the requestor.

So, a request made on the application is effectively an invocation of a method in a POJO. Request parameters are converted into Java types, and passed along as parameters to the controller action method.

It might be best at this point to illustrate this through use of the canonical Hello World example. To run this example, you'll need access to a servlet container, such as Apache Tomcat.

Our Hello World application will be deployed as a .war file into the servlet container. In our .war archive, we'll need to include a web.xml in the WEB-INF folder. The web.xml file will define one servlet, the Mojave MVC front controller:

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" 
xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
  http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
	
  <display-name>HelloWorld</display-name>
	
  <servlet>
    <servlet-name>FrontController</servlet-name>
    <servlet-class>org.mojavemvc.FrontController</servlet-class>
    <init-param>
      <param-name>controller-classes</param-name>
      <param-value>helloworld.controllers</param-value>
    </init-param>
    <init-param>
      <param-name>jsp-path</param-name>
      <param-value>/WEB-INF/jsp/</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>FrontController</servlet-name>
    <url-pattern>/serv/*</url-pattern>
  </servlet-mapping>
	
</web-app>

The web.xml file above defines one servlet, the Mojave MVC front controller, and several init parameters. This is the only XML-based configuration that is required. There are other init parameters, but these will suffice for now. The controller-classes parameter defines the namespace of the controller classes in the application. The jsp-path parameter defines the location of JSP pages. Note the URL pattern of the servlet mapping: you can replace "serv" with whatever you like, but the pattern must otherwise follow the same convention as above if you are using JSP, as we will in this example.

Next, we'll need to create a controller. Let's create a class called HelloWorld:

package helloworld.controllers;

import org.mojavemvc.annotations.Action;
import org.mojavemvc.annotations.Param;
import org.mojavemvc.annotations.ParamPath;
import org.mojavemvc.annotations.StatelessController;
import org.mojavemvc.views.JSP;
import org.mojavemvc.views.View;

@StatelessController
public class HelloWorld {

  @Action
  @ParamPath("to/:name")
  public View sayHello(@Param("name") String name) {
		
    return new JSP("hello").withAttribute("name", name);
  }
}

Finally, we'll need to create the hello.jsp file referred to in the HelloWorld class above:

<html>
  <body>
    <p>Hello <%=request.getAttribute("name") %>!</p>
  </body>
</html>

Be sure to place the hello.jsp file in the /WEB-INF/jsp folder in the .war archive, as that's what we specified in the web.xml servlet init param. Also, you'll need to place the Mojave MVC jar with all dependencies in the /WEB-INF/lib folder.

When we deploy this .war archive, called helloworld.war, for example, to a servlet container like Apache Tomcat, we can invoke the application with the following request:

In a browser, you should see the following response:

The request path following "serv/" should be of the form "[controller]/[action]". There are possible variations on this; for example, if you didn't specify an action, the framework would look for an annotated default action. Also, the controller and action annotations take optional String parameters that indicate their URL representation, as an alternative to using the class name or method signature. Please see other documentation for more information.

This concludes this short introduction to the Mojave MVC framework. More documentation will be provided over time. The framework is still in its infancy, but it already provides some powerful capabilites, such as dependency injection via Guice, and support for AOP through the use of custom interceptor classes. Please refer to the Javadocs for more information.