de.infinityloop.util.inout
Class DiskFile

java.lang.Object
  extended by de.infinityloop.util.inout.DiskFile

public class DiskFile
extends java.lang.Object

This class implements a platform neutral container for resource locations, which can be URLs or local file/path specifiers, both relative and absolute, along with the necessary conversion methods to convert from one to the other. It handles all the name encoding, path construction and root volume problems java.io.File has, as well as platform issues.

Also, we can determine whether the 'file' is a folder, whether it is relative, and can calculate the relative path from two DiskFile's.

Version:
1.0
Author:
Christian Roth

Constructor Summary
DiskFile(java.io.File file)
          Constructs from a java.io.File.
DiskFile(java.lang.String s)
          Constructs from a String.
DiskFile(java.lang.String s, boolean folder)
          Construct from a String and additionally explicitly specify whether it's a file or folder.
 
Method Summary
static DiskFile calcAbsoluteDestfile(java.lang.String src, java.lang.String ext, java.lang.String destDirectory, boolean createIntermediateDirs)
          Calculates the absolute file name from various given components.
static java.lang.String calcAbsolutePath(java.lang.String basePath, java.lang.String relativePath)
          Helper: returns the absolute path for the relative one passed in, based on the absolute base path also specified.
static java.lang.String calcRelativePathNative(java.lang.String src, java.lang.String dest, java.lang.String upHierarchyString)
          Helper: returns the relative path from the source directory to the destination directory.
static java.lang.String calcRelativePathURL(java.lang.String src, java.lang.String dest, java.lang.String upHierarchyString)
          Helper: returns the relative path from the source directory to the destination directory in URL format.
static boolean copyFile(java.io.File src, java.io.File dest)
          Copies the file from its original location with the same name to the directory specified.
static boolean copyFile(java.io.InputStream inStream, java.io.File dest)
          Overloaded version of copyFile(File,File), only that the source is an InputStream.
static DiskFile createTemporaryFile(java.lang.String destPath, java.lang.String extension)
          Creates a DiskFile object for a temporary, non-existing file.
 boolean delete()
          Delete this DiskFile.
 boolean deleteRecursively(java.lang.String rootDir)
          Delete this DiskFile.
