org.jdesktop.application
Class SessionStorage

java.lang.Object
  extended by 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 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.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:
ApplicationContext.getSessionStorage(), LocalStorage

Nested Class Summary
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 This class defines how the session state for JTables is saved and and restored in terms of a property called sessionState.
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. the bounds of the screen that the Window appears on.
 
Constructor Summary
protected SessionStorage(ApplicationContext context)
          Constructs a SessionStorage object.
 
Method Summary
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).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SessionStorage

protected SessionStorage(ApplicationContext context)
Constructs a SessionStorage object. The following 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

See Also:
ApplicationContext.getSessionStorage(), getProperty(Class), getProperty(Component)
Method Detail

getContext

protected final ApplicationContext getContext()

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 using 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
 }
 

Parameters:
root - the root of the Component hierarchy to be saved.
fileName - the LocalStorage 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 using 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.

Parameters:
root - the root of the Component hierarchy to be restored.
fileName - the LocalStorage 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 SessionStorage.Property getProperty(java.lang.Class cls)
Returns the 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.

Parameters:
cls - the class to which the returned Property applies
Returns:
the Property registered with putProperty for the specified class or the first one registered for a superclass of cls.
See Also:
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)

putProperty

public void putProperty(java.lang.Class cls,
                        SessionStorage.Property property)
Register a 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.

Parameters:
cls - the class to which property applies.
property - the Property object to register or null.
See Also:
getProperty(Component), getProperty(Class), save(java.awt.Component, java.lang.String), restore(java.awt.Component, java.lang.String)

getProperty

public final SessionStorage.Property getProperty(java.awt.Component c)
If a 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.

Returns:
if 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.

See Also:
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)