Package org.jdesktop.application

# Class SessionStorage

java.lang.Object
org.jdesktop.application.SessionStorage

public class SessionStorage extends 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 `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:
  - `ApplicationContext.getSessionStorage()`
  - `LocalStorage`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`SessionStorage(ApplicationContext context)`
Constructs a SessionStorage object.

## Method Summary

Modifier and Type
Method
Description
`protected final ApplicationContext`
`getContext()`
Returns `ApplicationContext` which was used during creation of this `SessionStorage` object.
`final PropertySupport`
`getProperty(Component component)`
If a `sessionState PropertySupport` object exists for the specified Component return it, otherwise return null.
`PropertySupport`
`getProperty(Class cls)`
Returns the `PropertySupport` object that was `registered` for the specified class or a superclass.
`void`
`putProperty(Class cls, PropertySupport propertySupport)`
Register a `PropertySupport` for the specified class.
`void`
`restore(Component root, String fileName)`
Restores each named component in the specified hierarchy from the session state loaded from a file using `LocalStorage.load(fileName)`.
`void`
`save(Component root, 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 Details

### SessionStorage

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

### getContext

protected final ApplicationContext getContext()
Returns `ApplicationContext` which was used during creation of this `SessionStorage` object.

Returns:
  the application context for this session storage object

### save

public void save(Component root, String fileName) throws 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 `PropertySupport` `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 `PropertySupport.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:
  `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(Component root, String fileName) throws 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 `PropertySupport` 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:
  `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(Class cls)
Returns the `PropertySupport` object that was `registered` for the specified class or a superclass. If no PropertySupport has been registered, return null. To lookup the session state `PropertySupport` for a `Component` use `getProperty(Component)`.

Parameters:
  `cls` - the class to which the returned `PropertySupport` applies
Returns:
  the `PropertySupport` registered with `putProperty` for the specified class or the first one registered for a superclass of `cls`.
Throws:
  `IllegalArgumentException` - if `cls` 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(Class cls, PropertySupport propertySupport)
Register a `PropertySupport` 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 custom `PropertySupport`:

     ApplicationContext ctx = Application.getInstance(MyApplication.class).getContext();
     SessionStorage ss = ctx.getSesssionStorage();
     ctx.putProperty(JTable.class, new ExtendedTableProperty());

Parameters:
  `cls` - the class to which `propertySupport` applies.
  `propertySupport` - the `PropertySupport` object to register or null.
Throws:
  `IllegalArgumentException` - if `cls` 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(Component component)
If a `sessionState PropertySupport` 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 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 the `PropertySupport` interface directly.

Parameters:
  `component` - the component to retrive the `PropertySupport` from
Returns:
  if `component` implements `PropertySupport`, then `component`, if `component` is a `JComponent` with a `PropertySupport` valued `client property` under (client property key) `PropertySupport`, then return that, otherwise return the value of `getProperty(component.getClass())`.

Throws:
  `IllegalArgumentException` - if `Component 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)`