FileSvc.IFileSaver Interface

com.bea.ide.filesystem
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

Method Summary

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.

Method Detail

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