org.inria.ns.reflex.modules.io
Class XFile

java.lang.Object
  extended by org.apache.commons.vfs.provider.AbstractFileObject
      extended by org.inria.ns.reflex.modules.io.XFile
All Implemented Interfaces:
FileObject, Unwrappable, XOperable

public class XFile
extends AbstractFileObject
implements XOperable, FileObject, Unwrappable

A file (#io:x-file) that is X-operable according to the Active Tags specification.

Any FileObject(s) given by the methods of this class may be cast safely to an XFile.

To get a file, simply use getXFile(Object)

Author:
Philippe Poulard

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.inria.ns.reflex.structures.Unwrappable
Unwrappable.Unwrapper
 
Field Summary
static long t
           
 
Fields inherited from interface org.inria.ns.reflex.structures.Unwrappable
UNWRAPPER
 
Constructor Summary
XFile(FileObject file)
          Wrap a file in an XFile.
 
Method Summary
static List buildXFileList(File[] files)
          Build an XFile list from a set of files.
static List buildXFileList(FileObject[] files)
          Build an XFile list from a set of files.
 boolean canRenameTo(FileObject newfile)
          Indicates whether this file can be renamed or not.
 void close()
          Closes this file, and its content.
 void copyFrom(FileObject file, FileSelector selector)
          Copies another file and all its descendents to this file.
static InputStream createEmptyInputStream()
          Return an empty input stream.
 void createFile()
          Create a new file based on this file definition if it does not exist.
 void createFolder()
          Create a new folder based on this file definition if it does not exist.
 boolean delete()
          Deletes this file.
 int delete(FileSelector selector)
          Deletes all descendents of this file that match a selector.
 boolean equals(Object obj)
          Test whether 2 files are equal or not.
 boolean exists()
          Indicates whether this file exists or not.
 FileObject[] findFiles(FileSelector selector)
          Finds the set of matching descendents of this file, in depthwise order.
static XFile getAbsoluteXFile(String path)
          Construct an XFile from the given path.
 FileObject getChild(String name)
          Returns a child of this file.
 FileObject[] getChildren()
          Lists the children of this file.
 FileContent getContent()
          Returns this file's content.
static String getEncoding(FileObject file)
          Return the encoding of a file.
 FileSystem getFileSystem()
          Return the file system that owns this file.
 InputSource getInputSource(String publicId)
          Create an input source from this file.
 InputStream getInputStream()
          Returns an input stream to use to read the content of the file.
static XOperator getInstance()
          Get a singleton X-operator for efficiency.
static String getMimeType(FileObject file)
          Return the MIME type of a file.
 FileName getName()
          Return the name of this file.
 OutputStream getOutputStream()
          Returns an output stream to use to write the content of the file.
 FileObject getParent()
          Returns the folder that contains this file.
 String getSpecifiedEncoding()
          Return the encoding specified.
 String getSpecifiedMimeType()
          Return the MIME type specified.
 FileType getType()
          Return the type of this file.
 URL getURL()
          Returns a URL representing this file.
static XFile getXFile(Object object)
          Construct an XFile from the given object.
static XFile getXFile(XFile base, Object object)
          Construct an XFile from the given object.
 XOperator getXOperator()
          Return the X-operator of this object.
 int hashCode()
          Return the hash value of this file.
 boolean isHidden()
          Indicates whether this file is hidden or not.
 boolean isReadable()
          Indicates whether this file is readable or not.
 boolean isWriteable()
          Indicates whether this file is writeable or not.
static void main(String[] args)
          Display the URI schemes available.
 void moveTo(FileObject destFile)
          Move this file.
 FileObject resolveFile(String path)
          Finds a file, relative to this file.
 FileObject resolveFile(String name, NameScope scope)
          Finds a file, relative to this file.
static XFile resolveXFile(XFile base, String uri)
          Resolve an URI (relative or absolute) from a base file.
 boolean setSpecifiedEncoding(String encoding)
          Set the specified encoding.
 boolean setSpecifiedMimeType(String mimeType)
          Set the specified MIME type.
 Object unwrap()
          Unwrap the file contains in this XFile
 
Methods inherited from class org.apache.commons.vfs.provider.AbstractFileObject
findFiles, getFileOperations, getOutputStream, getRandomAccessContent, holdObject, isAttached, isContentOpen, refresh, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.apache.commons.vfs.FileObject
findFiles, getFileOperations, isAttached, isContentOpen, refresh
 

Field Detail

t

public static long t
Constructor Detail

XFile

public XFile(FileObject file)
Wrap a file in an XFile.

Parameters:
file - The file to wrap.
Method Detail

getXFile

public static XFile getXFile(Object object)
                      throws FileSystemException
Construct an XFile from the given object. Suitable for opaque URIs or absolute URLs. Relative URLs should be resolved upon a base file.

Parameters:
object - An object that represent a file.
Returns:
The file, or null.
Throws:
FileSystemException - When the object is not a file, or the scheme is unknown.
See Also:
getXFile(XFile, Object)

getAbsoluteXFile

public static XFile getAbsoluteXFile(String path)
                              throws FileSystemException
Construct an XFile from the given path. Suitable for opaque URIs or absolute URLs.

*** Relative URLs can't be resolved with this method. ***

Parameters:
path - The path to the file.
Returns:
The file, or null if the path is relative.
Throws:
FileSystemException - When a file error occurs.

getXFile

public static XFile getXFile(XFile base,
                             Object object)
                      throws FileSystemException
Construct an XFile from the given object.

Parameters:
base - The base to use if the object to resolve is relative. If null, the file will be resolved regarding the current directory.
object - An object that represent a file.
Returns:
The file, or null.
Throws:
FileSystemException - When the object is not a file, or the scheme is unknown.

resolveXFile

public static XFile resolveXFile(XFile base,
                                 String uri)
                          throws FileSystemException
Resolve an URI (relative or absolute) from a base file.

Parameters:
base - The absolute base file.
uri - The URI to resolve.
Returns:
If the URI is absolute, it is returned as an XFile, otherwise, the base file is used for the resolution with the relative path (that may itself be absolute).
Throws:
FileSystemException - When an I/O error occurs.

getInstance

public static XOperator getInstance()
Get a singleton X-operator for efficiency.

Returns:
A singleton instance of a X-operator.

getXOperator

public XOperator getXOperator()
Return the X-operator of this object.

Specified by:
getXOperator in interface XOperable
Returns:
The non null X-operator of this object.

buildXFileList

public static List buildXFileList(FileObject[] files)
Build an XFile list from a set of files.

Parameters:
files - The set to files to build from.
Returns:
A list of XFiles.

buildXFileList

public static List buildXFileList(File[] files)
Build an XFile list from a set of files.

Parameters:
files - The set to files to build from.
Returns:
A list of XFiles.

getName

public FileName getName()
Return the name of this file.

Specified by:
getName in interface FileObject
Overrides:
getName in class AbstractFileObject
Returns:
The name of this file.
See Also:
FileObject.getName()

getURL

public URL getURL()
           throws FileSystemException
Returns a URL representing this file.

Specified by:
getURL in interface FileObject
Overrides:
getURL in class AbstractFileObject
Returns:
The URL of this file.
Throws:
FileSystemException
See Also:
FileObject.getURL()

exists

public boolean exists()
               throws FileSystemException
Indicates whether this file exists or not.

Specified by:
exists in interface FileObject
Overrides:
exists in class AbstractFileObject
Returns:
true if this file exists, false otherwise.
Throws:
FileSystemException - On error determining if this file exists.
See Also:
FileObject.exists()

isHidden

public boolean isHidden()
                 throws FileSystemException
Indicates whether this file is hidden or not.

Specified by:
isHidden in interface FileObject
Overrides:
isHidden in class AbstractFileObject
Returns:
true if this file is hidden, false otherwise.
Throws:
FileSystemException - On error determining if this file is hidden.
See Also:
FileObject.isHidden()

isReadable

public boolean isReadable()
                   throws FileSystemException
Indicates whether this file is readable or not.

Specified by:
isReadable in interface FileObject
Overrides:
isReadable in class AbstractFileObject
Returns:
true if this file is readable, false otherwise.
Throws:
FileSystemException - On error determining if this file is readable.
See Also:
FileObject.isReadable()

isWriteable

public boolean isWriteable()
                    throws FileSystemException
Indicates whether this file is writeable or not.

Specified by:
isWriteable in interface FileObject
Overrides:
isWriteable in class AbstractFileObject
Returns:
true if this file is writable, false otherwise.
Throws:
FileSystemException - On error determining if this file is writeable.
See Also:
FileObject.isWriteable()

getType

public FileType getType()
                 throws FileSystemException
Return the type of this file.

Specified by:
getType in interface FileObject
Overrides:
getType in class AbstractFileObject
Returns:
The non-null type of this file.
Throws:
FileSystemException - On error determining the file's type.
See Also:
FileObject.getType()

getParent

public FileObject getParent()
                     throws FileSystemException
Returns the folder that contains this file.

Specified by:
getParent in interface FileObject
Overrides:
getParent in class AbstractFileObject
Returns:
The folder that contains this file. Returns null if this file is the root of a file system.
Throws:
FileSystemException - On error finding the file's parent.
See Also:
FileObject.getParent()

getFileSystem

public FileSystem getFileSystem()
Return the file system that owns this file.

Specified by:
getFileSystem in interface FileObject
Overrides:
getFileSystem in class AbstractFileObject
Returns:
The file system that owns this file.
See Also:
FileObject.getFileSystem()

getChildren

public FileObject[] getChildren()
                         throws FileSystemException
Lists the children of this file.

Specified by:
getChildren in interface FileObject
Overrides:
getChildren in class AbstractFileObject
Returns:
A non-null array containing the children of this file. The array is unordered. If the file does not have any children, a zero-length array is returned.
Throws:
FileSystemException - If this file does not exist, or is not a folder, or on error listing this file's children.
See Also:
FileObject.getChildren()

getChild

public FileObject getChild(String name)
                    throws FileSystemException
Returns a child of this file. Note that this method returns null when the child does not exist. This differs from resolveFile( String, NameScope) which never returns null.

Specified by:
getChild in interface FileObject
Overrides:
getChild in class AbstractFileObject
Parameters:
name - The name of the child file.
Returns:
The child file of this file that has a given name, or null.
Throws:
FileSystemException - If this file does not exist, or is not a folder, or on error determining this file's children.
See Also:
FileObject.getChild(java.lang.String)

resolveFile

public FileObject resolveFile(String name,
                              NameScope scope)
                       throws FileSystemException
Finds a file, relative to this file.

Specified by:
resolveFile in interface FileObject
Overrides:
resolveFile in class AbstractFileObject
Parameters:
name - The name of the file to lookup.
scope - The scope to lookup.
Returns:
The file to lookup.
Throws:
FileSystemException - On error parsing the path, or on error finding the file.
See Also:
FileObject.resolveFile(java.lang.String, org.apache.commons.vfs.NameScope)

resolveFile

public FileObject resolveFile(String path)
                       throws FileSystemException
Finds a file, relative to this file. Equivalent to calling resolveFile( path, NameScope.FILE_SYSTEM ).

Specified by:
resolveFile in interface FileObject
Overrides:
resolveFile in class AbstractFileObject
Parameters:
path - The path of the file to locate. Can either be a relative path or an absolute path.
Returns:
The file to lookup.
Throws:
FileSystemException - On error parsing the path, or on error finding the file.
See Also:
FileObject.resolveFile(java.lang.String)

findFiles

public FileObject[] findFiles(FileSelector selector)
                       throws FileSystemException
Finds the set of matching descendents of this file, in depthwise order.

Specified by:
findFiles in interface FileObject
Overrides:
findFiles in class AbstractFileObject
Parameters:
selector - The selector to use to select matching files.
Returns:
The matching files. The files are returned in depthwise order (that is, a child appears in the list before its parent).
Throws:
FileSystemException
See Also:
FileObject.findFiles(org.apache.commons.vfs.FileSelector)

delete

public boolean delete()
               throws FileSystemException
Deletes this file. Does nothing if this file does not exist or if it is a folder that has children. Does not delete any descendents of this file, use delete(FileSelector) for that.

Specified by:
delete in interface FileObject
Overrides:
delete in class AbstractFileObject
Returns:
true if this object has been deleted, false otherwise.
Throws:
FileSystemException - If this file is a non-empty folder, or if this file is read-only, or on error deleting this file.
See Also:
FileObject.delete()

delete

public int delete(FileSelector selector)
           throws FileSystemException
Deletes all descendents of this file that match a selector. Does nothing if this file does not exist. This method is not transactional. If it fails and throws an exception, this file will potentially only be partially deleted.

Specified by:
delete in interface FileObject
Overrides:
delete in class AbstractFileObject
Parameters:
The - selector to use to select which files to delete.
Returns:
The number of files deleted, or -1.
Throws:
FileSystemException - If this file or one of its descendents is read-only, or on error deleting this file or one of its descendents.
See Also:
FileObject.delete(org.apache.commons.vfs.FileSelector)

createFolder

public void createFolder()
                  throws FileSystemException
Create a new folder based on this file definition if it does not exist. Also creates any ancestor folders which do not exist. This method does nothing if the folder already exists.

Specified by:
createFolder in interface FileObject
Overrides:
createFolder in class AbstractFileObject
Throws:
FileSystemException - If the folder already exists with the wrong type, or the parent folder is read-only, or on error creating this folder or one of its ancestors.
See Also:
FileObject.createFolder()

createFile

public void createFile()
                throws FileSystemException
Create a new file based on this file definition if it does not exist. Also creates any ancestor folders which do not exist. This method does nothing if the file already exists and is a file.

Specified by:
createFile in interface FileObject
Overrides:
createFile in class AbstractFileObject
Throws:
FileSystemException - If the file already exists with the wrong type, or the parent folder is read-only, or on error creating this file or one of its ancestors.
See Also:
FileObject.createFile()

copyFrom

public void copyFrom(FileObject file,
                     FileSelector selector)
              throws FileSystemException
Copies another file and all its descendents to this file. If this file does not exist, it is created. Its parent folder is also created, if necessary. If this file does exist, it is deleted first. This method is not transactional. If it fails and throws an exception, this file will potentially only be partially copied.

Specified by:
copyFrom in interface FileObject
Overrides:
copyFrom in class AbstractFileObject
Parameters:
file - The file to copy.
selector - The selector to use to select which files to copy.
Throws:
FileSystemException - If this file is read-only, or if the source file does not exist, or on error copying the file.
See Also:
FileObject.copyFrom(org.apache.commons.vfs.FileObject, org.apache.commons.vfs.FileSelector)

moveTo

public void moveTo(FileObject destFile)
            throws FileSystemException
Move this file.

Specified by:
moveTo in interface FileObject
Overrides:
moveTo in class AbstractFileObject
Parameters:
destFile - The destination.
Throws:
FileSystemException - If this file is read-only, or if the source file does not exist, or on error moving the file.
See Also:
FileObject.moveTo(org.apache.commons.vfs.FileObject)

canRenameTo

public boolean canRenameTo(FileObject newfile)
Indicates whether this file can be renamed or not.

Specified by:
canRenameTo in interface FileObject
Overrides:
canRenameTo in class AbstractFileObject
Returns:
true if this file can be renamed, false otherwise.
See Also:
FileObject.canRenameTo(org.apache.commons.vfs.FileObject)

getContent

public FileContent getContent()
                       throws FileSystemException
Returns this file's content. The FileContent returned by this method can be used to read and write the content of the file. This method can be called if the file does not exist, and the returned FileContent can be used to create the file by writing its content.

Specified by:
getContent in interface FileObject
Overrides:
getContent in class AbstractFileObject
Returns:
The content of this file.
Throws:
FileSystemException - On error getting this file's content.
See Also:
FileObject.getContent()

close

public void close()
           throws FileSystemException
Closes this file, and its content. This method is a hint to the implementation that it can release any resources asociated with the file. The file object can continue to be used after this method is called.

Specified by:
close in interface FileObject
Overrides:
close in class AbstractFileObject
Throws:
FileSystemException - On error closing the file.
See Also:
FileObject.close()

unwrap

public Object unwrap()
Unwrap the file contains in this XFile

Specified by:
unwrap in interface Unwrappable
Returns:
The file object wrapped.
See Also:
Unwrappable.unwrap(), FileObject

createEmptyInputStream

public static InputStream createEmptyInputStream()
Return an empty input stream.

Returns:
An empty input stream.

getInputStream

public InputStream getInputStream()
                           throws FileSystemException
Returns an input stream to use to read the content of the file.

Overrides:
getInputStream in class AbstractFileObject
Returns:
The input stream to read from.
Throws:
FileSystemException
See Also:
AbstractFileObject.getInputStream()

getOutputStream

public OutputStream getOutputStream()
                             throws FileSystemException
Returns an output stream to use to write the content of the file.

Overrides:
getOutputStream in class AbstractFileObject
Returns:
The output stream to write to.
Throws:
FileSystemException
See Also:
AbstractFileObject.getOutputStream()

getInputSource

public InputSource getInputSource(String publicId)
                           throws FileSystemException
Create an input source from this file.

Parameters:
publicId - The public ID to set to the input source, or null if not specified.
Returns:
An input source from this file.
Throws:
FileSystemException - When an I/O error occurs.

getEncoding

public static String getEncoding(FileObject file)
                          throws FileSystemException
Return the encoding of a file.

Do not use this method on XFiles : use instead XMaster.getAttributes(xfile).get(IONames.ENCODING_QNAME)

Parameters:
file - The file.
Returns:
The non-null encoding : either those set explicitely, or those supplied by the underlying file system, or the empty string.
Throws:
FileSystemException - When an I/O error occurs.

getSpecifiedEncoding

public String getSpecifiedEncoding()
Return the encoding specified. If no encoding was specified, this method return null, but it is also possible to get the encoding supplied by the underlying file system by using its @io:encoding attribute (use XMaster.getAttributes(this).get(IONames.ENCODING_QNAME)).

Returns:
The encoding explicitely specified.

setSpecifiedEncoding

public boolean setSpecifiedEncoding(String encoding)
Set the specified encoding. It is stored within the file's attributes. Note that internally, the key of the encoding is not the io:encoding QName but its expanded form.

Parameters:
encoding - The encoding.
Returns:
true if the underlying file system accept attributes, false otherwise.
See Also:
IONames.ENCODING_EXPANDED_QNAME

getMimeType

public static String getMimeType(FileObject file)
                          throws FileSystemException
Return the MIME type of a file.

Do not use this method on XFiles : use instead XMaster.getAttributes(xfile).get(IONames.MIME_TYPE_QNAME)

Parameters:
file - The file.
Returns:
The non-null MIME type : either those set explicitely, or those supplied by the underlying file system, or the empty string.
Throws:
FileSystemException - When an I/O error occurs.

getSpecifiedMimeType

public String getSpecifiedMimeType()
Return the MIME type specified. If no MIME type was specified, this method return null, but it is also possible to get the MIME type supplied by the underlying file system by using its @io:mime-type attribute (use XMaster.getAttributes(this).get(IONames.MIME_TYPE_QNAME)).

Returns:
The MIME type explicitely specified.

setSpecifiedMimeType

public boolean setSpecifiedMimeType(String mimeType)
Set the specified MIME type. It is stored within the file's attributes. Note that internally, the key of the MIME type is not the io:mime-type QName but its expanded form.

Parameters:
mimeType - The MIME type.
Returns:
true if the underlying file system accept attributes, false otherwise.
See Also:
IONames.MIME_TYPE_EXPANDED_QNAME

equals

public boolean equals(Object obj)
Test whether 2 files are equal or not.

Overrides:
equals in class Object
Returns:
true or false
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Return the hash value of this file.

Overrides:
hashCode in class Object
Returns:
The hash value of this file.
See Also:
Object.hashCode()

main

public static void main(String[] args)
Display the URI schemes available.

Parameters:
args - Unused.