com.partnersoft.io.vfs
Class AbstractVfsFile

java.lang.Object
  com.partnersoft.io.vfs.AbstractVfsFile

All Implemented Interfaces:

VfsFile, VfsNode

Direct Known Subclasses:

NonexistentVfsFile

public abstract class AbstractVfsFile
extends java.lang.Object
implements VfsFile

A standard abstract implementation of com.partnersoft.io.VfsFile. Includes implementations of the various convenience methods derived from the essential methods, and provides the vfs and path properties.

Most implementations of VfsFile should extend this class.

A minimal set of methods has been declared abstract. All other methods are derived from these with default implementations. For example, the various buffered forms of the create methods simply add a buffered wrapper to the plain create (e.g. createBufferedInputStream() returns a new BufferedInputStream wrapped around the results of createInputStream()). Also, the createReader/createWriter methods simply apply wrappers to the results of createInputStream/createOutputStream. Feel free to override these default implementations if a more efficient method is available (e.g. if you're already getting a BufferedInputStream).

Copyright 2006-2007 Partner Software, Inc.

Version:

$Id: AbstractVfsFile.java 2474 2010-03-13 14:28:43Z paul $

Author:

Paul Reavis

Constructor Summary

AbstractVfsFile(Vfs vfs, Path path)
Create a new AbstractVfsFile with the given vfs and path.

Method Summary

void	appendBytes(byte[] bytes) Appends the given bytes to the file.
void	appendText(java.lang.String text) Appends the given text to the end of the file.
long	checksum() Generates a CRC32 checksum for the file's contents.
VfsFile	copyTo(Path newPath) Copies the file to the new path.
VfsFile	copyTo(VfsFile destination) Copies the file to the given VfsFile.
java.io.BufferedOutputStream	createAppendingBufferedOutputStream() Creates a buffered output stream to write to the file.
java.io.BufferedWriter	createAppendingBufferedWriter() Creates a buffered writer to write to the file.
abstract java.io.OutputStream	createAppendingOutputStream() Creates an output stream to append to the file.
java.io.Writer	createAppendingWriter() Creates a writer to append text to the file.
java.io.BufferedInputStream	createBufferedInputStream() Creates a buffered input stream to read from the file.
java.io.BufferedOutputStream	createBufferedOutputStream() Creates a buffered output stream to write to the file.
java.io.BufferedReader	createBufferedReader() Creates a buffered reader to read from the file.
java.io.BufferedWriter	createBufferedWriter() Creates a buffered writer to write to the file.
abstract java.io.InputStream	createInputStream() Creates an input stream to read from the file.
abstract java.io.OutputStream	createOutputStream() Creates an output stream to write to the file.
abstract VfsRandomAccess	createRandomAccess() Creates a random access handle for the file.
java.io.Reader	createReader() Creates a reader to read text from the file.
java.io.Writer	createWriter() Creates a writer to write to the file.
boolean	equals(java.lang.Object nother)
abstract boolean	exists() Whether the Vfs node exists.
Path	getAbsolutePath() The absolute path to the Vfs node.
java.lang.String	getBaseName() Base name of node; this is the part before the '.' if there's a file extension.
VfsDirectory	getDirectory() The VfsDirectory this node is in, or null if it is the root directory.
java.lang.String	getExtension() File extension (the part after the '.' in most file names; includes the '.').
DateAndTime	getLastModified() Returns the date and time the file was last modified.
abstract long	getLastModifiedMillis() Returns the timestamp in milliseconds that the file was last modified.
java.lang.String	getName() Bare name of node.
Path	getPath() The path to the Vfs node.
Vfs	getVfs() The Vfs this node is in.
boolean	isBackup() True if the file is a backup file - commonly this is based on file name patterns like *~ or *.bak.
boolean	isHidden() True if the file is a hidden file - commonly this is based on the file name starting with a ".".
abstract void	make() Creates the node and any ancestor directories needed to contain it.
VfsFile	moveTo(Path newPath) Moves the file to the new path.
VfsFile	moveTo(VfsFile destination) Moves the file to the given VfsFile.
byte[]	readBytes() Reads the entire file in as a byte array.
java.lang.String	readText() Read the contents of the file as text into a String.
java.util.List<java.lang.String>	readTextAsLines() Read the contents of the file as text into a list of Strings, separated by line.
java.lang.String	readTextRange(long start, long end) Returns the text from the given start (inclusive) to the given end (exclusive), in characters.
void	regexReplace(java.util.List<java.lang.String> replacements) Does a regular-expression-based text replacement on the entire file.
void	regexReplace(java.lang.String... replacements) Does a regular-expression-based text replacement on the entire file.
VfsFile	renameTo(java.lang.String name) Renames the file.
void	setLastModified(DateAndTime newLast) If possible, sets the date and time the file was last modified.
abstract void	setLastModifiedMillis(long millis) If possible, sets the date and time the file was last modified in milliseconds.
abstract long	size()
void	textReplace(java.util.List<java.lang.String> replacements) Does a simple text replacement on the entire file.
void	textReplace(java.lang.String... replacements) Does a simple text replacement on the entire file.
java.lang.String	toString()
VfsFile	withExtension(java.lang.String extension)
void	writeBytes(byte[] bytes) Writes the given bytes to the file.
void	writeText(java.lang.String text) Write the given String text to the file.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.partnersoft.io.vfs.VfsFile

remove

Methods inherited from interface com.partnersoft.io.vfs.VfsNode

getUri, getUrl, toFile

Constructor Detail

AbstractVfsFile

public AbstractVfsFile(Vfs vfs,
                       Path path)

Create a new AbstractVfsFile with the given vfs and path.

Parameters:

vfs - Vfs file is in.

path - path to file in Vfs.

Method Detail

exists

public abstract boolean exists()
                        throws java.io.IOException

Description copied from interface: VfsNode

Whether the Vfs node exists. VfsNode objects serve as addresses as well as handles, so they may not point to existing resources. Use VfsNode.make() to create the node if it does not exist.

Specified by:

exists in interface VfsNode

Returns:

true if node exists

Throws:

java.io.IOException - if it can't tell for some reason.

make

public abstract void make()
                   throws java.io.IOException

Description copied from interface: VfsNode

Creates the node and any ancestor directories needed to contain it.

Specified by:

make in interface VfsNode

Throws:

java.io.IOException - if it can't.

size

public abstract long size()
                   throws java.io.IOException

Specified by:

size in interface VfsFile

Throws:

java.io.IOException

createInputStream

public abstract java.io.InputStream createInputStream()
                                               throws java.io.IOException

Description copied from interface: VfsFile

Creates an input stream to read from the file. Starts at the beginning of the file. You must close the stream using InputStream.close() when you are done with it. Note that this stream is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a single bulk read. So, don't use this method unless you know what you're doing - use VfsFile.createBufferedInputStream() instead.

Specified by:

createInputStream in interface VfsFile

Returns:

stream you can read from

Throws:

java.io.IOException - if the read fails

createOutputStream

public abstract java.io.OutputStream createOutputStream()
                                                 throws java.io.IOException

Description copied from interface: VfsFile

Creates an output stream to write to the file. The stream will overwrite any existing contents of the file - in fact, just calling this method will erase any existing contents, so be careful. You must close the stream when you are done with it (OutputStream.close()). Note that this stream is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a bulk write. So, don't use this method unless you know what you're doing - use VfsFile.createBufferedOutputStream() instead.

Specified by:

createOutputStream in interface VfsFile

Returns:

stream you can write to

Throws:

java.io.IOException

createAppendingOutputStream

public abstract java.io.OutputStream createAppendingOutputStream()
                                                          throws java.io.IOException

Description copied from interface: VfsFile

Creates an output stream to append to the file. The stream will NOT overwrite the existing contents of the file; instead it adds to the end. You must close the stream when you are done with it (OutputStream.close()). Note that this stream is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a bulk write. So, don't use this method unless you know what you're doing - use VfsFile.createAppendingBufferedOutputStream() instead.

Specified by:

createAppendingOutputStream in interface VfsFile

Returns:

stream you can write to

Throws:

java.io.IOException

createRandomAccess

public abstract VfsRandomAccess createRandomAccess()
                                            throws java.io.IOException

Description copied from interface: VfsFile

Creates a random access handle for the file. You must close it when you are done with it using com.partnersoft.io.VFSRandomAccess.close().

Specified by:

createRandomAccess in interface VfsFile

Returns:

random access handle for file

Throws:

java.io.IOException - if file can't be accessed

getLastModifiedMillis

public abstract long getLastModifiedMillis()
                                    throws java.io.IOException

Description copied from interface: VfsFile

Returns the timestamp in milliseconds that the file was last modified. This is a more level version of getLastModified(), and may be more efficient since it doesn't create an actual DateAndTime object. If all you care about is the milliseconds anyway (e.g. to store to see if the file changes later), this is your friend. It is exactly equivalent to (though should be faster than) getLastModified().getMillis().

Specified by:

getLastModifiedMillis in interface VfsFile

Throws:

java.io.IOException

setLastModifiedMillis

public abstract void setLastModifiedMillis(long millis)
                                    throws java.io.IOException

Description copied from interface: VfsFile

If possible, sets the date and time the file was last modified in milliseconds. This is generally only done to preserve the characteristics of a file during a copy or mirroring operation. This is exactly equivalent (though should be faster than) setLastModified(new DateAndTime(millis)).

Specified by:

setLastModifiedMillis in interface VfsFile

Throws:

java.io.IOException

withExtension

public VfsFile withExtension(java.lang.String extension)

Specified by:

withExtension in interface VfsFile

createReader

public java.io.Reader createReader()
                            throws java.io.IOException

Description copied from interface: VfsFile

Creates a reader to read text from the file. Starts at the beginning of the file. You must close the reader using Reader.close() when you are done with it. Note that this reader is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a single bulk read. So, don't use this method unless you know what you're doing - use VfsFile.createBufferedReader() instead.

Specified by:

createReader in interface VfsFile

Returns:

reader you can read from

Throws:

java.io.IOException - if the read fails

createWriter

public java.io.Writer createWriter()
                            throws java.io.IOException

Description copied from interface: VfsFile

Creates a writer to write to the file. The writer will overwrite any existing contents of the file - in fact, just calling this method will erase any existing contents, so be careful. You must close the writer when you are done with it (Writer.close()). Note that this writer is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a bulk write. So, don't use this method unless you know what you're doing - use VfsFile.createBufferedWriter() instead.

Specified by:

createWriter in interface VfsFile

Returns:

writer you can write to

Throws:

java.io.IOException

createAppendingWriter

public java.io.Writer createAppendingWriter()
                                     throws java.io.IOException

Description copied from interface: VfsFile

Creates a writer to append text to the file. The writer will NOT overwrite the existing contents of the file; instead it adds to the end. You must close the writer when you are done with it (Writer.close()). Note that this writer is NOT buffered. This is usually a bad thing, unless you are doing your own buffering or doing a bulk write. So, don't use this method unless you know what you're doing - use VfsFile.createAppendingBufferedWriter() instead.

Specified by:

createAppendingWriter in interface VfsFile

Returns:

writer you can write to

Throws:

java.io.IOException

renameTo

public VfsFile renameTo(java.lang.String name)
                 throws java.io.IOException

Description copied from interface: VfsFile

Renames the file. Returns a new VfsFile pointing to the new location. This is not the same as a move; it can only affect the final filename, not the rest of the path.

Specified by:

renameTo in interface VfsFile

Throws:

java.io.IOException

copyTo

public VfsFile copyTo(Path newPath)
               throws java.io.IOException

Description copied from interface: VfsFile

Copies the file to the new path. Returns a new VfsFile pointing to the location of the copy.

Specified by:

copyTo in interface VfsFile

Throws:

java.io.IOException

copyTo

public VfsFile copyTo(VfsFile destination)
               throws java.io.IOException

Description copied from interface: VfsFile

Copies the file to the given VfsFile. Works across Vfs types and filesystems. Returns the destination.

Specified by:

copyTo in interface VfsFile

Throws:

java.io.IOException

moveTo

public VfsFile moveTo(Path newPath)
               throws java.io.IOException

Description copied from interface: VfsFile

Moves the file to the new path. Returns a new VfsFile pointing to the new location.

Specified by:

moveTo in interface VfsFile

Throws:

java.io.IOException

moveTo

public VfsFile moveTo(VfsFile destination)
               throws java.io.IOException

Description copied from interface: VfsFile

Moves the file to the given VfsFile. Works across Vfs types and filesystems. Deletes this file. Returns the destination.

Specified by:

moveTo in interface VfsFile

Throws:

java.io.IOException

checksum

public long checksum()
              throws java.io.IOException

Description copied from interface: VfsFile

Generates a CRC32 checksum for the file's contents.

Specified by:

checksum in interface VfsFile

Throws:

java.io.IOException

writeText

public void writeText(java.lang.String text)
               throws java.io.IOException

Description copied from interface: VfsFile

Write the given String text to the file. Replaces the existing contents completely.

Specified by:

writeText in interface VfsFile

Parameters:

text - text to write to the file.

Throws:

java.io.IOException - if unable to write

readText

public java.lang.String readText()
                          throws java.io.IOException

Description copied from interface: VfsFile

Read the contents of the file as text into a String. Returns the entire contents.

Specified by:

readText in interface VfsFile

Returns:

contents of file

Throws:

java.io.IOException - if unable to read

readTextRange

public java.lang.String readTextRange(long start,
                                      long end)
                               throws java.io.IOException

Description copied from interface: VfsFile

Returns the text from the given start (inclusive) to the given end (exclusive), in characters.

Specified by:

readTextRange in interface VfsFile

Throws:

java.io.IOException

readTextAsLines

public java.util.List<java.lang.String> readTextAsLines()
                                                 throws java.io.IOException

Description copied from interface: VfsFile

Read the contents of the file as text into a list of Strings, separated by line. Returns the entire contents.

Specified by:

readTextAsLines in interface VfsFile

Returns:

contents of file as list of lines

Throws:

java.io.IOException - if unable to read

appendText

public void appendText(java.lang.String text)
                throws java.io.IOException

Description copied from interface: VfsFile

Appends the given text to the end of the file. Does not add linefeeds or carriage returns; you must supply those as part of the text. Do not use this in a loop or other situation where you will call it multiple times for the same file. It is inherently inefficient since it opens an output stream, writes, and closes it. You would be better served, efficiency-wise, by creating a buffered writer and writing to that, then closing it.

Specified by:

appendText in interface VfsFile

Parameters:

text - text to append

Throws:

java.io.IOException - if unable to append

writeBytes

public void writeBytes(byte[] bytes)
                throws java.io.IOException

Description copied from interface: VfsFile

Writes the given bytes to the file. Replaces the entire contents of the file.

Specified by:

writeBytes in interface VfsFile

Parameters:

bytes - byte contents to write

Throws:

java.io.IOException - if unable to write

appendBytes

public void appendBytes(byte[] bytes)
                 throws java.io.IOException

Description copied from interface: VfsFile

Appends the given bytes to the file. Do not use this in a loop or other situation where you will call it multiple times for the same file. It is inherently inefficient since it opens an output stream, writes, and closes it. You would be better served, efficiency-wise, by creating a buffered output stream and writing to that, then closing it.

Specified by:

appendBytes in interface VfsFile

Parameters:

bytes - bytes to append to file

Throws:

java.io.IOException - if unable to append

readBytes

public byte[] readBytes()
                 throws java.io.IOException

Description copied from interface: VfsFile

Reads the entire file in as a byte array. Returns the entire contents.

Specified by:

readBytes in interface VfsFile

Returns:

contents of file as byte array

Throws:

java.io.IOException - if unable to read

textReplace

public void textReplace(java.util.List<java.lang.String> replacements)
                 throws java.io.IOException

Description copied from interface: VfsFile

Does a simple text replacement on the entire file. Processes each line individually, so cannot be used for line break replacement. Uses a temporary file for the results, so can process a file of any length. Does not use regular expressions; use regexReplace(List) for that.

Specified by:

textReplace in interface VfsFile

Parameters:

replacements - list of strings, in alternating original1, replacement1, original2, replacement2, etc. order

Throws:

java.io.IOException

textReplace

public void textReplace(java.lang.String... replacements)
                 throws java.io.IOException

Description copied from interface: VfsFile

Does a simple text replacement on the entire file. Processes each line individually, so cannot be used for line break replacement. Uses a temporary file for the results, so can process a file of any length. Does not use regular expressions; use regexpReplace(String...) for that.

Specified by:

textReplace in interface VfsFile

Parameters:

replacements - array or vararg list of strings, in alternating original1, replacement1, original2, replacement2, etc. order

Throws:

java.io.IOException

regexReplace

public void regexReplace(java.util.List<java.lang.String> replacements)
                  throws java.io.IOException

Description copied from interface: VfsFile

Does a regular-expression-based text replacement on the entire file. Processes each line individually, so cannot be used for line break replacement. Uses a temporary file for the results, so can process a file of any length.

Specified by:

regexReplace in interface VfsFile

Parameters:

replacements - list of strings, in alternating regex1, replacement1, regex2, replacement2, etc. order

Throws:

java.io.IOException

regexReplace

public void regexReplace(java.lang.String... replacements)
                  throws java.io.IOException

Description copied from interface: VfsFile

Does a regular-expression-based text replacement on the entire file. Processes each line individually, so cannot be used for line break replacement. Uses a temporary file for the results, so can process a file of any length.

Specified by:

regexReplace in interface VfsFile

Parameters:

replacements - array or vararg list of strings, in alternating regex1, replacement1, regex2, replacement2, etc. order

Throws:

java.io.IOException

createBufferedInputStream

public java.io.BufferedInputStream createBufferedInputStream()
                                                      throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered input stream to read from the file. Starts at the beginning of the file. You must close the stream using OutputStream.close() when you are done with it. This stream is buffered. This is usually a good thing. So, generally use this method instead of VfsFile.createInputStream() unless you know what you're doing.

Specified by:

createBufferedInputStream in interface VfsFile

Returns:

stream you can read from

Throws:

java.io.IOException - if the read fails

createBufferedOutputStream

public java.io.BufferedOutputStream createBufferedOutputStream()
                                                        throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered output stream to write to the file. The stream will overwrite any existing contents of the file - in fact, just calling this method will erase any existing contents, so be careful. You must close the stream when you are done with it (OutputStream.close()). This stream is buffered, which is usually a good thing. You should generally use this instead of VfsFile.createOutputStream() unless you know what you're doing.

Specified by:

createBufferedOutputStream in interface VfsFile

Returns:

stream you can write to

Throws:

java.io.IOException

createAppendingBufferedOutputStream

public java.io.BufferedOutputStream createAppendingBufferedOutputStream()
                                                                 throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered output stream to write to the file. The stream will NOT overwrite the existing contents of the file; instead it adds to the end. You must close the stream when you are done with it (OutputStream.close()). This stream is buffered, which is usually a good thing. You should generally use this instead of VfsFile.createAppendingOutputStream() unless you know what you're doing.

Specified by:

createAppendingBufferedOutputStream in interface VfsFile

Returns:

stream you can write to

Throws:

java.io.IOException

createBufferedReader

public java.io.BufferedReader createBufferedReader()
                                            throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered reader to read from the file. Starts at the beginning of the file. You must close the reader using Reader.close() when you are done with it. This reader is buffered. This is usually a good thing. So, generally use this method instead of VfsFile.createReader() unless you know what you're doing.

Specified by:

createBufferedReader in interface VfsFile

Returns:

reader you can read from

Throws:

java.io.IOException - if the read fails

createBufferedWriter

public java.io.BufferedWriter createBufferedWriter()
                                            throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered writer to write to the file. The writer will overwrite any existing contents of the file - in fact, just calling this method will erase any existing contents, so be careful. You must close the writer when you are done with it (Writer.close()). This writer is buffered, which is usually a good thing. You should generally use this instead of VfsFile.createWriter() unless you know what you're doing.

Specified by:

createBufferedWriter in interface VfsFile

Returns:

writer you can write to

Throws:

java.io.IOException

createAppendingBufferedWriter

public java.io.BufferedWriter createAppendingBufferedWriter()
                                                     throws java.io.IOException

Description copied from interface: VfsFile

Creates a buffered writer to write to the file. The writer will NOT overwrite the existing contents of the file; instead it adds to the end. You must close the writer when you are done with it (java.io.OutputStream.close()). This writer is buffered, which is usually a good thing. You should generally use this instead of VfsFile.createAppendingWriter() unless you know what you're doing.

Specified by:

createAppendingBufferedWriter in interface VfsFile

Returns:

writer you can write to

Throws:

java.io.IOException

getPath

public Path getPath()

Description copied from interface: VfsNode

The path to the Vfs node.

Specified by:

getPath in interface VfsNode

Returns:

path to Vfs node.

getAbsolutePath

public Path getAbsolutePath()

Description copied from interface: VfsNode

The absolute path to the Vfs node. This has different meanings in different contexts.

Specified by:

getAbsolutePath in interface VfsNode

getVfs

public Vfs getVfs()

Description copied from interface: VfsNode

The Vfs this node is in.

Specified by:

getVfs in interface VfsNode

Returns:

Vfs this node is in.

getName

public java.lang.String getName()

Description copied from interface: VfsNode

Bare name of node. name = baseName + extension

Specified by:

getName in interface VfsNode

Returns:

name of node.

getBaseName

public java.lang.String getBaseName()

Description copied from interface: VfsNode

Base name of node; this is the part before the '.' if there's a file extension. name = baseName + extension

Specified by:

getBaseName in interface VfsNode

getExtension

public java.lang.String getExtension()

Description copied from interface: VfsNode

File extension (the part after the '.' in most file names; includes the '.'). Returns the blank string "" if there is none. name = baseName + extension

Specified by:

getExtension in interface VfsNode

getLastModified

public DateAndTime getLastModified()
                            throws java.io.IOException

Description copied from interface: VfsFile

Returns the date and time the file was last modified. This is exactly equivalent to new DateAndTime(getLastModifiedMillis()).

Specified by:

getLastModified in interface VfsFile

Throws:

java.io.IOException

setLastModified

public void setLastModified(DateAndTime newLast)
                     throws java.io.IOException

Description copied from interface: VfsFile

If possible, sets the date and time the file was last modified. This is generally only done to preserve the characteristics of a file during a copy or mirroring operation. This is exactly equivalent to setLastModifiedMillis(newLast.getMillis()).

Specified by:

setLastModified in interface VfsFile

Throws:

java.io.IOException

getDirectory

public VfsDirectory getDirectory()

Description copied from interface: VfsNode

The VfsDirectory this node is in, or null if it is the root directory.

Specified by:

getDirectory in interface VfsNode

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

isBackup

public boolean isBackup()

Description copied from interface: VfsNode

True if the file is a backup file - commonly this is based on file name patterns like *~ or *.bak.

Specified by:

isBackup in interface VfsNode

isHidden

public boolean isHidden()

Description copied from interface: VfsNode

True if the file is a hidden file - commonly this is based on the file name starting with a ".".

Specified by:

isHidden in interface VfsNode

equals

public boolean equals(java.lang.Object nother)

Overrides:

equals in class java.lang.Object