Baritus Web Development Framework.

The ability to work with POJO's (Plain Old Java Objects) is one of the primary focusses of this framework.

The objects that you want to have populated from the HTTP request do not need to extend any base class or implement any interface. This way, you can populate classes from, for example, your domain model without the duplication of code you see often in Java web applications. And as you can nest objects as well, you could even populate several objects in one pass.

Type conversion and property navigation is done automatically, so there's is no need for configuration. Just provide a bean to populate and Baritus will do the rest. Population and is flexible and pluggable on several levels of abstraction. The default population delegate uses Ognl to resolve properties and set values.

If there are any errors during population, those errors are stored in the formBeanContext for later use. The original input values are stored in the formBeanContext as well, in order to be able to override the property value with the input value if a population or validation error occured.

As the controls are responsible for creating instances of the objects that should be populated (usually called form beans), no extra configuration is needed. Furthermore, you can do very interesting things with those objects before actually having them populated by Baritus. For instance, if you are working with a ORM tool (like Hibernate), you could load your persistent object, let Baritus populate it, and persist the changed object in the command method (perform) of your control. Tricks like these can be serious code savers, compared to where you work with a seperate domain- and form object and where you have to sync those two yourself.

As by default the formBeanContext is reused within one request, you have the option of reusing the allready populated form bean as well. And by setting property populateAndValidate from formBeanContext to false, you could even skip population/ validation in the current and laters steps in the command chain within one request.

Besides populating objects with HTTP request parameters, you can optionally have your objects populated with Maverick configuration parameters, request attributes and session attributes. It's all configurable for each instance of a control, or even for each request if you like.

Type conversion during population is in fact your first validation step. For further validation, like checking if a required property was set, or checking that a certain date is actually after the date of today, Baritus provides a flexible and pluggable validation mechanism.

De default provided validation mechanism is based on validation with Java objects that do the validation, and that are registered in the controls that want to use them. The default mechanism is probably powerfull enough for everything you want to do. It is possible however, to plug in one or more additional mechanisms. This way, you could use Commons Validator, FormProc, or possibly another validation framework with Baritus (though at this time no implementations are available).

The objects that do the validation come in two main forms:

Exactely when validators are used can be tuned with ValidationActivationRules. Validation activation rules can be registered on control (/form bean) level. These rules are checked before any validation is done. If one of the rules fails, no validation is done at all. If the control level rules allow validation, the FieldValidators are executed. Instances of FieldValidator can hold a reference to one rule. When a FieldValidator has a rule, this rule is used to check whether the field validator should be executed. If you want to stack rules for a field, you can put them in an instance of nl.openedge.baritus.validation.impl.NestedValidationActivationRule, and register this instance with the field validator. If all field validators succeeded, the form validators are executed, possibly dependent on a registered validation rule. If property doFormValidationIfFieldValidationFailed in ExecutionParams is true, form validation will allways be executed, whether the field validation succeeded or not.

If all population actions and validation actions have succeeded succesfully, the command method (perform) will be executed. If one of the actions failed, the command method will not be executed and the view that results from getErrorView (error by default) will be used. If property doPerformIfPopulationFailed from ExectuionParams is set to true (default is false), the command method is execution even if the population/ validation failed.

Interceptors provide a means to encapsulate cross-cutting code that is executed on pre-defined points in the line of execution.

Interceptors can be used to 'enrich' de model (formBeanContext), eg. load data, save session attributes, etc. Furthermore, as interceptors can throw 'FlowExceptions', interceptors can have an effect on the flow. They can overrule the command (perform method) and redirect to another view or do an arbitrairy redirect right away. This behaviour can be used to work with multi page forms coupled to one command or for instance implementing a generic 'system error' type of view.

This sequence diagram displays the commons flow of execution with Baritus.

The minimal thing you have to do to use Baritus - besides using Maverick -, is to extend from nl.openedge.baritus.FormBeanCtrl and implement the two abstract methods makeFormBean and perform.

Let's start from the begining and work our way up to a working example.

You should know how to work with Maverick. If you are not aquainted with Maverick yet, please read the Maverick tutorial first. After you know how to work with Maverick, you should create a web application project in your favorite IDE, or you can download a stub project using Maverick, Baritus and Velocity here. The stub project is has a Maven project descriptor in order to assist you with getting the dependencies you need fast. Read more about Apache Maven here.

