net.sac.ui
Class FileManager

java.lang.Object
  java.awt.event.WindowAdapter
      net.sac.ui.FileManager

All Implemented Interfaces:

java.awt.event.WindowFocusListener, java.awt.event.WindowListener, java.awt.event.WindowStateListener, java.util.EventListener, AutoSavable

public class FileManager
extends java.awt.event.WindowAdapter
implements java.awt.event.WindowListener, AutoSavable

FileManager simplifies the process of managing a users open files. FileManager takes care of prompting the user when necessary and provides support for autosaving. To use FileManager, the saved files must consist of a single serializable object (if there are multiple objects that make up a single file, you can either put them into a Collection or create a wrapper class for the objects). inputStreamEquals and fileContentsEquals methods courtesy of Joe Orost (snoopyjc at www.velocityreviews.com).

Author:

Scott Arnold

Nested Class Summary

static class

FileManager.FileState

Constructor Summary

FileManager(javax.swing.JFrame parent)
Construct a new FileManager with the given parent frame.

FileManager(javax.swing.JFrame parent, boolean multiple)
Construct a new FileManager with the given parent frame.

FileManager(javax.swing.JFrame parent, boolean multiple, java.lang.String defaultExtension, java.lang.String description)
Construct a new FileManager with the given parent frame, setting up a file filter with the given extension and description.

FileManager(javax.swing.JFrame parent, java.lang.String defaultExtension, java.lang.String description)
Construct a new FileManager with the given parent frame, and set up a file filter with the given extension and description.

Method Summary

void	activateOnFileOpen(javax.swing.JMenuItem menuItem) Add a JMenuItem to be managed by the FileManager; menu item will be enabled when files are open and disabled when no files are open.
void	addActiveFileChangeListener(ActiveFileChangeListener listener) Add an ActiveFileChangeListener to this FileManager.
void	autoSave() auto save any open files to their temporary file names.
void	closeDown() Stop the autosaver if it's active and close all open files.
java.lang.String	executeClose() Close the currently active file.
boolean	executeClose(java.lang.String key) Close the file with given key.
java.lang.String	executeNew(java.lang.Object object) Create a new file using the given object.
boolean	executeNew(java.lang.String key, java.lang.Object object) Create a new file using the given object and key.
java.lang.String	executeOpen() Open a file chosen by user prompt.
java.lang.String	executeOpen(java.io.File file) Open the given file.
java.lang.String	executeOpen(java.lang.String fileName)
boolean	executeOpen(java.lang.String key, java.io.File file) Open the given file using the given key.
boolean	executeOpen(java.lang.String key, java.lang.String fileName)
boolean	executeRestore() Attempt to restore any autosaved files that were previously lost due to an abnormal program termination.
boolean	executeSave() Save the currently active file.
boolean	executeSave(java.lang.String key) Save the file of given key.
boolean	executeSaveAs() Save the currently active file, prompting for file name/location.
static boolean	executeSaveAs(javax.swing.JFrame parent, java.lang.Object object) Save the given Object, prompting for file name/location.
static boolean	executeSaveAs(javax.swing.JFrame parent, java.lang.Object object, java.lang.String dialogTitle) Save the given Object, prompting for file name/location.
boolean	executeSaveAs(java.lang.String key) Save the file with given key, prompting for file name/location.
java.lang.String	getFileName() Get the filename associated with the active open file.
java.lang.String	getFileName(java.lang.String key) Get the filename associated with the file of given key.
java.lang.Object	getObject() Get the object associated with the active open file.
java.lang.Object	getObject(java.lang.String key) Get the object associated with the file of given key.
int	getOpenFileCount() Return a count of the number of currently open files.
static java.lang.Object	loadObject(java.io.File file) Load an Object from the given file.
static java.lang.Object	loadObject(java.lang.String fileName)
static void	saveObject(java.io.File file, java.lang.Object object) Save an Object to the given file.
static void	saveString(java.io.File file, java.lang.Object object) Save an Object's String value to the given file.
void	setActiveFile(java.lang.String key) Set which open file is considered to be the active open file using the file's key value.
void	setAutosave(boolean autosave) Turn the autosave feature on or off.
void	setAutosaveInterval(long autosaveInterval) Set the frequency in milliseconds of the autosave feature.
void	windowClosed(java.awt.event.WindowEvent event)
void	windowClosing(java.awt.event.WindowEvent event)

Methods inherited from class java.awt.event.WindowAdapter

windowActivated, windowDeactivated, windowDeiconified, windowGainedFocus, windowIconified, windowLostFocus, windowOpened, windowStateChanged

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.awt.event.WindowListener

