Handling a request for interactivity

Initially there will be no items in the list so the page provides the form submission to add an item.

Looking back at the template the action url of the form is actually #{addItem} . On submitting the form, OfficeFloor will invoke the below method via naming convention (same name).

	public void addItem(Item item) {
		this.items.add(item);
	}

Notice that the method has a single parameter Item. The Item class is annotated as follows which identifies to WoOF that the object should be loaded with the corresponding HTTP parameter values.

@HttpParameters
public class Item implements Serializable {

	private String name;

	private String description;

	public String getName() {
		return this.name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getDescription() {
		return this.description;
	}

	public void setDescription(String description) {
		this.description = description;
	}
}

The following steps therefore occur on submitting the form:

1. an Item object is instantiated from its default constructor
2. form submission parameters are reflectively loaded onto the Item object by matching HTTP parameter name to setter method name, e.g. description to setDescription(String description)
3. the Item object is passed to the invocation of the addItem method as the parameter value

This relieves writing plumbing code and allows focus on handling the values submitted by the user (in this case adding the item to the list). It also makes for cleaner and easier to unit test code.

Once the addItem method returns, WoOF will by default re-render the template back to the user. It is possible to direct flow to other templates however this is beyond the scope of this tutorial.

Along with adding an item to the list the template also provides the ability to clear the list of items. Clicking on the #{clear} link invokes the following method.

	public void clear() {
		this.items.clear();
	}

Again by default, the template will be re-rendered once the clear method returns.

OfficeFloor achieves this simple interactive programming model by subsituting into the rendered page a unique url which it can map back to the corresponding method. The method is matched by its name and is free to have any parameters it requires (enabled by OfficeFloor's dependency injection). For example in more complex applications the handling methods may include a parameter for a DataSource or EntityManager to enable database interaction rather than just storing content into the object. This however is beyond the scope of this tutorial.

Controlling section rendering

Now that the user is able to add and clear items, control is necessary to only render certain parts of the template.

In this case:

• if there are items in the list, display them in a table
• if there are no items in the list, provide a message indicating no items

To provide control over the sections rendered in the page, the following interface is created.

	@FlowInterface
	public static interface PageFlows {

		void getNoItems();

		void endListItems();
	}

The interface is annotated to tell WoOF it provides flow links. The methods of the interface correspond by name to the template sections and the template object's methods.

The template logic for controlling the rendering of sections is as follows:

	public void getListItems(PageFlows flows) {
		if (this.items.size() == 0) {
			flows.getNoItems(); // skip to getNoItems
		}
	}

	public void getNoItems(PageFlows flows) {
		if (this.items.size() > 0) {
			flows.endListItems(); // skip to endListItems
		}
	}

For the above methods, WoOF will invoke them before rendering the corresponding template sections. On invoking the method, WoOF will generate an object implementing the PageFlows interface that will allow changing the next section to be rendered. Should no method be invoked then the next section is rendered as per the template. Should a method be invoked then the corresponding section by the interface method name becomes the next section to be rendered. In this case:

• For getListItems :
  • An empty items list will have rendering skip to the getNoItems method along with its corresponding section (skipping the rending of the table).
  • With items in the list, the flow interface method is not invoked so rendering will carry on to the next section (i.e. listItems template section).
• For getNoItems :
  • Having items in the list will have rendering skip to the endListItems template section (skipping the rendering of the message).
  • An empty items list will cause the flow interface method to not be invoked so rendering will carry on to the next section (i.e. noItems template section).

Controlling rendering of the template like this means that the code is not dependent on any framework API's and subsequently allows easier unit testing (via mocking the interface).

This style of controlling the rendering works well with OfficeFloor's dependency injection. As the methods match based on naming and not on method signature (i.e. parameters are ignored), it allows for the interface and template logic class methods to have different parameter lists. The result is that dependencies are used only as necessary and also makes for adding/removing dependencies easier. For example, the following shows the changes necessary to make a DataSource available:

		public void getNoItems(PageFlows flows, DataSource dataSource) {
			// code requiring DataSource
		}

OfficeFloor will happily inject the additional DataSource dependency on invoking the method. The call from getListItems will not need to be aware that the implementing method has had a change in dependencies - especially if later it might change again to call a web service.

This ability to dependency inject into methods is only the start of the functionality contained within OfficeFloor, as this starts to touch on the Job Based Architecture at it's heart.