xdev.io

Class XdevFile

java.lang.Object

java.io.File

xdev.io.XdevFile

All Implemented Interfaces:

Serializable, Comparable<File>

public class XdevFile
extends File

The standard abstract representation of file and directory pathnames in XDEV.

Since:

2.0

Author:

XDEV Software

See Also:

File, Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

Constructors

Constructor and Description
XdevFile(File path) Creates a new XdevFile instance by converting the given pathname string into an abstract pathname.
XdevFile(File parent, String child) Creates a new XdevFile instance from a parent abstract pathname and a child pathname string.
XdevFile(String pathname) Creates a new XdevFile instance by converting the given pathname string into an abstract pathname.
XdevFile(String parent, String child) Creates a new XdevFile instance from a parent pathname string and a child pathname string.
XdevFile(URI uri) Creates a new XdevFile instance by converting the given file: URI into an abstract pathname.

Method Summary

Modifier and Type	Method and Description
XdevFile	copyTo(File dest) Copies this file to dest. If this file is a directory: dest has to be a directory or an IOExeption is thrown a new directory with src's name is created in dest and this file's content is copied to the new directory else if this is a file: if dest is a directory, this file is copied to dest to a file with the same name else if dest is a file, dest is overwritten with this file's content
boolean	createDirectory() This method is a alias for File.mkdirs().
boolean	createFile() Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
String	createHash(String algorithm) Creates a hash value of this file using the specified algorithm.
XdevList<XdevFile>	getChildren() Returns a sorted XdevList of child files of this folder. The directory's parent directory are not included in the result.
static FileSystemView	getFileSystemView() Returns the gateway to the file system.
XdevDate	getLastModified() Return a XdevDate with the time of the last modification of this file.
XdevFile	getParentXdevFile() Return the XdevFile of the parent directory.
long	getSize() This method is a alias for File.length().
String	getSystemDisplayName() Name of a file, directory, or folder as it would be displayed in a system file browser.
String	getSystemDisplaySize() Returns this file's size in a human readable form.
Icon	getSystemIcon() Icon for this XdevFile as it would be displayed in a system file browser.
XdevImage	getSystemImage() Creates a new XdevImage with the system icon for this XdevFile.
static XdevFile[]	getSystemRoots() Returns all root files on this system.
String	getSystemTypeDescription() Type description for a file, directory, or folder as it would be displayed in a system file browser.
boolean	isChildOf(XdevFile parent) Tests if parent is a parent or a parent's parent directory of this file.
boolean	isParentOf(XdevFile child) Tests if this file is a parent or a parent's parent directory of child.
InputStream	openInputStream() Creates a InputStream by opening a connection to this XdevFile.
OutputStream	openOutputStream() This method is a alias for openOutputStream(false).
OutputStream	openOutputStream(boolean append) Creates OutputStream to write to the file represented by the specified XdevFile object.
Reader	openReader() Creates a new Reader, to read from this XdevFile.
Reader	openReader(Charset charset) Creates a new Reader, to read from this XdevFile, using the given charset.
Reader	openReader(String charsetName) Creates a new Reader, to read from this XdevFile.
Writer	openWriter() This method is a alias for openWriter(false).
Writer	openWriter(boolean append) Constructs a Writer object to write on this XdevFile.
Writer	openWriter(boolean append, Charset charset) Constructs a Writer object to write on this XdevFile using the given charset.
Writer	openWriter(boolean append, String charsetName) Constructs a Writer object to write on this XdevFile using the given charset.
Writer	openWriter(Charset charset) Constructs a Writer object to write on this XdevFile using the given charset.
Writer	openWriter(String charsetName) Constructs a Writer object to write on this XdevFile using the given charset.
byte[]	readData() Reads the contents of this file into a byte array.
String	readString() Reads from this file and stores results in a string.
String	readString(String charsetName) Reads from this file and stores results in a string.
boolean	setLastModified(XdevDate date) Sets the last-modified time of the file.
static void	sort(List<? extends File> files) Sorts a list of files in the underlying operating system's manner.
static XdevFile[]	toXdevFile(File... files) Converts an array of java.io.Files to an array of XdevFiles;

Methods inherited from class java.io.File

canExecute, canRead, canWrite, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getFreeSpace, getName, getParent, getParentFile, getPath, getTotalSpace, getUsableSpace, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setExecutable, setExecutable, setLastModified, setReadable, setReadable, setReadOnly, setWritable, setWritable, toPath, toString, toURI, toURL

