5.4.3. Object State Viewers (OSV)

When an object is selected in the objects pane of the main window the registered Object State Viewer (or OSV) for that object type is invoked. An OSV’s job is to make information available via the user interface to the user to show information about the selected object. Distributed with the standard tools is an OSV for Atomic Actions, the OSV displays information on the Abstract Records in it’s various lists (e.g. heuristic, failed, read-only, etc). It is also possible to write your own OSVs which can be used to display information about object types you have defined. This subject is covered next.
Writing an OSV

Writing an OSV plugin allows you to extend the capabilities of the Object Store browser to show the state of user defined abstract records. An OSV plug-in is simply a class which implements the interface:

com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface
It must be packaged in a JAR within the plugins directory. This example shows how to create an OSV plugin for an abstract record subclass which looks as follows:
public class SimpleRecord extends AbstractRecord
{
	private int _value = 0;
	
	.....
	
	public void increase()
	{
		_value++;
	}
	
	public int get()
	{
		return _value;
	}
	
	public String type()
	{
		return “/StateManager/AbstractRecord/SimpleRecord”;
	}
	
	public boolean restore_state(InputObjectState os, int i)
	{
		boolean returnValue = true;
	
		try
		{
			_value = os.unpackInt();
		}
		catch (java.io.IOException e)
		{
			returnValue = false;
		}
	
		return returnValue;
	}
	
	public boolean save_state(OutputObjectState os, int i)
	{
		boolean returnValue = true;
	
		try
		{
			os.packInt(_value);
		}
		catch (java.io.IOException e)
		{
			returnValue = false;
		}
	
		return returnValue;
	}
}
When this abstract record is viewed in the object store browser it would be nice to see the current value. This is easy to do as we can read the state into an instance of our abstract record and call getValue(). The following is the object store browser plug-in source code:
public class SimpleRecordOSVPlugin implements StateViewerInterface
{
	/**
	* A uid node of the type this viewer is registered against has been expanded.
	* @param os
	* @param type
	* @param manipulator
	* @param node
	* @throws ObjectStoreException
	*/
	public void uidNodeExpanded(ObjectStore os,
	String type,
	ObjectStoreBrowserTreeManipulationInterface 
	manipulator,
	UidNode node,
	StatePanel infoPanel)
	throws ObjectStoreException
	{
		// Do nothing
	}
	
	/**
	* An entry has been selected of the type this viewer is registered against.
	*
	* @param os
	* @param type
	* @param uid
	* @param entry
	* @param statePanel
	* @throws ObjectStoreException
	*/
	public void entrySelected(ObjectStore os,
	String type,
	Uid uid,
	ObjectStoreViewEntry entry,
	StatePanel statePanel) 
	throws ObjectStoreException
	{
		SimpleRecord rec = new SimpleRecord();
	
		if ( rec.restore_state( os.read_committed(uid, type), ObjectType.ANDPERSISTENT ) )
		{
			statePanel.setData( “Value”, rec.getValue() );
		}
	}
	
	/**
	* Get the type this state viewer is intended to be registered against.
	* @return
	*/
	public String getType()
	{
		return “/StateManager/AbstractRecord/SimpleRecord”;
	}
}
The method uidNodeExpanded is invoked when a UID (Unique Identification) representing the given type is expanded in the object store hierarchy tree. This is not required by this plugin as this abstract record is not visible in the object store directly it is only viewable via one of the lists in an atomic action. The method entrySelected is invoked when an entry is selected from the object view which represents an object with the given type. In both methods the StatePanel is used to display information regarding the state of the object. The state panel has the following methods that assist in display this information:
  • setInfo(String info): This method can be used to show general information.
  • setData(String name, String value): This method is used to put information into the table which is displayed by the object store browser tool.
  • enableDetailsButton(DetailsButtonListener listener): This method is used to enable the details button. The listener interface allows a plug-in to be informed when the button is pressed. It is up to the plug-in developer to decide how to display this further information.
In this example we read the state from the object store and use the value returned by getValue() to put an entry into the state panel table. The getType() method returns the type this plug-in is to be registered against.
To add this plug-in to the object store browser it is necessary to package it into a JAR (Java Archive) file with a name that is prefixed with 'osbv-'. The JAR file must contain certain information within the manifest file so that the object store browser knows which classes are plug-ins. All of this can be performed using an Apache ANT script, as follows:
<jar jarfile="osbv-simplerecord.jar">
	<fileset dir="build" includes="*.class”/>
	<manifest>
		<section name="arjuna-tools-objectstorebrowser">
			<attribute name="plugin-classname-1" value=" SimpleRecordOSVPlugin "/>
		</section>
	</manifest>
</jar>
Once the JAR has been created with the correct information in the manifest file it just needs to be placed in the bin/tools/plugins directory.