We begin by creating a command in the Maverick configuration. A command in Maverick is the combination of a url-mapping (name), a controller class and one or more views.

<command name="example">
	<controller class="nl.openedge.examples.baritus.ExampleCtrl" />
	<view name="success" path="/example1.vm"/>
	<view name="error" path="/example1.vm"/>
</command>

Next, we create a controller class that extends from nl.openedge.baritus.FormBeanCtrl and a bean that we will use for population.

package nl.openedge.examples.baritus;

import nl.openedge.baritus.FormBeanContext;
import nl.openedge.baritus.FormBeanCtrl;
import org.infohazard.maverick.flow.ControllerContext;

public class ExampleCtrl extends FormBeanCtrl
{

	protected String perform(
		FormBeanContext formBeanContext, 
		ControllerContext cctx)
		throws Exception
	{

		ExampleBean bean = (ExampleBean)formBeanContext.getBean();
		
		//... logic comes here...
		
		return "success";
	}

	protected Object makeFormBean(
		FormBeanContext formBeanContext, 
		ControllerContext cctx)
	{
		// create a new instance of the bean we want to populate
		return new ExampleBean();
	}
}

package nl.openedge.examples.baritus;

public class ExampleBean
{
	private Integer myInteger;
	
	public Integer getMyInteger()
	{
		return myInteger;
	}
	
	public void setMyInteger(Integer integer)
	{
		myInteger = integer;
	}
}

And finally, we create a Velocity template. If you are new to Velocity, you can check out their website here. Note that you can use whatever view type you like. We from OpenEdge mainly use Velocity, but you could use JSP's, XML/XSLT, webmacro, freemarker etc. just the same.

Note that we use the default Maverick configuration, which saves the current instance of FormBeanContext as request attribute 'model'.

<HTML>
<head>
	<title>First Baritus VM</title>
</head>
<body>
	<form action="${request.contextPath}/example.m" method="POST">
	
		Please give an integer:
		<input type="text" name="myInteger" size="20"
			value="$!{model.bean.myInteger}"/>
			
		<br><br>
		<input type="submit" value="save">
		
	</form>
</body>
</HTML>

Actually, the above code only works when population and validation succeeded. If it did not, the property myInteger was probably not set, and thus this example displays the old (null) value in case of an error. If population or validation errors occure, the user input is saved in a special map property 'overrideFields' in the FormBeanContext.

Now, instead of using override fields directely, we can use one of the utility methods that are available in FormBeanContext for displaying properties. In this case we use method 'displayProperty(String)', with the name of the form bean property to display as its parameter.

Method 'displayProperty' will not only lookup if an override value should be displayed, but also formats the output according to the current locale. For other formats, you can use 'displayProperty(propertyName, format)', but more about formatting later on. Here's our new version.

<HTML>
<head>
	<title>First Baritus VM</title>
</head>
<body>
	<form action="${request.contextPath}/example.m" method="POST">
	
		Please give an integer:
		<input type="text" name="myInteger" size="20"
			value="$!{model.displayProperty('myInteger')}"/>
			
		<br><br>
		<input type="submit" value="save">
		
	</form>
</body>
</HTML>

To further fine tune our displaying we will create a Velocity macro.

#macro( forminput $fieldname $type $size )

<input type="${type}" name="${fieldname}" size="${size}" 
	#if( $model.errors.get($fieldname) ) 
		class="fielderror" 
	#else 
		class="field" 
	#end
	value="$!{model.displayProperty($fieldname)}">
		
#end

