POJO State

Some years ago I was working on an application where I wanted to display the internal state of the application in an HTML interface. Thinks like how long has it been up, what it is doing now and so forth. Typicaly this would be solved by coding a Servlet (or JSP) visualizing the underlying object model as required.

Three thinks were worring me though. First there was that wish of mine to be able to change the object model without having to edit the Servlet or HTML code. Second, I didn't want anyhting fancy, showing all data in a tabular format would be acceptable. Third, I had the feeling that observing my object model was part of a bigger use case, the one which you can look into an object, determine which are its state-representative methods and display them in a user friendly manner. All this lead to creation of this library.

If you think about Model-View-Controller (MVC) paradigm, the Model is your object model, the View is this library and the Controller is your integration code.
POJO State is a generic library which can decorate any Java object with user friendly information about its state.
Imagine a Java Bean where all or some getter methods reveal information about its state. This library will provide you with the means to display their content in XML, HTML or simple TEXT tabular format. Further on, it will provide you with means to replace the method names with user friendly names and allow you to add description to them. It will also format the actual method values in their proper human readble format (dates, time, numbers, price info and such). Finally, if already avaialable functionality is not enough one can utilize the API to extend it in any required direction.

Typical usage scenario is:

where:

• Decorator is decorating a POJO with a State
• Selector is used to decide which methods from the POJO class are to be included in the State.
  It also decide on what the formating of their values.
• Property represent a single method from the POJO, typically a bean getter method
  It contains UI friendly name, description and the method value is formated with java.text.Format object.
• State is a collection of Properties, with formating of its own provided by java.text.Format object.

Here is one simple example, observing the state of a custom defined object:

	import net.sf.fikin.pojostate.State;
	import net.sf.fikin.pojostate.Property;
	import net.sf.fikin.pojostate.decorate.SnapshotDecorator;
	import net.sf.fikin.pojostate.select.BeanSelector;
	import net.sf.fikin.pojostate.format.PropertiesStateFormat;

	Decorator decorator = new SnapshotDecorator();

	decorator.setSelector( new BeanSelector() );
	decorator.setFormat( new PropertiesStateFormat() );

	State state = decorator.decorate( myPOJO );

	System.out.println( state.toString() );

which will print out table in the format:

<UI name>=<value>
<#UI description>
...

And few more possibilities:

    // update the POJO state
    myPOJO.changeInternalState();
	state.update();
	System.out.println( state.toString() );

    // sort properties by name
	state.sort( State.SORT_BY_NAME, State.SORT_ASC );
	System.out.println( state.toString() );

	// obtain a single property and read its data
	Property property = state.getProperty( "getInternalState" );
	System.out.println( property.getName() );
	System.out.println( property.getValue() );
	System.out.println( property.getDescription() );

Before you start using the library, you have to sort out few questions:

• How do you decide which methods are representing state (and thus you want to see them printed) and which not?
  Are all "getXXX()" methods to be printed or some are to be excluded?
  Are methods of ClassA only to be printed out or all inherited ones are to be included as well?
  These kind of question is addressed by Selector interface.
  Typically there are two decision strategies at place here:
  • Decide implicitly, by looking at the class, name and signature. Getter methods could be good bet in that direction if your POJOs are genuine Java beans.
    See BeanSelector.
  • Decide explicitly, by providing an exact list of methods. This is useful when method names vary a lot.
    See NEFormatterSelector and ResourceBundleSelector
• In which way do you inspect the object?
  Read all methods at once and store the result inside the State?
  Or read one method at a time as the displaying of it is happening?
  These kind of decisions addressed by Decorator interface.
  • In general, reading in bulk is to be preferred if various get methods are correlated i.e. their values depend on each other. Or POJO state update time is smaller compared to state reading.
    See SnapshotDecorator.
  • Reading on-demand might be more appropriate when methods are self independent from each other and when perhaps not all values would be printed out (thus reducing the amount of unnecessary called methods).
    See DynamicDecorator.
• How often do you plan to read from State object?
  Is observing object's state once in awhile enough? Or do you intend on observing it repeatedly?
  These kind of questions are addressed by your application code.
  • Reusing Decorator would result in smaller decoration time for similar objects.
  • Reusing State would result in smaller state update time for a single object.
• Do you plan on keeping an explicit reference to the object or you prefer to decorate it with weak-ref?
  Having explicit object reference may obstruct the garbage collector.
  • Currently all State implementations are featuring explicit reference.
    If weak-ref is needed one would have to subclass its own soluton.
• How do you plan to format Property values?
  How do you print Date() objects?
  With which calendar, which date-time format?
  Is "long getTimeInMs()" method to be printed as number or as time in milliseconds?
  These kind of questions are addressed by java.text.Format objects.
  Default formatting object used is failing to default toString() implementation.
  But there are Selector classes able to read an external source of information on how to provide formatting to Property values.
• How to do you visulize the whole State?
  Do you want all values in properties-like format? Or XML? Or HTML?
  These kind of questions are addressed by java.text.Format objects, assigned to the Decorator.
• Is methods synchronization going to be a problem?
  When executing object methods there would be object locking if they are synchronized. Is this going to be a problem for your application?
  These kind of decisions are governed by application code.

Once you figure these questions out you're ready to start coding!

Decorators:
SnapshotDecotar creates State object capable of taking all Property values upon update. DynamicDecorator creates State object capable of executing and formatting underlying java.lang.Method each time Property.getValue() is called.
Selectors:
BeanSelector is selecting all getter methods.
ResourceBundleSelector is accepting a resource file with all-to-be-recognized methods listed in.

Formatters:
All java.text.Format implementations are accepted.