Class SessionStorage
This class simplifies the common task of saving a little bit of an
application's GUI "session" state when the application shuts down,
and then restoring that state when the application is restarted.
Session state is stored on a per component basis, and only for
components with a name and for
which a PropertySupport object has been defined and registeres.
SessionState Properties that preserve the bounds Rectangle
for Windows, the dividerLocation for JSliderPanes and the
selectedIndex for JTabbedPanes are defined by default. The
ApplicationContext getSessionStorage method
provides a shared SessionStorage object.
A typical Application saves session state in its
shutdown() method, and then restores
session state in startup():
public class MyApplication extends Application {
@Override protected void shutdown() {
getContext().getSessionStorage().save(mainFrame, "session.xml");
}
@Override protected void startup() {
ApplicationContext appContext = getContext();
appContext.setVendorId("Sun");
appContext.setApplicationId("SessionStorage1");
// ... create the GUI rooted by JFrame mainFrame
appContext.getSessionStorage().restore(mainFrame, "session.xml");
}
// ...
}
In this example, the bounds of mainFrame as well the
session state for any of its JSliderPane or
JTabbedPane will be saved when the application shuts down, and
restored when the applications starts up again. Note: error
handling has been omitted from the example.
Session state is stored locally, relative to the user's
home directory, by the LocalStorage
save and load
methods. The startup method must set the
ApplicationContext vendorId and applicationId
properties to ensure that the correct
local directory is selected on
all platforms. For example, on Windows XP, the full pathname
for filename "session.xml" is typically:
${userHome}\Application Data\${vendorId}\${applicationId}\session.xml
Where the value of ${userHome} is the the value of
the Java System property "user.home". On Solaris or
Linux the file is:
${userHome}/.${applicationId}/session.xml
and on OSX:
${userHome}/Library/Application Support/${applicationId}/session.xml
- See Also:
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedSessionStorage(ApplicationContext context) Constructs a SessionStorage object. -
Method Summary
Modifier and TypeMethodDescriptionprotected final ApplicationContextReturnsApplicationContextwhich was used during creation of thisSessionStorageobject.final PropertySupportgetProperty(Component component) If asessionState PropertySupportobject exists for the specified Component return it, otherwise return null.getProperty(Class cls) Returns thePropertySupportobject that wasregisteredfor the specified class or a superclass.voidputProperty(Class cls, PropertySupport propertySupport) Register aPropertySupportfor the specified class.voidRestores each named component in the specified hierarchy from the session state loaded from a file usingLocalStorage.load(fileName).voidSaves the state of each named component in the specified hierarchy to a file usingLocalStorage.save(fileName).
-
Constructor Details
-
SessionStorage
Constructs a SessionStorage object. The followingPropertySupportobjects are registered by default:Base Component Type PropertySupport PropertySupport Value Window WindowProperty WindowState JTabbedPane TabbedPaneProperty TabbedPaneState JSplitPane SplitPaneProperty SplitPaneState JTable TableProperty TableState Applications typically would not create a
SessionStorageobject directly, they'd use the shared ApplicationContext value:ApplicationContext ctx = Application.getInstance(MyApplication.class).getContext(); SessionStorage ss = ctx.getSesssionStorage();
- Parameters:
context-- See Also:
-
-
Method Details
-
getContext
ReturnsApplicationContextwhich was used during creation of thisSessionStorageobject.- Returns:
- the application context for this session storage object
-
save
Saves the state of each named component in the specified hierarchy to a file usingLocalStorage.save(fileName). Each component is visited in breadth-first order: if aPropertySupportexistsfor that component, and the component has aname, then itsstateis saved.Component names can be any string however they must be unique relative to the name's of the component's siblings. Most Swing components do not have a name by default, however there are some exceptions: JRootPane (inexplicably) assigns names to it's children (layeredPane, contentPane, glassPane); and all AWT components lazily compute a name, so JFrame, JDialog, and JWindow also have a name by default.
The type of sessionState values (i.e. the type of values returned by
PropertySupport.getSessionState) must be one those supported byXMLEncoderandXMLDecoder, for example beans (null constructor, read/write properties), primitives, and Collections. Java bean classes and their properties must be public. Typically beans defined for this purpose are little more than a handful of simple properties. The JDK 6 @ConstructorProperties annotation can be used to eliminate the need for writing set methods in such beans, e.g.public class FooBar { private String foo, bar; // Defines the mapping from constructor params to properties @ConstructorProperties({"foo", "bar"}) public FooBar(String foo, String bar) { this.foo = foo; this.bar = bar; } public String getFoo() { return foo; } // don't need setFoo public String getBar() { return bar; } // don't need setBar }- Parameters:
root- the root of the Component hierarchy to be saved.fileName- theLocalStoragefilename.- Throws:
IOException- See Also:
-
restore
Restores each named component in the specified hierarchy from the session state loaded from a file usingLocalStorage.load(fileName). Each component is visited in breadth-first order: if aPropertySupportexists for that component, and the component has aname, then its state isrestored.- Parameters:
root- the root of the Component hierarchy to be restored.fileName- theLocalStoragefilename.- Throws:
IOException- See Also:
-
getProperty
Returns thePropertySupportobject that wasregisteredfor the specified class or a superclass. If no PropertySupport has been registered, return null. To lookup the session statePropertySupportfor aComponentusegetProperty(Component).- Parameters:
cls- the class to which the returnedPropertySupportapplies- Returns:
- the
PropertySupportregistered withputPropertyfor the specified class or the first one registered for a superclass ofcls. - Throws:
IllegalArgumentException- ifclsis null- See Also:
-
putProperty
Register aPropertySupportfor the specified class.One can clear the
PropertySupportfor a class by setting the entry to null:sessionStorage.putProperty(myClass.class, null);
Register a customPropertySupport:ApplicationContext ctx = Application.getInstance(MyApplication.class).getContext(); SessionStorage ss = ctx.getSesssionStorage(); ctx.putProperty(JTable.class, new ExtendedTableProperty());
- Parameters:
cls- the class to whichpropertySupportapplies.propertySupport- thePropertySupportobject to register or null.- Throws:
IllegalArgumentException- ifclsis null.- See Also:
-
getProperty
If asessionState PropertySupportobject exists for the specified Component return it, otherwise return null. This method is used by thesaveandrestoremethods to lookup thesessionState PropertySupportobject for each component to whose session state is to be saved or restored.The
putPropertymethod registers a PropertySupport object for a class. One can specify a PropertySupport object for a single Swing component by setting the component's client property, like this:myJComponent.putClientProperty(PropertySupport.class, myPropertySupport);
One can also create components that implement thePropertySupportinterface directly.- Parameters:
component- the component to retrive thePropertySupportfrom- Returns:
- if
componentimplementsPropertySupport, thencomponent, ifcomponentis aJComponentwith aPropertySupportvaluedclient propertyunder (client property key)PropertySupport, then return that, otherwise return the value ofgetProperty(component.getClass()). - Throws:
IllegalArgumentException- ifComponent componentis null.- See Also:
-