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.
Rationale:
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
java.io.File) 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 java.io.File 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 java.io.File 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
accidents.
* 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.
Cheers,
--binkley
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
|