windowActivated, windowDeactivated, windowDeiconified, windowIconified, windowOpened

Constructor Detail

FileManager

public FileManager(javax.swing.JFrame parent)

Construct a new FileManager with the given parent frame. The FileManager will default to only allowing 1 open file at a time.

Parameters:

parent - Parent frame

FileManager

public FileManager(javax.swing.JFrame parent,
                   java.lang.String defaultExtension,
                   java.lang.String description)

Construct a new FileManager with the given parent frame, and set up a file filter with the given extension and description. The FileManager will default to only allowing 1 open file at a time.

Parameters:

parent - parent frame

defaultExtension - file extension for file filter

description - description of file filter

FileManager

public FileManager(javax.swing.JFrame parent,
                   boolean multiple)

Construct a new FileManager with the given parent frame. If multiple is set to true, the FileManager will allow multiple files to be opened simultaneously; if false, FileManager will only allow one file to be open at a time.

Parameters:

parent - Parent frame

multiple - Whether or not to allow multiple files to be open simultaneously

FileManager

public FileManager(javax.swing.JFrame parent,
                   boolean multiple,
                   java.lang.String defaultExtension,
                   java.lang.String description)

Construct a new FileManager with the given parent frame, setting up a file filter with the given extension and description. If multiple is set to true, the FileManager will allow multiple files to be open simultaneously; if false, FileManager will only allow one open file at a time.

Parameters:

parent - parent frame

multiple - whether or not to allow multiple files to be open simultaneously

defaultExtension - file extension for file filter

description - description for file filter

Method Detail

addActiveFileChangeListener

public void addActiveFileChangeListener(ActiveFileChangeListener listener)

Add an ActiveFileChangeListener to this FileManager. Whenever the active file changes, all ActiveFileChangeListeners will be notified.

Parameters:

listener -

setAutosaveInterval

public void setAutosaveInterval(long autosaveInterval)

Set the frequency in milliseconds of the autosave feature.

Parameters:

autosaveInterval - frequency (in milliseconds) of auto save

setAutosave

public void setAutosave(boolean autosave)

Turn the autosave feature on or off.

Parameters:

autosave - true == on, false == off

getOpenFileCount

public int getOpenFileCount()

Return a count of the number of currently open files.

Returns:

number of open files

setActiveFile

public void setActiveFile(java.lang.String key)

Set which open file is considered to be the active open file using the file's key value.

Parameters:

key -

getObject

public java.lang.Object getObject()

Get the object associated with the active open file.

Returns:

object associated with the currently active file.

getObject

public java.lang.Object getObject(java.lang.String key)

Get the object associated with the file of given key.

Parameters:

key - key associated with file

Returns:

object from file with given key

getFileName

public java.lang.String getFileName()

Get the filename associated with the active open file.

Returns:

file name of currently active file.

getFileName

public java.lang.String getFileName(java.lang.String key)

Get the filename associated with the file of given key.

Parameters:

key - key of file

Returns:

file name of file with given key

executeRestore

public boolean executeRestore()
                       throws java.io.IOException

Attempt to restore any autosaved files that were previously lost due to an abnormal program termination. This call should be performed on program startup for any program utilizing the autosave feature; if this method returns true, then program should then iterate through the keys and reconstruct it's state through calls to getObject and getFileName. If files are restored, the active file is set to the first restored file; the program should manually set the active file if necessary.

Returns:

whether or not any files were restored.

Throws:

java.io.IOException

executeNew

public java.lang.String executeNew(java.lang.Object object)
                            throws java.io.IOException

Create a new file using the given object.

Parameters:

object - object associated with new file

Returns:

auto-generated key for new file

Throws:

java.io.IOException

executeNew

public boolean executeNew(java.lang.String key,
                          java.lang.Object object)
                   throws java.io.IOException

Create a new file using the given object and key. Key value must be unique. This method provides the main program the ability to use it's own key values rather than auto-generated keys.

Parameters:

key - key to associate with new file

object - object associated with new file

Returns:

whether or not new file was set up successfully

Throws:

java.io.IOException

executeOpen

public java.lang.String executeOpen()
                             throws java.io.IOException

Open a file chosen by user prompt.

Returns:

key of opened file (null if no file was opened)

Throws:

java.io.IOException

executeOpen

public java.lang.String executeOpen(java.lang.String fileName)
                             throws java.io.IOException

Throws:

java.io.IOException

executeOpen

public boolean executeOpen(java.lang.String key,
                           java.lang.String fileName)
                    throws java.io.IOException

Throws:

java.io.IOException

executeOpen

public java.lang.String executeOpen(java.io.File file)
                             throws java.io.IOException

