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 SessionState.Property
object has been defined.
SessionState Properties that preserve the bounds
Rectangle
for Windows, the dividerLocation
for JSliderPanes
and the
selectedIndex
for JTabbedPanes
are defined by default. The
ApplicationContext
getSesssionStorage
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.xmlWhere 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.xmland on OSX:
${userHome}/Library/Application Support/${applicationId}/session.xml
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Defines thesessionState
property.static class
AsessionState
property for JSplitPane.static class
This Java Bean records thedividerLocation
andorientation
properties of aJSplitPane
.static class
AsessionState
property for JTabbedPane.static class
This Java Bean record theselectedIndex
andtabCount
properties of aJTabbedPane
.static class
AsessionState
property for JTablestatic class
This Java Bean records thecolumnWidths
for all of the columns in a JTable.static class
AsessionState
property for Window.static class
This Java Bean defines theWindow
state preserved across sessions: the Window'sbounds
, and the bounds of the Window'sGraphicsConfiguration
, i.e. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
SessionStorage
(ApplicationContext context) Constructs a SessionStorage object. -
Method Summary
Modifier and TypeMethodDescriptionprotected final ApplicationContext
final SessionStorage.Property
If asessionState Property
object exists for the specified Component return it, otherwise return null.getProperty
(Class cls) Returns theProperty
object that wasregistered
for the specified class or a superclass.void
putProperty
(Class cls, SessionStorage.Property property) Register aProperty
for the specified class.void
Restores each named component in the specified hierarchy from the session state loaded from a file usingLocalStorage.load(fileName)
.void
Saves the state of each named component in the specified hierarchy to a file usingLocalStorage.save(fileName)
.
-
Constructor Details
-
SessionStorage
Constructs a SessionStorage object. The followingProperty
objects are registered by default:Base Component Type sessionState Property sessionState Property Value Window WindowProperty WindowState JTabbedPane TabbedPaneProperty TabbedPaneState JSplitPane SplitPaneProperty SplitPaneState JTable TableProperty TableState Applications typically would not create a
SessionStorage
object directly, they'd use the shared ApplicationContext value:ApplicationContext ctx = Application.getInstance(MyApplication.class).getContext(); SessionStorage ss = ctx.getSesssionStorage();
FIXME - @param javadoc- See Also:
-
-
Method Details
-
getContext
-
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 aProperty
exists
for that component, and the component has aname
, then itsstate
is 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
Property.getSessionState
) must be one those supported byXMLEncoder
andXMLDecoder
, 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
- theLocalStorage
filename.- 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 aProperty
exists for that component, and the component has aname
, then its state isrestored
.- Parameters:
root
- the root of the Component hierarchy to be restored.fileName
- theLocalStorage
filename.- Throws:
IOException
- See Also:
-
getProperty
Returns theProperty
object that wasregistered
for the specified class or a superclass. If no Property has been registered, return null. To lookup the session stateProperty
for aComponent
usegetProperty(Component)
.Throws an
IllegalArgumentException
ifcls
is null.- Parameters:
cls
- the class to which the returnedProperty
applies- Returns:
- the
Property
registered withputProperty
for the specified class or the first one registered for a superclass ofcls
. - See Also:
-
putProperty
Register aProperty
for the specified class. One can clear theProperty
for a class by setting the entry to null:sessionStorage.putProperty(myClass.class, null);
Throws an
IllegalArgumentException
ifcls
is null.- Parameters:
cls
- the class to whichproperty
applies.property
- theProperty
object to register or null.- See Also:
-
getProperty
If asessionState Property
object exists for the specified Component return it, otherwise return null. This method is used by thesave
andrestore
methods to lookup thesessionState Property
object for each component to whose session state is to be saved or restored.The
putProperty
method registers a Property object for a class. One can specify a Property object for a single Swing component by setting the component's client property, like this:myJComponent.putClientProperty(SessionState.Property.class, myProperty);
One can also create components that implement theSessionState.Property
interface directly.- Returns:
- if
Component c
implementsSession.Property
, thenc
, ifc
is aJComponent
with aProperty
valuedclient property
under (client property key)SessionState.Property.class
, then return that, otherwise return the value ofgetProperty(c.getClass())
.Throws an
IllegalArgumentException
ifComponent c
is null. - See Also:
-