Parancoe Controller Tutorial

In this tutorial we will cover the necessary steps to create a Controller in the Parancoe Web framework.

Introduction

First of all you have to know that Parancoe uses the Spring MVC framework.

In Spring MVC all HTTP requests are routed to the DispatcherServlet. This particular servlet, by examining the url, decides which Controller can manipulate the request.

Controllers are a core part of Spring MVC and the Parancoe Web Framework tries to ease the process of defining and mapping those objects to urls.

The steps necessary to define and use a Controller are:

Let’s see those steps through an example. Suppose that your application needs to manage a sort of administration control. The easy way to develop such a component is to write an object that manages all the request coming from /admin/*.html.

Write the controller class

Writing the controller class is simple: you have to extend from BaseMultiActionController in this way:


package org.parancoe.basicWebApp.controllers;
public abstract class AdminController 
           extends BaseMultiActionController {
    ...
}

BaseMultiActionController extends from Spring MultiActionController and adds some facilities for logging and error handling. If you are not familiar with MultiActionController, Spring site has a well documented tutorial on it here .

Annotate the controller class with url mappings

The problem now is to link our controller to urls like /admin/*.html. To do so we can use an annotation directly in the controller class:

package org.parancoe.basicWebApp.controllers;

@UrlMapping("/admin/*.html")
public abstract class AdminController 
           extends BaseMultiActionController {
    ...
}

In this way all urls matching /admin/*.html will be routed to AdminController.

The annotations defined for url mapping are three:
  • @UrlMapping: receives a string containing the url definition;
  • @MultiUrlMapping: allows to define multiple mappings for the same controller. For example @MultiUrlMapping("/admin/*.html", "/admin/*.jsp");
  • @DefaultUrlMapping: sets the default Parancoe convention on url mappings.

The default convention used in @DefaultUrlMapping works in this way. If you define a controller with class name AdminController and if you annotate it with @DefaultUrlMapping, Parancoe will associate it with the url /admin/*.html.

In the same way if you define a controller called MyFantasticApplicationAdminController it would be associated with urls like /my/fantastic/application/admin/*.html.

If you don’t specify any url in @UrlMapping, Parancoe will default the url in the same way of @DefaultUrlMapping. So the behaviour of this two annotations is the same: @UrlMapping("") == @DefaultUrlMapping.

Autodiscovery of controllers

Now that you have defined and annotated your controller it’s time to register it in Spring Context. This task can be accomplished in two ways. The first one is the Spring normal way: you define your controller in parancoe-sevlet.xml like this:


<bean id="adminController" 
      class="org.parancoe.basicWebApp.controllers.AdminController" 
      parent="abstractController"/>

The other way is to let Parancoe find and define controllers for you. To do so you need to write in your parancoe-servlet.xml:


<parancoe-web:define-controllers 
    basePackage="org.parancoe.basicWebApp.controllers" 
    parent="abstractController"/>
This tag has two attribute:
  • basePackage: this is the package in which Parancoe searches your controllers;
  • parent: is the abstract controller from which your controller derives. This attribute is not mandatory, the default behavior is to use abstractController, provided by the framework.

If you use this second way, it would be easy to add another controller to your web application: simply put it in basePackage, and Parancoe will discover and configure it for you.

If you want to use this second way, remember to add this namespace to your parancoe-servlet.xml:

xmlns:parancoe-web="http://www.parancoe.org/schema/parancoe-web" 
xsi:schemaLocation="http://www.parancoe.org/schema/parancoe-web 
   http://www.parancoe.org/schema/parancoe-web.xsd" 

...to be continued.

Posted by Andrea Nasato on Tuesday, October 02, 2007