Methods inherited from class java.lang.Object

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

Constructor Detail

XdevFile

public XdevFile(File path)
         throws NullPointerException

Creates a new XdevFile instance by converting the given pathname string into an abstract pathname. If the given string is the empty string, then the result is the empty abstract pathname.

Parameters:

path - a file with a absolute path

Throws:

NullPointerException - If the path argument is null

XdevFile

public XdevFile(File parent,
                String child)
         throws NullPointerException

Creates a new XdevFile instance from a parent abstract pathname and a child pathname string.

If parent is null then the new XdevFile instance is created as if by invoking the single-argument File constructor on the given child pathname string.

Otherwise the parent abstract pathname is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty abstract pathname then the new XdevFile instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:

parent - The parent abstract pathname

child - The child pathname string

Throws:

NullPointerException - If child is null

XdevFile

public XdevFile(String parent,
                String child)
         throws NullPointerException

Creates a new XdevFile instance from a parent pathname string and a child pathname string.

If parent is null then the new XdevFile instance is created as if by invoking the single-argument File constructor on the given child pathname string.

Otherwise the parent pathname string is taken to denote a directory, and the child pathname string is taken to denote either a directory or a file. If the child pathname string is absolute then it is converted into a relative pathname in a system-dependent way. If parent is the empty string then the new XdevFile instance is created by converting child into an abstract pathname and resolving the result against a system-dependent default directory. Otherwise each pathname string is converted into an abstract pathname and the child abstract pathname is resolved against the parent.

Parameters:

parent - The parent pathname string

child - The child pathname string

Throws:

NullPointerException - If child is null

XdevFile

public XdevFile(String pathname)
         throws NullPointerException

Creates a new XdevFile instance by converting the given pathname string into an abstract pathname. If the given string is the empty string, then the result is the empty abstract pathname.

Parameters:

pathname - A pathname string

Throws:

NullPointerException - If the pathname argument is null

XdevFile

public XdevFile(URI uri)
         throws NullPointerException,
                IllegalArgumentException

Creates a new XdevFile instance by converting the given file: URI into an abstract pathname.

The exact form of a file: URI is system-dependent, hence the transformation performed by this constructor is also system-dependent.

For a given abstract pathname f it is guaranteed that

new File( f .toURI()).equals( f .getAbsoluteFile())

so long as the original abstract pathname, the URI, and the new abstract pathname are all created in (possibly different invocations of) the same Java virtual machine. This relationship typically does not hold, however, when a file: URI that is created in a virtual machine on one operating system is converted into an abstract pathname in a virtual machine on a different operating system.

Parameters:

uri - An absolute, hierarchical URI with a scheme equal to "file", a non-empty path component, and undefined authority, query, and fragment components

Throws:

NullPointerException - If uri is null

IllegalArgumentException - If the preconditions on the parameter do not hold

See Also:

File.toURI(), URI

Method Detail

toXdevFile

public static XdevFile[] toXdevFile(File... files)

Converts an array of java.io.Files to an array of XdevFiles;

Parameters:

files - the array to convert

Returns:

an array of XdevFiles

Since:

4.0

getLastModified

public XdevDate getLastModified()
                         throws SecurityException

Return a XdevDate with the time of the last modification of this file.

Returns:

a XdevDate with the time of the last modification of this file.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

setLastModified

public boolean setLastModified(XdevDate date)
                        throws NullPointerException

Sets the last-modified time of the file.

Parameters:

date - the XdevDate is set as the last modification of this file.

Returns:

true if and only if the operation succeeded; false otherwise

Throws:

NullPointerException - If date is null

getSize

public long getSize()
             throws SecurityException

This method is a alias for File.length().

Returns:

The length, in bytes, of the file denoted by this abstract pathname, or 0L if the file does not exist. Some operating systems may return 0L for pathnames denoting system-dependent entities such as devices or pipes.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file

getParentXdevFile

public XdevFile getParentXdevFile()
                           throws NullPointerException

Return the XdevFile of the parent directory.

Returns:

a XdevFile of the parent directory

Throws:

NullPointerException - If the XdevFile does not have a parent directory

See Also:

getChildren()

isParentOf

public boolean isParentOf(XdevFile child)