Open the given file.

Parameters:

file -

Returns:

Throws:

java.io.IOException

executeOpen

public boolean executeOpen(java.lang.String key,
                           java.io.File file)
                    throws java.io.IOException

Open the given file using the given key. Key value must be unique. This method provides the program the option of using it's own key values rather than using auto-generated keys.

Parameters:

key -

file -

Returns:

Throws:

java.io.IOException

executeSave

public boolean executeSave()
                    throws java.io.IOException

Save the currently active file.

Returns:

whether or not file was saved successfully

Throws:

java.io.IOException

executeSave

public boolean executeSave(java.lang.String key)
                    throws java.io.IOException

Save the file of given key.

Parameters:

key - key of file to save

Returns:

whether or not file was saved successfully

Throws:

java.io.IOException

executeSaveAs

public static boolean executeSaveAs(javax.swing.JFrame parent,
                                    java.lang.Object object,
                                    java.lang.String dialogTitle)
                             throws java.io.IOException

Save the given Object, prompting for file name/location. This method provides the convenience of the FileManager save as feature for files that are not under the control of the FileManager.

Parameters:

parent - parent frame

object - object to save to file

dialogTitle - title for file chooser dialog window

Returns:

whether or not file was saved

Throws:

java.io.IOException

executeSaveAs

public static boolean executeSaveAs(javax.swing.JFrame parent,
                                    java.lang.Object object)
                             throws java.io.IOException

Save the given Object, prompting for file name/location. This method provides the convenience of the FileManager save as feature for files that are not under the control of the FileManager.

Parameters:

parent - parent frame

object - object to save to file

Returns:

whether or not file was saved

Throws:

java.io.IOException

executeSaveAs

public boolean executeSaveAs()
                      throws java.io.IOException

Save the currently active file, prompting for file name/location.

Returns:

whether or not file was saved

Throws:

java.io.IOException

executeSaveAs

public boolean executeSaveAs(java.lang.String key)
                      throws java.io.IOException

Save the file with given key, prompting for file name/location.

Parameters:

key - key of file to save

Returns:

whether or not file was saved

Throws:

java.io.IOException

executeClose

public boolean executeClose(java.lang.String key)
                     throws java.io.IOException

Close the file with given key.

Parameters:

key - key of file to close

Returns:

whether or not file was closed

Throws:

java.io.IOException

executeClose

public java.lang.String executeClose()
                              throws java.io.IOException

Close the currently active file. The file key is returned in case the calling code is uncertain of which file is the currently active file; null is returned if no file is closed.

Returns:

key of file closed

Throws:

java.io.IOException

loadObject

public static java.lang.Object loadObject(java.io.File file)
                                   throws java.io.IOException

Load an Object from the given file.

Parameters:

file -

Returns:

Throws:

java.io.IOException

saveObject

public static void saveObject(java.io.File file,
                              java.lang.Object object)
                       throws java.io.IOException

Save an Object to the given file.

Parameters:

file -

object -

Throws:

java.io.IOException

saveString

public static void saveString(java.io.File file,
                              java.lang.Object object)
                       throws java.io.IOException

Save an Object's String value to the given file.

Parameters:

file -

object -

Throws:

java.io.IOException

loadObject

public static java.lang.Object loadObject(java.lang.String fileName)
                                   throws java.io.IOException

Throws:

java.io.IOException

autoSave

public void autoSave()

auto save any open files to their temporary file names.

Specified by:

autoSave in interface AutoSavable

closeDown

public void closeDown()

Stop the autosaver if it's active and close all open files. Programs using the File Manager do not need to explicitly call this method for any reason, but may choose to on program exit if the program exit strategy does not always trigger a windowClosing event and either does not alternately trigger a windowClosed event or the windowClosed event is considered undesireable (because the parent window will already be gone from the screen if caught by the window closed event). In such cases, the program can manually call the FileManager closeDown() method to ensure that save file prompts occur at the desired time on program shutdown.

activateOnFileOpen

public void activateOnFileOpen(javax.swing.JMenuItem menuItem)

Add a JMenuItem to be managed by the FileManager; menu item will be enabled when files are open and disabled when no files are open.

Parameters:

menuItem - menu item to be managed

windowClosed

public void windowClosed(java.awt.event.WindowEvent event)

Specified by:

windowClosed in interface java.awt.event.WindowListener

Overrides:

windowClosed in class java.awt.event.WindowAdapter

windowClosing

public void windowClosing(java.awt.event.WindowEvent event)

Specified by:

windowClosing in interface java.awt.event.WindowListener

Overrides:

windowClosing in class java.awt.event.WindowAdapter