Madvoc is MVC framework that prefers convention over configuration what removes the need for external configurations. The story behind Madvoc is not new: it is similar to VRaptor and WebWork2/Struts2. Madvoc controller on each request creates a new instance of action, invokes it and renders the view indicated by action result. Madvoc actions are simple POJO classes. Each action can be intercepted by one or more interceptors. There is only one default interceptor, that injects and outjects parameters and attributes to and from the action before and after action execution. This is default behavior which will be explained bellow.

It is important to separate the core Madvoc behaviour from its configuration! Core functionality is the concept itself how Madvoc works, and it is something that is less changeble, but still configurable. On the other hand, default configuration in Madvoc is very changeble, so every user can define its own way how to configure Madvoc: using annotations, XML files, plain Java, or whatever suits him the best.

On each request, Madvoc creates one action object and invokes it. An action encapsulates the request. In Madvoc actions are defined by:

• action path - actual http request that will invoke the action,
• action class - class that will handle the request,
• action method - method that will be invoked on request handling,
• list of interceptors - that will be invoked 'arround' the action, and
• action result of some type - that will be rendered after the action.

Actions are good old POJOs. If default interceptors are used (and there is no reason why not), actions will usually contain some annotations. Here is a typical action:

@MadvocAction
@InterceptedBy(MyInterceptorStack.class)
public class HelloAction {

	@In
	private String name;
	public void setName(String name) {
		this.name = name + "xxx";
	}

	@In
	MutableInteger data;

	@Out
	String retv;

	public String world() {
		System.out.println(">HelloAction.world " + name + data);
		retv = " and Universe";
		return "ok";
	}

The name of all actions classes must end with 'Action' and must be annotated as @MadvocAction. One action class may contain one or more action handlers - simple public methods within the action class. They might be annotated with @Action annotation. If there is at least one annotated method, then only annotated methods are action handlers. Otherwise, if there is no annotated method, then all public methods are considered as action handlers. By Madvoc convention, that defines single action request: action class name + action handler (i.e. method) name. In above example, method world()is mapped to action request: '/hello.world.html' (extension is configurable).

Similarly, destination to which results are mapped depends also on string value of action handler result. In above example there is only one destination, and by Madvoc convention it is: '/hello.world.ok.jsp'.

For convenience, some action handlers with common names do not use method name in action path: invoke(), run(), execute(). These action handlers names will not exists in the action path!

As expected, parameters are injected and outjected to and from action. Annotation @In marks injected class attributes. Annotation @Out marks class attributes which values will be outjected. By default, name of injecting values should match target class attribute names, although this can be easily within the annotation. Similarly, it is possible to choose where injected value is read from: request, response, session, application scope. The same applies for the outjection, too. There is a large variety of ways how input parameters may be injected in the action class.

Actions may be intercepted. As said, by default, two interceptors are active: one that renders the results, and the other that prepares action and performs injection and outjection. Interceptors may be applied to action class, but also to action handlers (i.e. methods). Default interceptors don't have to be stated, so when adding new interceptors, it is possible to simply add all default ones, at once. Interceptors are singletons for one Madvoc. Since interceptors are invoked on each action, due to performance, parameters are not dynamically injected into it.

Naming convention is nice, but sometimes users may want to override it. Of course, it is very easy to do, within annotations:

@MadvocAction("/foo/boo")
public class CustomAction {

	@In("ppp")
	List<Person> plist;

	@In("ppp")
	Person[] parray;

	@In("ppp")
	Map pmap;

	@Action("/foo/hello")
	public String execute() {	// mapped to /foo/hello (no default extension!)
		return "ok";		// mapped to /foo/hello.ok.jsp
	}

	@Action("zoo/again.exec")
	public void again() {		// mapped to /foo/boo.zoo/again.exec.html
		System.out.println("CustomAction.again");		// mapped to /foo/boo.zoo/again.exec.jsp
	}
	
	@Action("/foo/boo-aa/temp.bb")
	public void temp() {		// mapped to '/foo/boo-aa/temp.bb'
	}
	

Results may be of various types. By default, there are dispatching and forward types, but it is easy to add more types. For example, it is possible to add custom result type for rendering FreeMarker or Velocity templates, or to generate PDF reports.

	public String fff() {
		return "forward:/hello.again.html";
	}

It is easy:

	@In(scope=ScopeType.CONTEXT)
	HttpServletResponse servletResponse;

	public String again() throws IOException {	// mapped to /hello.again.html
		servletResponse.getWriter().print("Direct stream output...");
		return "none:";
	}

This is also an example how references to HTTP classes can be injected in the action, by using specific scope type.

Uploaded files are injected as input parameters:

@MadvocAction
public class UploadAction {

	@In
	UploadFormBean foo;

	public String exec() {
		System.out.println(foo);
		return "ok";
	}
}		

Madvoc dispatcher is registered as filter in 'web.xml'. By default it uses automatic mode that scans the class path for action classes, interceptors etc. It is possible to fine tune this search, if needed. Moreover, Madvoc will search also for MadvocConfig instances, too. These are the classes that can add add some explicit configurations. Some users like to put one configuration class in each actions folder and to manually register all actions, if they do not use automatic registration.

Madvoc can be easily integrated with Petite. Such integration makes development power and yet simple.