commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "B. K. Oxley (binkley)" <>
Subject [vfs] proposal: FileUtils
Date Fri, 21 Jan 2005 21:12:07 GMT
For inclusion in the VFS I propose a higher-level API which wraps the 
lower-level FileObject operations for ease of use in applications.

In particular, I would like to capture these principles:

* Do-or-die semantics.
* Transactional semantics.
* Completed operations.
* Instance methods.
* Easy to use methods.
* A common exception class.


Do-or-die semantics :- Also called succeed-or-throw, I would like 
operations that are always successful if complete, and which throw 
otherwise.  Checking return status for file operations (ala just reeks of procedural programming and is one step from 
error code checking.

Transactional semantics :- If operations fail and throw, as much state 
as possible is restored, possibly all state, such that one could fix a 
problem and retry the operation without any extra complexity, or that 
failed operations do not destroy data, leave junk files around, etc.

Completed operations :- Continuing the idea of do-or-die, nothing should 
be left over for the caller to do after methods finish.  For example, 
the methods should clean up after themselves, removing all temporary 
files, flushing all output streams, closing all open streams, etc.  As 
much as possible, method calls should be one-liners.

Instance methods :- One of the nuisances of is the static 
method for creating a temporary file.  It makes it impossible to 
override the class and change the policy for temporary files.  No public 
static methods unless it is a convenience that forwards to an 
overridable instance method.

Easy to use methods :- Befitting a higher-level API, I'm looking for a 
few large operations which encapsulate typical application- or 
server-level file operations and which transparently handle issues such 
as backup files, temporary files, converting streams to file objects to 
streams, etc.  The whole point is to relieve the 80% usage case from 
extra work and eliminate file operation common bugs.

A common exception class :- One thing does right is use 
IOException as the root of all it's exceptions.  (Too bad JDK 5 didn't 
fix IOException to take the same arguments as java.lang.Exception! -- A 
cause would be very handy.)  I don't want to throw the baby out with the 
bathwater.  I'll refer to it as FuException until there is a better name.

Towards these ends, I suggest at least these methods:

  * FuFile is just a place-holder name.  Maybe these methods move into
  * {@link FileObject}, maybe FileName and FileObject become fields in
  * this class.  It is a good point of discussion.
public interface FuFile {
      * Creates an appropriately named backup file.
     FileName createBackup() throws FuException;

      * Creates an appropriate temporary file.
     FileName createTemporary() throws FuException;

      * Reads from <var>is</var> into this file.
     void readFrom(InputStream is) throws FuException;

      * Writes into <var>out</var> from this file.
     void writeTo(OutputStream out) throws FuException;

      * Moves (renames) this file to the <var>newLocation</var>.
     void moveTo(FuFile newLocation) throws FuException;

      * Copies this file to the <var>newLocation</var>.
     void copyTo(FuFile newLocation) throws FuException;

      * Deletes this file.
     void delete() throws FuException;

Additionally, I'd like to include support for these features in 
combination with the above methods:

* Backup files for operations which replace a files contents.
* Say when it is ok or not ok to overwrite existing files to help avoid 
* Distinguish between replacing contents and appending to contents.

The two model applications I have in mind to demonstrate these ideas and 
how to simplify use of the VFS are graphical file manager and a text 
editor.  I'd like things like cut/copy/paste of files, easy save/saveAs 
operations, backups, confirmation of destructive operations, etc.  So 
many applications needs these things, it seems a shame to make them all 
reimplement the same features.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message