Tests if this file is a parent or a parent's parent directory of child.

Parameters:

child - the may-be-child

Returns:

true if this file is a parent or a parent's parent directory of child, false otherwise

isChildOf

public boolean isChildOf(XdevFile parent)

Tests if parent is a parent or a parent's parent directory of this file.

Parameters:

parent - the may-be-parent

Returns:

true if parent is a parent or a parent's parent directory of this file, false otherwise

getChildren

public XdevList<XdevFile> getChildren()
                               throws SecurityException

Returns a sorted XdevList of child files of this folder.
The directory's parent directory are not included in the result.

Returns:

a XdevList of child files in that folder.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the directory

See Also:

getParentXdevFile()

sort

public static void sort(List<? extends File> files)

Sorts a list of files in the underlying operating system's manner.

Parameters:

files - the files to sort

Since:

3.1

createFile

public boolean createFile()
                   throws SecurityException

Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.

Returns:

true if the named file does not exist and was successfully created; false if the named file already exists or any problem occurred.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to the file

See Also:

File.createNewFile()

createDirectory

public boolean createDirectory()
                        throws SecurityException

This method is a alias for File.mkdirs().

Returns:

true if and only if the directory was created, along with all necessary parent directories; false otherwise

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method does not permit verification of the existence of the named directory and all necessary parent directories; or if the SecurityManager.checkWrite(java.lang.String) method does not permit the named directory and all necessary parent directories to be created

getSystemDisplayName

public String getSystemDisplayName()

Name of a file, directory, or folder as it would be displayed in a system file browser. If the name of this XdevFile is not available, the name of this XdevFile is returned.

Returns:

a String the file name as it would be displayed by a native file chooser; null if name is not available

getSystemDisplaySize

public String getSystemDisplaySize()

Returns this file's size in a human readable form.

Returns:

The human readable file size e.g: 1 KB

Since:

3.1

getSystemIcon

public Icon getSystemIcon()

Icon for this XdevFile as it would be displayed in a system file browser. If the icon for this XdevFile is not available, null is returned.

Returns:

an Icon as it would be displayed by a native file chooser; null if icon is not available

getSystemImage

public XdevImage getSystemImage()

Creates a new XdevImage with the system icon for this XdevFile.

Returns:

a new XdevImage with the system icon for this XdevFile; null if icon is not available

getSystemTypeDescription

public String getSystemTypeDescription()

Type description for a file, directory, or folder as it would be displayed in a system file browser. Example from Windows: the "Desktop" folder is described as "Desktop".

Returns:

the file type description as it would be displayed by a native file chooser or null if no native information is available.

openReader

public Reader openReader()
                  throws IOException

Creates a new Reader, to read from this XdevFile.

Returns:

a new Reader

Throws:

IOException - If the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

openReader

public Reader openReader(String charsetName)
                  throws IOException,
                         UnsupportedEncodingException

Creates a new Reader, to read from this XdevFile.

Parameters:

charsetName - The name of a supported Charset

Returns:

a new Reader

Throws:

IOException - If the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

UnsupportedEncodingException - If the named charset is not supported.

Since:

3.1

openReader

public Reader openReader(Charset charset)
                  throws IOException

Creates a new Reader, to read from this XdevFile, using the given charset.

Parameters:

charset - A Charset

Returns:

a new Reader

Throws:

IOException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

Since:

3.1

openWriter

public Writer openWriter()
                  throws IOException

This method is a alias for openWriter(false).

Returns:

a new Writer

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

See Also:

openWriter(boolean)

openWriter

public Writer openWriter(boolean append)
                  throws IOException

Constructs a Writer object to write on this XdevFile. If append is true, then bytes will be written to the end of the file rather than the beginning.

Parameters:

append - if true, then bytes will be written to the end of the file rather than the beginning

Returns:

a Writer object to write on this XdevFile

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

openWriter

public Writer openWriter(String charsetName)
                  throws IOException,
                         UnsupportedEncodingException

Constructs a Writer object to write on this XdevFile using the given charset.

Parameters:

charsetName - The name of a supported Charset

Returns:

a Writer object to write on this XdevFile

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

UnsupportedEncodingException - If the named charset is not supported.

Since:

3.1

openWriter

public Writer openWriter(boolean append,
                         String charsetName)
                  throws IOException,
                         UnsupportedEncodingException

