# 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