Tutorial: Part One

This tutorial is available to give a quick glimpse of how to use Waffle. It touches on each of the main components that make up Waffle.

Controller

The term Controller is probably familiar to those who have worked with other web frameworks. An Controller in Waffle can be any java object (i.e. POJO). However, in order for a POJO to be considered an Controller in Waffle it needs to be registered with the Registrar. The Registrar is a simple class that your application must implement. The Registrar provides a few methods that allows you to register your pojo's as Controllers. For complete details on the Registrar have a look at the Registrar section.

Now we will write a very simple class to use as an Controller. The class below is really nothing more than a simple bean type of object.

Registrar

As stated earlier, a Controller is not active in Waffle until it has been registered with the Registrar. So now we will create a simple Registrar class and register the Automobile class with it. The MyRegistrar class below defines the method "session" and within that method it calls register("automobile", Automobile.class);, which registers our Automobile class as an Controller under the name "automobile". Registration is not limited to Controllers because any component, service, factory, etc... can be registered. Detailed examples of this will be discussed later.

web.xml

While Waffle does not require any proprietary XML configuration files we still must create a web.xml. The web.xml example below has four points worth mentioning.

  1. org.codehaus.waffle.registrar.Registrar is the key used to register your applications custom Registrar. The key is the fully qualified name of the basic Registrar interface.
  2. org.codehaus.waffle.context.pico.PicoWaffleContextListener needs to be registered as a listener so that Waffle can be notified of context level (application, session) events.
  3. org.codehaus.waffle.context.WaffleRequestFilter this is the Filter Waffle uses to handle request level events. This is superior to a RequestAttributeListeners implementation because we can ensure a request level container will only be created when appropriate (i.e. not when images or cascading style sheets are requested).
  4. org.codehaus.waffle.servlet.WaffleServlet is Waffle's front controller for handling requests.

View

We will create a very simple view to display the content of the Controller. The following example uses a JSP and simply displays the values of the Controller.

automobile.jsp

Application structure (WAR File)

An application built with Waffle is similar to most other Java web based applications. The following provides an overview of how you might layout the code for this tutorial:

NOTE
The jars jstl.jar and standard.jar are only required because this tutorial demonstrates the use of JSP's. If you plan on using FreeMarker or Velocity you'll need to include the jar files that each of those projects may require.

Running the application

Now the application can be deployed to a Servlet container (e.g., Tomcat, Jetty). So when we run the application and direct the browser to http://localhost:8080/hello/automobile.waffle we see the following:

When Waffle's front controller, WaffleServlet, handled this request it first located the "automobile" Controller, which we registered earlier to the session.

We can also exercise the ability to bind values from the request directly onto the Controller. If we append the value "?model=ranger" to the original url we will now have: http://localhost:8080/hello/automobile.waffle?model=ranger. Notice that the url and the value of the Model field has been updated.

More to see

This has only been an introduction to Waffle and it provides a good starting point to understanding how it works. Continue on to Tutorial: Part two to see how ControllerMethods can be dynamically invoked on Controllers.