Class SessionStorage
- java.lang.Object
-
- org.jdesktop.application.SessionStorage
-
public class SessionStorage extends java.lang.Object
Support for storing GUI state that persists between Application sessions.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 aPropertySupport
object has been defined and registeres. SessionState Properties that preserve thebounds
Rectangle
for Windows, thedividerLocation
forJSliderPanes
and theselectedIndex
forJTabbedPanes
are defined by default. TheApplicationContext
getSessionStorage
method provides a sharedSessionStorage
object.A typical Application saves session state in its
shutdown()
method, and then restores session state instartup()
: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 ofmainFrame
as well the session state for any of itsJSliderPane
orJTabbedPane
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
andload
methods. Thestartup
method must set theApplicationContext
vendorId
andapplicationId
properties to ensure that the correctlocal 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
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
SessionStorage(ApplicationContext context)
Constructs a SessionStorage object.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected ApplicationContext
getContext()
ReturnsApplicationContext
which was used during creation of thisSessionStorage
object.PropertySupport
getProperty(java.awt.Component component)
If asessionState PropertySupport
object exists for the specified Component return it, otherwise return null.PropertySupport
getProperty(java.lang.Class cls)
Returns thePropertySupport
object that wasregistered
for the specified class or a superclass.void
putProperty(java.lang.Class cls, PropertySupport propertySupport)
Register aPropertySupport
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 usingLocalStorage.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 usingLocalStorage.save(fileName)
.
-
-
-
Constructor Detail
-
SessionStorage
protected SessionStorage(ApplicationContext context)
Constructs a SessionStorage object. The followingPropertySupport
objects 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
SessionStorage
object directly, they'd use the shared ApplicationContext value:ApplicationContext ctx = Application.getInstance(MyApplication.class).getContext(); SessionStorage ss = ctx.getSesssionStorage();
- Parameters:
context
-- See Also:
ApplicationContext.getSessionStorage()
,getProperty(Class)
,getProperty(Component)
-
-
Method Detail
-
getContext
protected final ApplicationContext getContext()
ReturnsApplicationContext
which was used during creation of thisSessionStorage
object.- Returns:
- the application context for this session storage object
-
save
public void save(java.awt.Component root, java.lang.String fileName) throws java.io.IOException
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 aPropertySupport
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
PropertySupport.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:
java.io.IOException
- See Also:
restore(java.awt.Component, java.lang.String)
,ApplicationContext.getLocalStorage()
,LocalStorage.save(java.lang.Object, java.lang.String)
,getProperty(Component)
-
restore
public void restore(java.awt.Component root, java.lang.String fileName) throws java.io.IOException
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 aPropertySupport
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:
java.io.IOException
- See Also:
save(java.awt.Component, java.lang.String)
,ApplicationContext.getLocalStorage()
,LocalStorage.save(java.lang.Object, java.lang.String)
,getProperty(Component)
-
getProperty
public PropertySupport getProperty(java.lang.Class cls)
Returns thePropertySupport
object that wasregistered
for the specified class or a superclass. If no PropertySupport has been registered, return null. To lookup the session statePropertySupport
for aComponent
usegetProperty(Component)
.- Parameters:
cls
- the class to which the returnedPropertySupport
applies- Returns:
- the
PropertySupport
registered withputProperty
for the specified class or the first one registered for a superclass ofcls
. - Throws:
java.lang.IllegalArgumentException
- ifcls
is null- See Also:
getProperty(Component)
,putProperty(java.lang.Class, org.jdesktop.application.session.PropertySupport)
,save(java.awt.Component, java.lang.String)
,restore(java.awt.Component, java.lang.String)
-
putProperty
public void putProperty(java.lang.Class cls, PropertySupport propertySupport)
Register aPropertySupport
for the specified class.One can clear the
PropertySupport
for 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 whichpropertySupport
applies.propertySupport
- thePropertySupport
object to register or null.- Throws:
java.lang.IllegalArgumentException
- ifcls
is null.- See Also:
getProperty(Component)
,getProperty(Class)
,save(java.awt.Component, java.lang.String)
,restore(java.awt.Component, java.lang.String)
-
getProperty
public final PropertySupport getProperty(java.awt.Component component)
If asessionState PropertySupport
object exists for the specified Component return it, otherwise return null. This method is used by thesave
andrestore
methods to lookup thesessionState PropertySupport
object for each component to whose session state is to be saved or restored.The
putProperty
method 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 thePropertySupport
interface directly.- Parameters:
component
- the component to retrive thePropertySupport
from- Returns:
- if
component
implementsPropertySupport
, thencomponent
, ifcomponent
is aJComponent
with aPropertySupport
valuedclient property
under (client property key)PropertySupport
, then return that, otherwise return the value ofgetProperty(component.getClass())
. - Throws:
java.lang.IllegalArgumentException
- ifComponent component
is null.- See Also:
JComponent.putClientProperty(java.lang.Object, java.lang.Object)
,getProperty(Class)
,putProperty(java.lang.Class, org.jdesktop.application.session.PropertySupport)
,save(java.awt.Component, java.lang.String)
,restore(java.awt.Component, java.lang.String)
-
-