com.partnersoft.io.vfs
Interface VfsFile

All Superinterfaces:

VfsNode

All Known Implementing Classes:

AbstractVfsFile, NonexistentVfsFile

public interface VfsFile
extends VfsNode

Address and handle for a file in a Vfs.

Vfs systems consist of a hierarchy of VFSDirectories, some of which may contain VFSFiles. A VfsFile is a container of byte and/or text data. You can access it using streams or via direct convenience methods.

Actual VfsFile objects are implemented by a specific VFSModule.

Many of the methods here are convenience methods that should generally simply wrap other methods. AbstractVfsFile implements many of these for you, so you should generally extend that class rather than implementing this interface.

Copyright 2006 Partner Software, Inc.

Author:

Paul Reavis

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.
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.
java.io.InputStream	createInputStream() Creates an input stream to read from the file.
java.io.OutputStream	createOutputStream() Creates an output stream to write to the file.
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.
DateAndTime	getLastModified() Returns the date and time the file was last modified.
long	getLastModifiedMillis() Returns the timestamp in milliseconds that the file was last modified.
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.
void	remove() Removes the 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.
void	setLastModifiedMillis(long millis) If possible, sets the date and time the file was last modified in milliseconds.
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.
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 interface com.partnersoft.io.vfs.VfsNode

exists, getAbsolutePath, getBaseName, getDirectory, getExtension, getName, getPath, getUri, getUrl, getVfs, isBackup, isHidden, make, toFile

Method Detail

size

long size()
          throws java.io.IOException

Throws:

java.io.IOException

withExtension

VfsFile withExtension(java.lang.String extension)

remove

void remove()
            throws java.io.IOException

Removes the file.

Throws:

java.io.IOException

renameTo

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

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.

Throws:

java.io.IOException

moveTo

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

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

Throws:

java.io.IOException

copyTo

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

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

Throws:

java.io.IOException

copyTo

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

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

Throws:

java.io.IOException

moveTo

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

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

Throws:

java.io.IOException

writeText

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

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

Parameters:

text - text to write to the file.

Throws:

java.io.IOException - if unable to write

readText

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

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

Returns:

contents of file

Throws:

java.io.IOException - if unable to read

readTextRange

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

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

Throws:

java.io.IOException

readTextAsLines

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

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

Returns:

contents of file as list of lines

Throws:

java.io.IOException - if unable to read

appendText

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

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.

Parameters:

text - text to append

Throws:

java.io.IOException - if unable to append

writeBytes

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

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

Parameters:

bytes - byte contents to write

Throws:

java.io.IOException - if unable to write

appendBytes

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

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.

Parameters:

bytes - bytes to append to file

Throws:

java.io.IOException - if unable to append

readBytes

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

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

Returns:

contents of file as byte array

Throws:

java.io.IOException - if unable to read

textReplace

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

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.

Parameters:

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

Throws:

java.io.IOException

textReplace

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

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.

Parameters:

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

Throws:

java.io.IOException

regexReplace

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

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.

Parameters:

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

Throws:

java.io.IOException

regexReplace

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

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.

Parameters:

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

Throws:

java.io.IOException

createInputStream

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

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 createBufferedInputStream() instead.

Returns:

stream you can read from

Throws:

java.io.IOException - if the read fails

createBufferedInputStream

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

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 createInputStream() unless you know what you're doing.

Returns:

stream you can read from

Throws:

java.io.IOException - if the read fails

createOutputStream

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

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 createBufferedOutputStream() instead.

Returns:

stream you can write to

Throws:

java.io.IOException

createBufferedOutputStream

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

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 createOutputStream() unless you know what you're doing.

Returns:

stream you can write to

Throws:

java.io.IOException

createAppendingOutputStream

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

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 createAppendingBufferedOutputStream() instead.

Returns:

stream you can write to

Throws:

java.io.IOException

createAppendingBufferedOutputStream

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

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 createAppendingOutputStream() unless you know what you're doing.

Returns:

stream you can write to

Throws:

java.io.IOException

createReader

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

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 createBufferedReader() instead.

Returns:

reader you can read from

Throws:

java.io.IOException - if the read fails

createBufferedReader

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

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 createReader() unless you know what you're doing.

Returns:

reader you can read from

Throws:

java.io.IOException - if the read fails

createWriter

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

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 createBufferedWriter() instead.

Returns:

writer you can write to

Throws:

java.io.IOException

createBufferedWriter

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

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 createWriter() unless you know what you're doing.

Returns:

writer you can write to

Throws:

java.io.IOException

createAppendingWriter

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

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 createAppendingBufferedWriter() instead.

Returns:

writer you can write to

Throws:

java.io.IOException

createAppendingBufferedWriter

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

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 createAppendingWriter() unless you know what you're doing.

Returns:

writer you can write to

Throws:

java.io.IOException

createRandomAccess

VfsRandomAccess createRandomAccess()
                                   throws java.io.IOException

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

Returns:

random access handle for file

Throws:

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

getLastModified

DateAndTime getLastModified()
                            throws java.io.IOException

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

Throws:

java.io.IOException

setLastModified

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

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()).

Throws:

java.io.IOException

getLastModifiedMillis

long getLastModifiedMillis()
                           throws java.io.IOException

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().

Throws:

java.io.IOException

setLastModifiedMillis

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

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)).

Throws:

java.io.IOException

checksum

long checksum()
              throws java.io.IOException

Generates a CRC32 checksum for the file's contents.

Throws:

java.io.IOException