Persistence of Plugins

Source file: Persistence

JavaDoc: JRViewer

JavaDoc: Plugin

Run as Java webstart

The controller of the plugin system provides an API which may be used by plugins to persist (save and restore) their properties. A Controller informs Plugins via the following two methods that a plugin should store or restore its properties

public void restoreStates(Controller c)
public void storeStates(Controller c)

The SimpleController, which works behind the scenes in JRViewer, calls them at startup and shutdown. A Controller provides the following three methods to be used by a Plugin in the methods storeStates and restoreStates.

	public Object storeProperty(Class<?> context, String key, Object property);
	public <T> T getProperty(Class<?> context, String key, T defaultValue);
	public <T> T deleteProperty(Class<?> context, String key);

The Controller should take care of saving and loading the stored properties. To tell the Controller of a JRViewer about which file it should use for reading and saving the properties the JRViewer provides the following three methods.

public void setPropertiesResource(Class<?> clazz, String propertiesFileName)
public void setPropertiesFile(String filename) 
public void setPropertiesFile(File file) 
public void setPropertiesInputStream(InputStream in)

The recommended method to use is setPropertiesResource.

Example

The following example implements a Plugin that allows the user to choose between four geometries. The plugin persists the choice. Note that ViewShrinkPanelPlugin persists its state (shrinking, position, visibility). So if you open the right slot (see the Window menu entry) and move the plugin (more precisely its ShrinkPanel) to the right slot, it will still be there after restarting the application.

public class Persistence extends ViewShrinkPanelPlugin {
	public enum Geometries {
		Icosahedron(Primitives.icosahedron()),
		ColoredCube(Primitives.coloredCube()),
		Tetrahedron(Primitives.tetrahedron()),
		Torus(Primitives.torus(Math.sqrt(2), 1, 20, 20));
		
		public final Geometry geometry;
		Geometries(Geometry geometry) {	this.geometry=geometry;}
	}
 
	private final JComboBox comboBox=new JComboBox(Geometries.values());
	private final SceneGraphComponent sgc=new SceneGraphComponent("A Geometry");
 
	public Persistence() {
		setInitialPosition(SHRINKER_LEFT);
		getShrinkPanel().add(comboBox);
		
		comboBox.addActionListener(new ActionListener() {
			public void actionPerformed(ActionEvent e) {
				sgc.setGeometry(
						((Geometries)comboBox.getSelectedItem()).geometry);
				}
		});
	}
	
	public PluginInfo getPluginInfo() {
		return new PluginInfo("Primitive Chooser");
	}
	
	public void install(Controller c) throws Exception {
		super.install(c);
		c.getPlugin(Scene.class)
			.getContentComponent()
			.addChild(sgc);
	}
 
	public void uninstall(Controller c) throws Exception {
		c.getPlugin(Scene.class)
			.getContentComponent()
		    .removeChild(sgc);
		super.uninstall(c);
	}
	
	public void restoreStates(Controller c) throws Exception {
		super.restoreStates(c);
		comboBox.setSelectedItem(
				c.getProperty(getClass(), "geometry", Geometries.values()[0]));
	}
	
	public void storeStates(Controller c) throws Exception {
		super.storeStates(c);
		c.storeProperty(getClass(), "geometry", (Geometries) comboBox.getSelectedItem());
	}
 
	public static void main(String[] args) {
		JRViewer v = new JRViewer();
		v.registerPlugin(new Persistence());
		v.registerPlugin(new ContentTools());
		v.registerPlugin(new PropertiesMenu());
		v.setPropertiesResource(Persistence.class, "PersistenceProperties.xml");
		v.setShowPanelSlots(true, false, false, false);
		v.startup();
	}
}

Remarks

Two lines in the example merit a comment.

• The line

v.setPropertiesResource(Persistence.class, "PersistenceProperties.xml");

instructs the JRViewer to read the properties from the resource "PersistenceProperties.xml", i.e., a file with that name in the folder of the Persistence.class file. If the resource is writable the controller may also write to this file. Any way the user is asked where to save the file, whether to load the properties from that file, and whether to be asked again. These 3 decisions and the filename are saved as java preferences in the node "de.jreality.tutorial.plugin", which is the package of the Persistence tutorial class. As the file is written by XStream it is a human readable and edible xml file. Just have a look at it.

• The line

v.registerPlugin(new PropertiesMenu())

adds a "Properties" menu, which allows the user to trigger saving and loading of the properties to a file of his choice.

Previous: The JRViewer plug-in set Developer Tutorial#Plugins: Contents Next: Developer Tutorial#Plugins