static DiskFile ensureNotExistingFilename(DiskFile target)
          This method ensures that the passed file name does not yet exist.
 boolean ensurePath()
          Ensures that the given path actually does exist, creating intermediate dirs if necessary.
 boolean exists()
          Checks for real existance of this DiskFile.
 java.lang.String getBaseName()
          retrieves only the basename (i.e. its name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.
 java.lang.String getBaseNameURL()
          retrieves only the basename (i.e. its name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.
 java.lang.String getDevice()
           
 java.lang.String getExtension()
          Returns the extension (excl. the dot) of the file or the empty string, if the file does not have an extension.
 java.io.File getFile()
          Returns the File equivalent (if possible) of this object.
 java.lang.String getGAuthority()
           
 java.lang.String getGDevice()
           
 java.lang.String getGProtocol()
           
 java.lang.String getGQuery()
           
 java.lang.String getGRawPath()
           
 java.io.InputStream getInputStream(boolean doThrow)
          Gets an InputStream to this DiskFile.
 java.lang.String getName()
          retrieves only the name of the specified file.
 java.lang.String getNameURLEncoded()
          retrieves only the name of the specified file, encoded for use in a URL.
 java.io.OutputStream getOutputStream(boolean doThrow)
          Gets resp. creates an OutputStream associated with this DiskFile.
 DiskFile getPathOnly()
          retrieves the path to the specified file (if it is a file), otherwise returns unaltered.
static java.lang.String getPathPrefix(java.io.File f)
          Retrieves the path prefix (which does not include any leading platform specific drive specifier like C:\) from an absolute file name.
 boolean isAbsolute()
          Determines if this object represents an absolute path.
 boolean isFolder()
          Returns whether this object represents a file or a folder.
 boolean isRelative()
          Determines if this object represents a relative path.
 boolean isVisible()
          Checks for visibility of a DiskFile.
static void main(java.lang.String[] args)
          Parses and breaks up the passed URL into its components and returns it in XMLified form so that after (re)parsing that XML code, it can easily be acessed e.g. with XSLT.
 DiskFile makeAbsolute(java.lang.String basePath)
          Returns the File equivalent (if possible) of this relative object.
static java.lang.String makePathString(java.lang.String path)
          Makes a path string from the passed string, i.e. it appends File.separator to it if that's not the last character in the string.
static boolean moveFile(java.lang.String srcfile, java.lang.String destdir)
          Moves the file from its original location with the same name to the directory specified.
static DiskFile PickFileOpen(java.awt.Frame parent, java.lang.String titleText, java.lang.Object defaultLocation, java.util.Vector fileFilters, de.infinityloop.util.Preferences prefsObject)
          Picks a file to be opened.
static DiskFile PickFileOrFolderOpen(java.awt.Frame parent, java.lang.String titleText, java.lang.Object defaultLocation, java.util.Vector fileFilters, de.infinityloop.util.Preferences prefsObject)
          Picks a file or folder to be opened.
static DiskFile PickFileSave(java.awt.Frame parent, java.lang.String titleText, java.lang.Object defaultLocation, java.util.Vector fileFilters, de.infinityloop.util.Preferences prefsObject)
          Picks a file to be saved.
static DiskFile PickFolder(java.awt.Frame parent, java.lang.String titleText, java.lang.Object defaultLocation, java.util.Vector fileFilters, de.infinityloop.util.Preferences prefsObject)
          Picks a folder
 java.lang.StringBuffer readToStringBuffer()
          Reads an ASCII file into memory and returns the contents as a StringBuffer.
 java.lang.StringBuffer readToStringBuffer(java.lang.String encoding)
          Reads a file into memory and returns the contents as a StringBuffer.
 java.util.Stack resolveToNameSequence()
          Resolves the passed file name into a name sequence, splitting at '/' or '\' characters.
 java.lang.String toLocalPathString()
          Retrieves the absolute path to the file designated by this object in local platform naming convention.
 java.lang.String toLocalPathStringNoTrailingSeparator()
           
 java.lang.String toString()
          For debugging
 java.lang.String toURLString()
          makes a file: or other protocol URL equivalent from this object as String.
 java.lang.String toURLStringNoTrailingSeparator()
           
 void writeString(java.lang.String data, java.lang.String encoding, boolean append)
          Write a string to a file, optionally appending.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DiskFile

public DiskFile(java.io.File file)
Constructs from a java.io.File.

Parameters:
file - File object

DiskFile

public DiskFile(java.lang.String s)
Constructs from a String. This may be local platform naming convention, a file: URL, or a relative path.

Parameters:
s - the String identifying the file

DiskFile

public DiskFile(java.lang.String s,
                boolean folder)
Construct from a String and additionally explicitly specify whether it's a file or folder.

Parameters:
s - the String
folder - true if s designates a folder
Method Detail

getDevice

public java.lang.String getDevice()
Returns:
Returns the device portion of this DiskFile object's local name.
Since:
6.0

toLocalPathString

public java.lang.String toLocalPathString()
Retrieves the absolute path to the file designated by this object in local platform naming convention.

Returns:
the local absolute path to this file or the URL notation if it is not the file: protocol.

toLocalPathStringNoTrailingSeparator

public java.lang.String toLocalPathStringNoTrailingSeparator()

toURLString

public java.lang.String toURLString()
makes a file: or other protocol URL equivalent from this object as String.

Returns:
an URL string

toURLStringNoTrailingSeparator

public java.lang.String toURLStringNoTrailingSeparator()

toString

public java.lang.String toString()
For debugging

Overrides:
toString in class java.lang.Object
Returns:
string representation (for debugging)
See Also:
Object.toString()

resolveToNameSequence

public java.util.Stack resolveToNameSequence()
Resolves the passed file name into a name sequence, splitting at '/' or '\' characters. We no longer recognize escapes!


isFolder

public boolean isFolder()
Returns whether this object represents a file or a folder. If the object exists physically, we use file system functions to retriev its type. Otherwise, we rely on the path notation, meaning that if it ends with a folder separator, it must be a folder and a file otherwise.

Returns:
true if it's a folder, false otherwise

getFile

public java.io.File getFile()
Returns the File equivalent (if possible) of this object.

Returns:
null, when no equivalent File can be created

makeAbsolute

public DiskFile makeAbsolute(java.lang.String basePath)
Returns the File equivalent (if possible) of this relative object. To make it absolute, it is handled as being relative to basePath.

Parameters:
basePath - the base path to which this object should be considered relative to; when null, the running user's current directory is used
Returns:
null, when no equivalent can be created, an equivalent File object otherwise

getPathOnly

public DiskFile getPathOnly()
retrieves the path to the specified file (if it is a file), otherwise returns unaltered.

Returns:
null, if the path can not be determined, the path otherwise

getName

public java.lang.String getName()
retrieves only the name of the specified file.

Returns:
null, if the name can not be determined, the file or folder name otherwise

getNameURLEncoded

public java.lang.String getNameURLEncoded()
retrieves only the name of the specified file, encoded for use in a URL.

Returns:
null, if the name can not be determined, the file or folder name otherwise

getBaseName

public java.lang.String getBaseName()
retrieves only the basename (i.e. its name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.

Returns:
null, if the name can not be determined, the basefile name if its is a file, or the name otherwise

getBaseNameURL

public java.lang.String getBaseNameURL()
retrieves only the basename (i.e. its name without path, extension and trailing dot) of the specified file (if it is a file), the name otherwise.

Returns:
null, if the name can not be determined, the basefile name if its is a file, or the name otherwise

getGAuthority

public final java.lang.String getGAuthority()
Returns:
Returns the gAuthority.

getGDevice

public final java.lang.String getGDevice()
Returns:
Returns the gDevice.

getGProtocol

public final java.lang.String getGProtocol()
Returns:
Returns the gProtocol.

getGQuery

public final java.lang.String getGQuery()
Returns:
Returns the gQuery.

getGRawPath

public final java.lang.String getGRawPath()
Returns:
Returns the gRawPath.

ensurePath

public boolean ensurePath()
Ensures that the given path actually does exist, creating intermediate dirs if necessary.


isAbsolute

public boolean isAbsolute()
Determines if this object represents an absolute path.

Returns:
true if this is an absolute path, false otherwise

isRelative

public boolean isRelative()
Determines if this object represents a relative path.

Returns:
true if this is a relative path, false otherwise

getInputStream

public java.io.InputStream getInputStream(boolean doThrow)
                                   throws java.lang.Exception
Gets an InputStream to this DiskFile.

Parameters:
doThrow - if true, this method throws on an error, otherwise it returns null
Returns:
a BufferedInputStream to this file
Throws:
java.lang.Exception

getOutputStream

public java.io.OutputStream getOutputStream(boolean doThrow)
                                     throws java.lang.Exception
Gets resp. creates an OutputStream associated with this DiskFile.

Parameters:
doThrow - if true, this method throws on an error, otherwise it returns null
Returns:
a FileOutputStream to this file
Throws:
java.lang.Exception

exists

public boolean exists()
Checks for real existance of this DiskFile. Only works for local files, not networked files!

Returns:
true if the file actually exists, false otherwise

isVisible

public boolean isVisible()
Checks for visibility of a DiskFile. Only works for local files, not networked files!

Returns:
true if the file is visible, false otherwise

readToStringBuffer

public java.lang.StringBuffer readToStringBuffer()
Reads an ASCII file into memory and returns the contents as a StringBuffer.

Returns:
a StringBuffer containing the file contents

readToStringBuffer

public java.lang.StringBuffer readToStringBuffer(java.lang.String encoding)
Reads a file into memory and returns the contents as a StringBuffer. You must specify the encoding the file is in.

Returns:
a StringBuffer containing the file contents

calcAbsolutePath

public static java.lang.String calcAbsolutePath(java.lang.String basePath,
                                                java.lang.String relativePath)
                                         throws java.io.IOException
Helper: returns the absolute path for the relative one passed in, based on the absolute base path also specified.

Parameters:
basePath - the basepath where relativePath should be interpreted relative to
relativePath - the relative path to make absolute with respect to the base path. If it is already absolute, it is returned unaltered.
Returns:
the absolute path
Throws:
java.io.IOException

calcRelativePathURL

public static java.lang.String calcRelativePathURL(java.lang.String src,
                                                   java.lang.String dest,
                                                   java.lang.String upHierarchyString)
Helper: returns the relative path from the source directory to the destination directory in URL format.

Parameters:
src - the path where we start travelling
dest - the path where we want to be
upHierarchyString - String in relative path that designates "up one hierarchy". Normally, this is "..". The path separator character is automatically appended, so it gets e.g. "../"
Returns:
the relative path from src to dest in file:-URL format. Might be "" if both are the same, or may be absolute if dest is on a different volume.

calcRelativePathNative

public static java.lang.String calcRelativePathNative(java.lang.String src,
                                                      java.lang.String dest,
                                                      java.lang.String upHierarchyString)
Helper: returns the relative path from the source directory to the destination directory.

Parameters:
src - the path where we start travelling
dest - the path where we want to be
upHierarchyString - String in relative path that designates "up one hierarchy". Normally, this is "..". The path separator character is automatically appended, so it gets e.g. "../"
Returns:
the relative path from src to dest in local format. Might be "" if both are the same, or may be absolute if dest is on a different volume.

moveFile

public static boolean moveFile(java.lang.String srcfile,
                               java.lang.String destdir)
Moves the file from its original location with the same name to the directory specified.

This is done by first copying the file there, then deleting the original.

Parameters:
srcfile - the source file to move
destdir - the directory where it should be moved to
Returns:
true if the operation succeeded, false otherwise

copyFile

public static boolean copyFile(java.io.File src,
                               java.io.File dest)
Copies the file from its original location with the same name to the directory specified.

Parameters:
src - the source file to move
dest - the directory where it should be moved to
Returns:
true if the operation succeeded, false otherwise

copyFile

public static boolean copyFile(java.io.InputStream inStream,
                               java.io.File dest)
Overloaded version of copyFile(File,File), only that the source is an InputStream.


makePathString

public static java.lang.String makePathString(java.lang.String path)
Makes a path string from the passed string, i.e. it appends File.separator to it if that's not the last character in the string.

Parameters:
path - the String to make a path string
Returns:
the appropriately modified String

getPathPrefix

public static java.lang.String getPathPrefix(java.io.File f)
Retrieves the path prefix (which does not include any leading platform specific drive specifier like C:\) from an absolute file name.

Parameters:
f - the absolute path
Returns:
the path prefix

PickFileOpen

public static DiskFile PickFileOpen(java.awt.Frame parent,
                                    java.lang.String titleText,
                                    java.lang.Object defaultLocation,
                                    java.util.Vector fileFilters,
                                    de.infinityloop.util.Preferences prefsObject)
Picks a file to be opened.

Parameters:
parent - the parent frame the open dialog has
titleText - the dialog's title
defaultLocation - if a String object, it is interpreted to mean a key which is used to lookup the last location for this operation; if a DiskFile object it means that specific location; if null, we use user.home by default.
fileFilters - should contain a Vector of objects that are javax.swing.filechooser.FileFilter objects, implementing also(!) java.io.FilenameFilter.
Returns:
null, when user cancelled dialog, a DiskFile object otherwise.

PickFileOrFolderOpen

public static DiskFile PickFileOrFolderOpen(java.awt.Frame parent,
                                            java.lang.String titleText,
                                            java.lang.Object defaultLocation,
                                            java.util.Vector fileFilters,
                                            de.infinityloop.util.Preferences prefsObject)
Picks a file or folder to be opened.

Parameters:
parent - the parent frame the open dialog has
titleText - the dialog's title
defaultLocation - if a String object, it is interpreted to mean a key which is used to lookup the last location for this operation; if a DiskFile object it means that specific location; if null, we use user.home by default.
fileFilters - should contain a Vector of objects that are javax.swing.filechooser.FileFilter objects, implementing also(!) java.io.FilenameFilter.
Returns:
null, when user cancelled dialog, a DiskFile object otherwise.

PickFileSave

public static DiskFile PickFileSave(java.awt.Frame parent,
                                    java.lang.String titleText,
                                    java.lang.Object defaultLocation,
                                    java.util.Vector fileFilters,
                                    de.infinityloop.util.Preferences prefsObject)
Picks a file to be saved.

Parameters:
parent - the parent frame the open dialog has
titleText - the dialog's title
defaultLocation - if a String object, it is interpreted to mean a key which is used to lookup the last location for this operation; if a DiskFile object it means that specific location; if null, we use user.home by default.
fileFilters - should contain a Vector of objects that are javax.swing.filechooser.FileFilter objects, implementing also(!) java.io.FilenameFilter.
Returns:
null, when user cancelled dialog, a DiskFile object otherwise.

PickFolder

public static DiskFile PickFolder(java.awt.Frame parent,
                                  java.lang.String titleText,
                                  java.lang.Object defaultLocation,
                                  java.util.Vector fileFilters,
                                  de.infinityloop.util.Preferences prefsObject)
Picks a folder

Parameters:
parent - the parent frame the open dialog has
titleText - the dialog's title
defaultLocation - if a String object, it is interpreted to mean a key which is used to lookup the last location for this operation; if a DiskFile object it means that specific location; if null, we use user.home by default.
fileFilters - should contain a Vector of objects that are javax.swing.filechooser.FileFilter objects, implementing also(!) java.io.FilenameFilter.
Returns:
null, when user cancelled dialog, a DiskFile object otherwise.

calcAbsoluteDestfile

public static DiskFile calcAbsoluteDestfile(java.lang.String src,
                                            java.lang.String ext,
                                            java.lang.String destDirectory,
                                            boolean createIntermediateDirs)
Calculates the absolute file name from various given components.

Parameters:
src - the source file
ext - the extension to add. When this is exactly one space ' ', the extension of the original file is NOT removed, but left as is.
destDirectory - the directory where the file should wind up. If null, same as source file.
createIntermediateDirs - if true, any missing intermediate directories will be created on the fly
Returns:
the absolute destination file

createTemporaryFile

public static DiskFile createTemporaryFile(java.lang.String destPath,
                                           java.lang.String extension)
Creates a DiskFile object for a temporary, non-existing file.

Parameters:
destPath - The file will be created under this path; if this is null, a system-dependent default path will be used.
extension - the file extension to use (including the dot, e.g. ".rtf"); when null, no extension will be used
Returns:
a DiskFile object of the temporary file
Since:
5.3

ensureNotExistingFilename

public static DiskFile ensureNotExistingFilename(DiskFile target)
This method ensures that the passed file name does not yet exist. If it exists, the target file's name is altered by appending "-1", "-2", ... to the file base name (i.e. before any trailing suffix .ext) until the resulting file does not yet exist.

Parameters:
target - the desired, absolute target name to be unique
Returns:
the passed target if it does not exist, or a DiskFile object with an altered name so that it does not exist in the specified location according to the above rules.

getExtension

public java.lang.String getExtension()
Returns the extension (excl. the dot) of the file or the empty string, if the file does not have an extension.

Returns:
the extension or the empty string, when the file does not have an extension

delete

public boolean delete()
Delete this DiskFile.

Returns:
true if the deletion was successful, false otherwise.
Since:
5.3

deleteRecursively

public boolean deleteRecursively(java.lang.String rootDir)
Delete this DiskFile. If it is a folder, its contents is deleted recursively. Only works on local file system.

Parameters:
rootdir - when non-null, specifies a path under which deletions may only occur (for safety reasons). The folder specified may NOT be deleted itself.
Returns:
true if the deletion was successful, false otherwise.
Since:
6.0

writeString

public void writeString(java.lang.String data,
                        java.lang.String encoding,
                        boolean append)
                 throws java.lang.Exception
Write a string to a file, optionally appending. If not specified, the default encoding is UTF-8.

Parameters:
data - the string to write
encoding - the encoding to use for writing; when null or the empty string, UTF-8 is used
append - when true, data is appended if the file already exists
Throws:
java.lang.Exception

main

public static void main(java.lang.String[] args)
Parses and breaks up the passed URL into its components and returns it in XMLified form so that after (re)parsing that XML code, it can easily be acessed e.g. with XSLT.