|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.jdesktop.application.SessionStorage
public class SessionStorage
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
ApplicationContext.getSessionStorage(),
LocalStorage| Constructor Summary | |
|---|---|
protected |
SessionStorage(ApplicationContext context)
Constructs a SessionStorage object. |
| Method Summary | |
|---|---|
protected ApplicationContext |
getContext()
Returns ApplicationContext which was used during creation of this
SessionStorage object. |
PropertySupport |
getProperty(java.lang.Class cls)
Returns the PropertySupport object that was
registered for the specified class
or a superclass. |
PropertySupport |
getProperty(java.awt.Component component)
If a sessionState PropertySupport object exists for the
specified Component return it, otherwise return null. |
void |
putProperty(java.lang.Class cls,
PropertySupport propertySupport)
Register a PropertySupport 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 |
|---|
protected SessionStorage(ApplicationContext context)
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();
context - ApplicationContext.getSessionStorage(),
getProperty(Class),
getProperty(Component)| Method Detail |
|---|
protected final ApplicationContext getContext()
ApplicationContext which was used during creation of this
SessionStorage object.
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 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
}
root - the root of the Component hierarchy to be saved.fileName - the LocalStorage filename.
java.io.IOExceptionrestore(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
PropertySupport 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.IOExceptionsave(java.awt.Component, java.lang.String),
ApplicationContext.getLocalStorage(),
LocalStorage.save(java.lang.Object, java.lang.String),
getProperty(Component)public PropertySupport getProperty(java.lang.Class cls)
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).
cls - the class to which the returned PropertySupport applies
PropertySupport registered with putProperty for
the specified class or the first one registered for a superclass
of cls.
java.lang.IllegalArgumentException - if cls is nullgetProperty(Component),
putProperty(java.lang.Class, org.jdesktop.application.session.PropertySupport),
save(java.awt.Component, java.lang.String),
restore(java.awt.Component, java.lang.String)
public void putProperty(java.lang.Class cls,
PropertySupport propertySupport)
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());
cls - the class to which propertySupport applies.propertySupport - the PropertySupport object to register or null.
java.lang.IllegalArgumentException - if cls is null.getProperty(Component),
getProperty(Class),
save(java.awt.Component, java.lang.String),
restore(java.awt.Component, java.lang.String)public final PropertySupport getProperty(java.awt.Component component)
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.
component - the component to retrive the PropertySupport from
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()).
java.lang.IllegalArgumentException - if Component component is null.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)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||