Constructs a Writer object to write on this XdevFile using the given charset. If append is true, then bytes will be written to the end of the file rather than the beginning.

Parameters:

append - if true, then bytes will be written to the end of the file rather than the beginning

charsetName - The name of a supported Charset

Returns:

a Writer object to write on this XdevFile

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

UnsupportedEncodingException - If the named charset is not supported.

Since:

3.1

openWriter

public Writer openWriter(Charset charset)
                  throws IOException

Constructs a Writer object to write on this XdevFile using the given charset.

Parameters:

charset - A Charset

Returns:

a Writer object to write on this XdevFile

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

Since:

3.1

openWriter

public Writer openWriter(boolean append,
                         Charset charset)
                  throws IOException

Constructs a Writer object to write on this XdevFile using the given charset. If append is true, then bytes will be written to the end of the file rather than the beginning.

Parameters:

append - if true, then bytes will be written to the end of the file rather than the beginning

charset - A Charset

Returns:

a Writer object to write on this XdevFile

Throws:

IOException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

Since:

3.1

openInputStream

public InputStream openInputStream()
                            throws FileNotFoundException,
                                   SecurityException

Creates a InputStream by opening a connection to this XdevFile. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its SecurityManager.checkRead(String) method is called with the path represented by the this XdevFile argument as its argument.

If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then a FileNotFoundException is thrown.

Returns:

a new InputStream

Throws:

FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

SecurityException - if a security manager exists and its SecurityManager.checkRead(String) method denies read access to the file.

See Also:

InputStream, FileInputStream

openOutputStream

public OutputStream openOutputStream()
                              throws FileNotFoundException,
                                     SecurityException

This method is a alias for openOutputStream(false).

Returns:

a new OutputStream to write into this XdevFile

Throws:

FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

SecurityException - if a security manager exists and its SecurityManager.checkWrite(String) method denies write access to the file.

See Also:

openOutputStream(boolean)

openOutputStream

public OutputStream openOutputStream(boolean append)
                              throws FileNotFoundException,
                                     SecurityException

Creates OutputStream to write to the file represented by the specified XdevFile object. If the second argument is true, then bytes will be written to the end of the file rather than the beginning. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its SecurityManager.checkWrite(String) method is called with the path represented by the XdevFile argument as its argument.

If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

Parameters:

append - if true, then bytes will be written to the end of the file rather than the beginning

Returns:

a new OutputStream to write into the XdevFile

Throws:

FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

SecurityException - if a security manager exists and its SecurityManager.checkWrite(String) method denies write access to the file.

See Also:

FileOutputStream

readData

public byte[] readData()
                throws IOException

Reads the contents of this file into a byte array.

Returns:

The file's content as a byte array.

Throws:

IOException - if an I/O error occurs

Since:

3.1

readString

public String readString()
                  throws IOException

Reads from this file and stores results in a string.

Returns:

a string containing the read characters.

Throws:

IOException

Since:

3.1

readString

public String readString(String charsetName)
                  throws IOException

Reads from this file and stores results in a string.

Parameters:

charsetName - a name of a character set to use

Returns:

a string containing the read characters.

Throws:

IOException - if an I/O error occurs

Since:

3.1

copyTo

public XdevFile copyTo(File dest)
                throws IOException

Copies this file to dest.

If this file is a directory:

• dest has to be a directory or an IOExeption is thrown
• a new directory with src's name is created in dest and this file's content is copied to the new directory

else if this is a file:

• if dest is a directory, this file is copied to dest to a file with the same name
• else if dest is a file, dest is overwritten with this file's content

Parameters:

dest - the destination file or directory

Returns:

the destination file

Throws:

IOException - if an I/O error occurs

Since:

3.1

createHash

public String createHash(String algorithm)
                  throws IOException

Creates a hash value of this file using the specified algorithm.

Parameters:

algorithm - the name of the hash algorithm to use. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

Returns:

a 32 charaters long hexadecimal String.

Throws:

IOException

getFileSystemView

public static FileSystemView getFileSystemView()

Returns the gateway to the file system.

Returns:

the gateway to the file system.

getSystemRoots

public static XdevFile[] getSystemRoots()

Returns all root files on this system.

 XdevFile[]     roots   = XdevFile.getSystemRoots();
 

Returns:

all root files on this system. The values are dependent of the operating system.

Since:

3.1