FileSvc.IFileSaver Interface
- public static interface FileSvc.IFileSaver
The file saver interface provides a safe, atomic mechanism for saving files. The caller is
guaranteed that the save succeeds, or the original file remains intact. Typically this is performed
by doing the save to a temporary file, and then atomically renaming the temporary file to the
final filename.
To use a file saver, you first call canSave(). if it returns true, then you get a writer or output stream
and write the data. Once all data has been written, you call finish(). Finally you call cleanup().
Generally, canSave() and finish() are the methods that return errors. getRealName() is a convenience method
that allows the caller to show useful error messages by including the real name of the file being saved.
Typically, invoking these methods directly is not necessary as you may simply call the FileSvc.get().save()
methods to perform this work for you.
-
Enclosing class
-
FileSvc
public boolean |
-
allowsOverwrite ()
- This method indicates whether the file saver object allows overwrite of an existing file.
|
public String |
-
canSave ()
- This method tests whether the initial conditions of the file saver are satisfied and returns an error string
if anything will prevent the save from occurring.
|
public void |
-
cleanup ()
- Performs final cleanup and insures that any temp files are removed.
|
public String |
-
finish ()
- The finish() method performs the final work to complete the save once all data has been written.
|
public OutputStream |
-
getOutputStream ()
- Get the output stream to use for saving the file.
|
public URI |
-
getRealName ()
- This is a utility method to get the URI of the file to be saved.
|
public Writer |
-
getWriter (Reader in, boolean dialogsOK)
- Content in the reader may define an encoding to use for writing
the file to disk.
|
public void |
-
setFileChangeEventState (Object o)
- sets the state object that will be sent with the file change event associated with this
file saver.
|
allowsOverwrite() Method
public boolean allowsOverwrite()
This method indicates whether the file saver object allows overwrite of an existing file.
If this value returns false, the file saver will only succeed if the destination file does not exist
prior to the save.
Returns
- true if the saver allows overwriting an existing file, false otherwise
canSave() Method
public String
canSave()
This method tests whether the initial conditions of the file saver are satisfied and returns an error string
if anything will prevent the save from occurring. Examples of these conditions are: permission to write the
temp and final files, valid filenames, valid encodings, etc....
Returns
- string indicating error if save is not possible, otherwise null is returned indicating save may proceed
cleanup() Method
public void cleanup()
Performs final cleanup and insures that any temp files are removed. This method should be called in the case of
both success and failure.
finish() Method
public String
finish()
The finish() method performs the final work to complete the save once all data has been written. This intended
to provide a safe atomic save operation. Thus even if a problem occurs while the data is being written, the
original contents of the file are left intact. A null return value indicates a successful save and the data
written using the provided writer or output stream will be the only contents of the file. A non-null return value
indicates an error occurred. The original contents of the file (if any) remain intact. It is possible that an
error occurred before the new data was moved to the correct filename, but after the backup of the old file was created.
The convention in this case is that the old file's contents are available in a file called "oldfilename.bak".
Returns
- null if the save completes successfully, otherwise a string with a relevant error message regarding
what went wrong with the save.
getOutputStream() Method
public OutputStream
getOutputStream()
Get the output stream to use for saving the file. This method is the equivalent of getWriter() however,
since OutputStreams don't have any encoding, it is much simpler. This provides an output stream to which
the caller should write data.
Returns
- output stream for writing data
getRealName() Method
public URI
getRealName()
This is a utility method to get the URI of the file to be saved. Note that this is not the temp file,
but the actual file that will be saved on successful completion of the method.
Returns
- URI of the file that is being saved
getWriter(Reader, boolean) Method
public Writer
getWriter(Reader
in,
boolean dialogsOK)
Content in the reader may define an encoding to use for writing
the file to disk. This method will examine the Reader's contents
and build a Writer appropriately. The Reader must support the mark()
and reset() calls, like BufferedReader does.
Parameters
-
in
- the Reader to examine for encoding headers.
-
dialogsOK
- true lets the FileSaver inform the user of errors.
Returns
- a properly-configured Writer.
setFileChangeEventState(Object) Method
public void setFileChangeEventState(Object
o)
sets the state object that will be sent with the file change event associated with this
file saver.
Parameters
-
o
- the object that will be returned from getState() on file change events sent by the save
operation of this file saver