And a cascading stylesheet definition file (we'll call it style.css here).

.field {
	color: black;
	background-color: white;
}
.fielderror {
	color: white;
	background-color: red;
}
.error {
	color: red;
}

Now we change our Velcocity template, that now also includes the displaying of a list of error messages. Note that you probably create this only once, like in a footer (check out the Maverick transform options).

<HTML>
<head>
	<title>First Baritus VM</title>
	<link rel="stylesheet" type="text/css" href="${request.contextPath}/style.css">
</head>
<body>
	<form action="${request.contextPath}/example.m" method="POST">
	
		Please give an integer:
		#forminput( "myInteger" "text" 20 )
			
		<br><br>
		<input type="submit" value="save">
		
	</form>
	
	#foreach( $err in $model.errors )
		<span class="error">$!{err}</span><br>
	#end
	
</body>
</HTML>

That's all there is to it. You should experiment yourself now. Try adding properties of different types and try playing around with nested objects as well.

Be aware that nested objects that are null references will NOT get populated, so be sure to provide instances of all the objects that you want to have populated. The only execption to this rule is working with arrays.

In order to help you debug your web applications more easily, the following loggers are available. As a logging API Baritus uses Jakarta Commons Logging, so you may use any of the logging mechanisms that are supported by Commons Logging.

The two loggers currently in use are named 'nl.openedge.baritus.population' and 'nl.openedge.baritus.formatting' and can be found as constants in Interface nl.openedge.baritus.LogConstants.

To configure with Log4J, for instance, you can add the following lines to your Log4J configuration file:

log4j.logger.nl.openedge.baritus.population=DEBUG
log4j.logger.nl.openedge.baritus.formatting=DEBUG

Currently, only DEBUG gives you run time logging. And, as it is quite a lot, you probably do not want to turn it on in production systems.

ExecutionParams can used to tune the flow of execution. The execution params can be tuned just for the local request, or for all subsequent requests handled by the current controller.

If you want to tune just for the current request, you can get a working copy by calling 'getExecutionParams(cctx);', where cctx is the instance of the ControllerContext. If you pass null instead of cctx, you will allways get a new copy, otherwise you will get the save params for the current request. So, with chained controlls, the excecution params will be reused for the whole server side processing. Thus, if control A chains control B (e.g. A has view '/to-b.m'), and A changes the execution params, these changed params will be used when executing control B this request.

If you want to fix/ change the execution parameters for all subsequent requests, you have to call fixExecutionParams(params) in your control. For example:

public void init(Element controllerNode) throws ConfigException
{			
  ExecutionParams params = getExecutionParams(null);
  params.setIncludeRequestAttributes(true);
  fixExecutionParams(params);
}

For additional fine grained control, you can decide to override method getExectionParams instead of using the copy and the fix method.

In this section, we will look at the FormBeanContext in more detail.

The FormBeanContext is your interface between controllers and views and between controllers within the same request. Also, FormBeanContext has the utility methods that helps you to properly display values of the form bean. Furthermore, FormBeanContext keeps references to the form bean, the current (request scoped) locale and, in case errors occured during population/ validation, to error messages and the original input values. And lastely, FormBeanContext acts as a Map/ attribute decorator that you can use for request scoped atrributes you do not want to include in the population/ validation process.

When building web applications with Java, one of the commons things you want to do is to translate user input, i.e. request parameters, into server side objects, like objects of your domain model. Population is the process of matching request parameters (and optionally configuration parameters, session attributes and request attributes) with properties of the form bean, converting the request parameters to the target property type and setting the converted values on the form bean.

By default, Ognl is used to get and set properties. It is possible to use a custom populator delegate instead of the default delegate 'nl.openedge.baritus.population.OgnlFieldPopulator'. See chapter six for the details, and this BeanUtils populator as an example.

One of the tasks to be done when populating a java bean from an HTTP request is the conversion of string parameters to Java types (Integers, Dates, etc.). Converters are used for this purpose. Converters are globally registered with the ConverterRegistry.

There are two types of converters, normal converters and locale-sensitive converters. Locale-sensitive converters override normal converters that are registered for the same type. Thus, if both a normal and a locale-sensitive converter are registered for type java.util.Date, the locale-sensitive converter will be used.

Allthough the ConverterRegistry has sensible defaults, you can register other Converters like this:

ConverterRegistry reg = ConverterRegistry.getInstance();
reg.register(new FallbackDateConverter(), Date.class);
reg.register(new FallbackDateConverter(), java.sql.Date.class);
reg.register(new FallbackDateConverter(), Timestamp.class);

Converters must implement either org.apache.commons.beanutils.Converter or org.apache.commons.beanutils.locale.LocaleConverter.

ConverterRegistry is a global registry. Hence, registered converters (and formatters) are shared amongst all controllers.

Besides converting string values to Java types, you often want to format values. Two mechanisms are available for formatting.

The algoritm to find a formatter is: first see if there's a formatter registered on fieldName (e.g. 'myProperty'). If not found, see if there's a formatter registered with the provided pattern (e.g. '*REVERSE). If not found, see if the converter that is registered for the property type and (the optional) locale, implements Formatter. If so, use the converter for formatting. If not found, just convert to a plain string (using ConvertUtils).

The population process can be customized to suit your requirements. By default, class nl.openedge.baritus.population.DefaultFieldPopulator is used for population. DefaultFieldPopulator uses introspection to set the properties. You can however, create custom populators by creating implementations of nl.openedge.baritus.population.FieldPopulator. nl.openedge.baritus.population.AbstractFieldPopulator can be used as a base class. You can register custom populators in two ways:

Custom populators are registered with a controller. Hence, registering a custom populator for controller A does not have effect on the population for controller B.

The first pass in the population process is the conversion of request parameters etc. to Java objects and populating the provided form bean with those objects. If this is successful, you know that inputs for integers, dates, etc. conform to a valid form (e.g. 'foo' is not a valid integer, but '12' is).

Next, you might want to check if, for instance, a provided parameter not only is a valid integer, but is also greater than say 10. Or that a parameter not only is a valid date, but that this date also is after today. If we talk about validation, we mean this kind of checks.

Validation can be performed on two levels: field and form level. Field level validation is related to one input field (e.g. a request parameter) at a time. Form level validation is executed regardles the provided parameters.

Furthermore, whether a validation action is executed can be made dependend of a certain state (like the value a parameter) using nl.openedge.baritus.validation.ValidationActivationRules.

Let us start with an example that displays some usages of the validation mechanism of Baritus. In the following example, we want to validate that not only myInteger is a valid integer, but also that the integer allways has a value that is greater than ten.

public class FooForm
{
	private Integer myInteger;
	
	public Integer getMyInteger() { return myInteger; }
	public void setMyInteger(Integer i) { myInteger = i; }
}

The validator:

public class BarValidator extends AbstractFieldValidator
{
	public boolean isValid(
		ControllerContext cctx, 
		FormBeanContext formBeanContext, 
		String fieldName, 
		Object value)
	{
		// note that type conversion is allready done by the population process
		Integer val = (Integer)value; 
		// the value can still be null though
		boolean valid = (val != null && val.intValue() > 10); 
		
		if(!valid)
		{
			String errorMessage = "input " + value + 
				" is not valid; please provide a number larger than 10";
			formBeanContext.setError(fieldName, errorMessage);
		}
		
		return valid;
	}

}

Now, register it with your control:

public class MyCtrl extends FormBeanCtrl
{
	...
	
	public void init(Element controllerNode) throws ConfigException
	{
		addValidator("myInteger", new BarValidator());
		...
	}
	
	...
}

And a crude example of how you can use it with a velocity template:

<input type="text" name="myInteger"
	#if( $model.errors.get('myInteger') ) class="fielderror" #else class="field" #end
	value="$!{model.displayProperty('myInteger')}">

<br>
#if( $model.errors.get('myInteger')  )  
	<span class="error"> ${model.errors.get('myInteger') } </span>
#end

When using mapped or indexed properties, you have two options of registering field validators, on target name and/ or on flat name. Let's illustratie this by example:

public class FormWithMap
{
	private Map foo = new HashMap();
	
	public Integer getfoo() { return foo; }
	public void setfoo(Map m) { foo = m; }
}

Not only can we register validators with the whole target name, including the keys or indexes like this:

...
	addValidator("foo['bar']", myValidator);
	addValidator("foo['someOtherKey']", myOtherValidator);
...

But in case the validator should be executed for all keys (or indexes), the 'flat name' (name without markup for map/ index navigation) as well like:

...
	addValidator("foo", myValidatorForAllKeys);
...

Whether validators are actually used a given situation can be directed through the use of ValidationActivationRules (nl.openedge.baritus.validation.ValidationActivationRule).

For example:

public class MyValidationRule implements ValidationActivationRule
{
	public boolean allowValidation(
		ControllerContext cctx,
		FormBeanContext formBeanContext)
	{
		return "true".equals(cctx.getRequest().getParameter("validate"));
	}
}

FieldValidator validator = new RequiredFieldValidator();
validator.setValidationRule(new MyValidationRule());
addValidator("myField", validator);

In the above example the validator will only be called when request parameter 'validate' is provided and has value 'true'.

You can register only one validation activation rule with a validator at a time. It is not difficult though, to stack validator activation rules, for example by using nl.openedge.baritus.validation.impl.NestedValidationActivationRule.

By default, if population failed and/ or if you registered validators that failed, the 'peform' method of your controller will not be called. Instead, the errors and override fields are saved, and the error page is shown.

Earlier, you have seen that the actual firing of Validators can be made conditional by registering ValidatorActivationRules with your validators. This works well for higher level validation that is dependent of e.g. the value of one of the other request parameters.

There are two ways of escaping the default mechanism of not performing the controller command method. The first way is to skip population and validation all together. In order to achieve this, you can set property 'populateAndValidate' of the ExecutionParams to false. The second way is to set property 'doPerformIfPopulationFailed' to true (false by default). In this case, population and validation is performed as usually, but now the perform method is allways executed, regardless of the population/ validation outcome. This option should be used with care.

Package nl.openedge.baritus.validation.impl is reserved for implementations of Validators.

Interceptors provide a means to encapsulate cross-cutting code that is executed on pre-defined points in the line of execution. Interceptors are classes that implement one or more interfaces from the package 'nl.openedge.baritus.interceptors'.

Interceptors can be used to decorate the normal execution. Also, by throwing FlowExceptions, interceptors can alter the flow of execution. An interceptor can throw a FlowException if it wants Baritus to stop normal processing and go to the given declared view (using ReturnNowFlowException) such as 'error', or dispatch to an arbitrary - non declared - URL (using DispatchNowFlowException) location.

The following interceptors are available.

An interceptor can alter the line of execution by thowing a FlowException. An example of when to do this is: if you expect a session variable to be set, but there is none, you might want to redirect to a search page or an error page. Another example: on certain non handled exceptions that are thrown in the perform method, you might want to redirect to a specific error page that is different from the error page that is shown when population errors occured.

There are two types of FlowExceptions that can be thrown by interceptors.

Finally, with FlowException property 'executeOtherInterceptors' you can set on the exception that indicates whether (some of the) other interceptors should be executed. FlowExceptions thrown by these interceptors are ignored.

Here is an example of how to use interceptors. In part of our imaginary application, we want to be sure that an object was saved in the session, and after we checked it is, we want to set that object as one of our form bean properties. If our object is not found however, we want to cancel the normal Baritus behaviour and do a redirect (or actually dispatch) to another location right away. Because we set that object in the form bean just before population takes place (but after the makeFormBean method was called), it can be populated by the request paremeters etc. as well.

First, there is our Interceptor.

public class LoadFooFromSessionInterceptor implements BeforePopulationInterceptor {

    /**
     * Before population takes place, we get our Foo object from the session, check
     * it's actually there (is not null) and set it in our form, so that it can be
     * populated as well.
     */
    public void doBeforePopulation(
        ControllerContext cctx, FormBeanContext formBeanContext)
        throws ServletException, DispatchNowFlowException, ReturnNowFlowException 
    {
        HttpServletRequest request = cctx.getRequest();
        HttpSession session = request.getSession();
        Foo ourFoo = (Foo) session.getAttribute(Constants.SESSION_KEY_FOO_OBJECT);

        if (ourFoo == null) 
        { // ourFoo does not exist in the session... redirect to 'home.m'
            throw new DispatchNowFlowException("home.m");
        } 
        else 
        { //  we're ok, set in form and exit method normally
            FooBarForm form = (FooBarForm) formBeanContext.getBean();
            form.setFoo(ourFoo);
        }
    }
}

Then, we should register the interceptor in the controllers we want to use it.

    public void init(Element controllerNode) throws ConfigException 
    {
        addInterceptor(new LoadFooFromSessionInterceptor());
    }

Baritus will now call this interceptor each time this control is used right after calling makeFormBean and just before population and validation takes place.

Just like you can do with validators, you can stack interceptors as well.

    public void init(Element controllerNode) throws ConfigException 
    {
        addInterceptor(new FooInterceptor());
        addInterceptor(new BarInterceptor());
        addInterceptor(new MooInterceptor());
    }

In the above example, all interceptors can be of the same type(s), and will be called in order of registration. Thus, FooInterceptor is called first, BarInterceptor after that and MooInterceptor is called last.