public class SessionStorage
extends java.lang.Object
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
Modifier and Type | Class and Description |
---|---|
static interface |
SessionStorage.Property
Defines the
sessionState property. |
static class |
SessionStorage.SplitPaneProperty
A
sessionState property for JSplitPane. |
static class |
SessionStorage.SplitPaneState
This Java Bean records the
dividerLocation and orientation properties of a JSplitPane . |
static class |
SessionStorage.TabbedPaneProperty
A
sessionState property for JTabbedPane. |
static class |
SessionStorage.TabbedPaneState
This Java Bean record the
selectedIndex and tabCount properties of a JTabbedPane . |
static class |
SessionStorage.TableProperty
A
sessionState property for JTable |
static class |
SessionStorage.TableState
This Java Bean records the
columnWidths for all
of the columns in a JTable. |
static class |
SessionStorage.WindowProperty
A
sessionState property for Window. |
static class |
SessionStorage.WindowState
This Java Bean defines the
Window state preserved across
sessions: the Window's bounds , and the bounds of the
Window's GraphicsConfiguration , i.e. |
Modifier | Constructor and Description |
---|---|
protected |
SessionStorage(ApplicationContext context)
Constructs a SessionStorage object.
|
Modifier and Type | Method and Description |
---|---|
protected ApplicationContext |
getContext() |
SessionStorage.Property |
getProperty(java.lang.Class cls)
Returns the
Property object that was
registered for the specified class
or a superclass. |
SessionStorage.Property |
getProperty(java.awt.Component c)
If a
sessionState Property object exists for the
specified Component return it, otherwise return null. |
void |
putProperty(java.lang.Class cls,
SessionStorage.Property property)
Register a
Property for the specified class. |
void |
restore(java.awt.Component root,
java.lang.String fileName)
Restores each named component in the specified hierarchy
from the session state loaded from
a file using
LocalStorage.load(fileName) . |
void |
save(java.awt.Component root,
java.lang.String fileName)
Saves the state of each named component in the specified hierarchy to
a file using
LocalStorage.save(fileName) . |
protected SessionStorage(ApplicationContext context)
Property
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
protected final ApplicationContext getContext()
public void save(java.awt.Component root, java.lang.String fileName) throws java.io.IOException
LocalStorage.save(fileName)
.
Each component is visited in breadth-first order: if a Property
exists
for that component,
and the component has a name
, then
its state
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 by XMLEncoder
and
XMLDecoder
, 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 }
root
- the root of the Component hierarchy to be saved.fileName
- the LocalStorage
filename.java.io.IOException
restore(java.awt.Component, java.lang.String)
,
ApplicationContext.getLocalStorage()
,
LocalStorage.save(java.lang.Object, java.lang.String)
,
getProperty(Component)
public void restore(java.awt.Component root, java.lang.String fileName) throws java.io.IOException
LocalStorage.load(fileName)
.
Each component is visited in breadth-first order: if a
Property
exists for that component,
and the component has a name
, then
its state is restored
.root
- the root of the Component hierarchy to be restored.fileName
- the LocalStorage
filename.java.io.IOException
save(java.awt.Component, java.lang.String)
,
ApplicationContext.getLocalStorage()
,
LocalStorage.save(java.lang.Object, java.lang.String)
,
getProperty(Component)
public SessionStorage.Property getProperty(java.lang.Class cls)
Property
object that was
registered
for the specified class
or a superclass. If no Property has been registered,
return null. To lookup the session state Property
for a Component
use getProperty(Component)
.
Throws an IllegalArgumentException
if cls
is null.
cls
- the class to which the returned Property
appliesProperty
registered with putProperty
for
the specified class or the first one registered for a superclass
of cls
.getProperty(Component)
,
putProperty(java.lang.Class, org.jdesktop.application.SessionStorage.Property)
,
save(java.awt.Component, java.lang.String)
,
restore(java.awt.Component, java.lang.String)
public void putProperty(java.lang.Class cls, SessionStorage.Property property)
Property
for the specified class. One can clear
the Property
for a class by setting the entry to null:
sessionStorage.putProperty(myClass.class, null);
Throws an IllegalArgumentException
if cls
is null.
cls
- the class to which property
applies.property
- the Property
object to register or null.getProperty(Component)
,
getProperty(Class)
,
save(java.awt.Component, java.lang.String)
,
restore(java.awt.Component, java.lang.String)
public final SessionStorage.Property getProperty(java.awt.Component c)
sessionState Property
object exists for the
specified Component return it, otherwise return null. This method
is used by the save
and restore
methods
to lookup the sessionState 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 the
SessionState.Property
interface directly.Component c
implements Session.Property
, then
c
, if c
is a JComponent
with a
Property
valued
client property
under
(client property key) SessionState.Property.class
, then
return that, otherwise return the value of
getProperty(c.getClass())
.
Throws an IllegalArgumentException
if Component c
is null.
JComponent.putClientProperty(java.lang.Object, java.lang.Object)
,
getProperty(Class)
,
putProperty(java.lang.Class, org.jdesktop.application.SessionStorage.Property)
,
save(java.awt.Component, java.lang.String)
,
restore(java.awt.Component, java.lang.String)