ccs.cpc
Class VFile

java.lang.Object
  ccs.cpc.VFile

Direct Known Subclasses:

ArchVFile, DiskVFile, ResultsVFile, ResultWrapperVFile, ZipVFile

public abstract class VFile
extends java.lang.Object

"Virtual file" - provides a common interface between files held on disk and those in archive virtual-filesystems. Implemented by ArchVFile, DiskVFile, ResultsVFile and ZipVFile.

A VFile is represented by two elements: a VDevice on which it sits, and its path within the "Filesystem" on that VDevice. A VDevice specifies a separator character. This separates directories from each other. The root directory is represented by a single separator character. The name of any (sub-) directory will end in a separator. The name of an actual file will not. (This stipulation will do to distinguish between subdirs and files if you have nothing else). The "path" of a file or directory is the complete specification excluding the VDevice. The "name" of a file or directory is everything on the path after the last separator (for a file; last-but-one for a directory since their paths end in a separator). This is not exactly how File behaves, for one - beware.

Nested Class Summary

static class	VFile.BasicRSSorter
static class	VFile.ExtnSorter
static class	VFile.NameSorter

Field Summary

int	hitpoints Undocumented.
boolean	isSelected Undocumented.

Constructor Summary

VFile(VDevice device, VFile parent, java.lang.String path, boolean isDirectory)
Construct a VFile given a device and a complete path as described above.

Method Summary

abstract void	acceptReal(java.lang.String leafname, ccs.utils.SwappingBuffer data) Directories: copy this data into yourself, creating a VFile for it.
void	acceptVirtual(VFile leaf) Directories: accept this VFile.
abstract boolean	contains(java.lang.String leafname) Directories: have you a file called this?
ccs.http.HProgressMonitor	createRealiseMonitor()
void	disposeRealiseMonitor(ccs.http.HProgressMonitor rmon)
boolean	equals(java.lang.Object o)
java.lang.String	fsanitise(java.lang.String name) Some subclasses may support filenames which aren't supported by Files.
abstract VFile	getContainee(java.lang.String leafname) Directories: you contain this, we'd like it.
abstract VFile[]	getContents() Directories: your contents please.
java.lang.String	getDecoratedName() A complete representation of the VFile.
VDevice	getDevice() return the VDevice this sits on.
java.lang.String	getDisplayName(VFile vf) Directories: return the display name of the supplied VFile.
java.lang.String	getID() Returns a unique ID for the file.
abstract VFileMeta	getMetadata() Return metadata for yourself, if available.
java.lang.String	getName() Return the leaf name (ie path - parent).
VFile	getParent() return the parent object.
java.lang.String	getPath() return the complete path.
abstract long	getSize() Files: return your size, if known, else -1L.
VFile	getTrackingParent() Return your parent folder for tracking purposes.
int	hashCode()
protected boolean	hasInternalSeparator(java.lang.String name) Whether a file name contains an internal path-separator char.
boolean	isDir() Is this a directory?
abstract boolean	isExist() Does this file still exist?
boolean	isRealiseInstant() For leaf nodes: can you realise a file instantly?
abstract boolean	isWritable() whether this vfile can be updated (i.e. virtualised).
abstract void	mkdir(java.lang.String leafname) Directories: create this subdir.
protected java.lang.String	normaliseName(java.lang.String name, boolean isFolder) Normalise the name of a leaf node.
void	postrecursionHook(boolean isRoot) Directories: we've finished recursing through you.
void	prerecursionHook(boolean isRoot) Directories: prepare to be recursed through.
abstract ccs.utils.SwappingBuffer	realiseAsBuffer() For leaf nodes, put your data into a SwappingBuffer.
abstract java.io.File	realiseAsFile() For leaf nodes: turn this VFile into a disk File.
abstract void	rename(VFile vf, java.lang.String newname) Directories: rename the attached VFile to the name given.
java.lang.String	toString()
abstract void	virtualiseFromFile(java.io.File f, boolean maybeChanged) For leaf nodes, your contents becomes the contents of the supplied physical file (which is usually an updated form of the result of a realise() earlier).
abstract void	virtualiseFromWad(byte[] wad, boolean maybeChanged) For leaf nodes, your contents become the contents of the supplied wad.
abstract void	wipe(VFile vf) Directories: wipe this VFile and its contents from the face of the world.

Methods inherited from class java.lang.Object

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

Field Detail

isSelected

public boolean isSelected

Undocumented. Reserved. Don't touch.

hitpoints

public int hitpoints

Undocumented. Reserved. Don't touch.

Constructor Detail

VFile

public VFile(VDevice device,
             VFile parent,
             java.lang.String path,
             boolean isDirectory)

Construct a VFile given a device and a complete path as described above. Exceptionally, the rule that directory names must end in a separator does not apply here - either with or without is OK. Exception is the root directory, whose path cannot be empty.

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public final boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public final int hashCode()

Overrides:

hashCode in class java.lang.Object

fsanitise

public java.lang.String fsanitise(java.lang.String name)

Some subclasses may support filenames which aren't supported by Files. This routine attempts to sanitise unsupported names into their supported equivalents by escaping characters which commonly cause problems on filesystems.

createRealiseMonitor

public final ccs.http.HProgressMonitor createRealiseMonitor()
                                                     throws java.io.IOException

Throws:

java.io.IOException

disposeRealiseMonitor

public final void disposeRealiseMonitor(ccs.http.HProgressMonitor rmon)

realiseAsFile

public abstract java.io.File realiseAsFile()
                                    throws java.io.IOException

For leaf nodes: turn this VFile into a disk File. This should only be used where a file is really necessary (e.g. external viewers). For all other uses, prefer realiseAsBuffer to suppress redundant copies. This is an identity operation for DiskVFiles.

Throws:

java.io.IOException

isRealiseInstant

public boolean isRealiseInstant()

For leaf nodes: can you realise a file instantly? Default false.

virtualiseFromFile

public abstract void virtualiseFromFile(java.io.File f,
                                        boolean maybeChanged)
                                 throws java.io.IOException

For leaf nodes, your contents becomes the contents of the supplied physical file (which is usually an updated form of the result of a realise() earlier). any copy other than yourself must vanish. maybeChanged is true if the operation for which it was realise might have changed it - if false no update is necessary. A NOP for DiskVFiles, an update() and FileKill for ArchVFiles.

Throws:

java.io.IOException

realiseAsBuffer

public abstract ccs.utils.SwappingBuffer realiseAsBuffer()
                                                  throws java.io.IOException

For leaf nodes, put your data into a SwappingBuffer. The preferred method of access to data.

Throws:

java.io.IOException

virtualiseFromWad

public abstract void virtualiseFromWad(byte[] wad,
                                       boolean maybeChanged)
                                throws java.io.IOException

For leaf nodes, your contents become the contents of the supplied wad. See virtualiseFromFile.

Throws:

java.io.IOException

isWritable

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

whether this vfile can be updated (i.e. virtualised).

Throws:

java.io.IOException

getPath

public final java.lang.String getPath()

return the complete path.

getParent

public final VFile getParent()

return the parent object. The root has null parent.

getName

public final java.lang.String getName()

Return the leaf name (ie path - parent).

getDevice

public final VDevice getDevice()

return the VDevice this sits on.

getID

public final java.lang.String getID()

Returns a unique ID for the file.

getDecoratedName

public final java.lang.String getDecoratedName()

A complete representation of the VFile. Used when the VFile appears in a result set.

isExist

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

Does this file still exist?

Throws:

java.io.IOException

isDir

public final boolean isDir()

Is this a directory?

getDisplayName

public java.lang.String getDisplayName(VFile vf)

Directories: return the display name of the supplied VFile. This API is targeted at the ResultsVFile; all regular VFiles can use the default.

contains

public abstract boolean contains(java.lang.String leafname)
                          throws java.io.IOException

Directories: have you a file called this? Directory with final separator.

Throws:

java.io.IOException

getContainee

public abstract VFile getContainee(java.lang.String leafname)
                            throws java.io.IOException

Directories: you contain this, we'd like it. Directory with final separator.

Throws:

java.io.IOException

getContents

public abstract VFile[] getContents()
                             throws java.io.IOException

Directories: your contents please.

Throws:

java.io.IOException

mkdir

public abstract void mkdir(java.lang.String leafname)
                    throws java.io.IOException

Directories: create this subdir. The name may or may not have a terminal separator.

Throws:

java.io.IOException

acceptReal

public abstract void acceptReal(java.lang.String leafname,
                                ccs.utils.SwappingBuffer data)
                         throws java.io.IOException

Directories: copy this data into yourself, creating a VFile for it. This is the basis for moving / copying. Implementations should tolerate (and strip out) any terminal separator character.

Throws:

java.io.IOException

acceptVirtual

public void acceptVirtual(VFile leaf)
                   throws java.io.IOException

Directories: accept this VFile. Only applicable to inhabitants of Result sets and any other (currently undefined) VDevice for which isReal() is false.

Throws:

java.io.IOException

wipe

public abstract void wipe(VFile vf)
                   throws java.io.IOException,
                          ccs.LoseException,
                          ccs.ArghException

Directories: wipe this VFile and its contents from the face of the world. It never existed. If the VFile is a directory, it must be empty.

Throws:

java.io.IOException

ccs.LoseException

ccs.ArghException

rename

public abstract void rename(VFile vf,
                            java.lang.String newname)
                     throws java.io.IOException,
                            ccs.LoseException,
                            ccs.ArghException

Directories: rename the attached VFile to the name given. The VFile might be a folder. The name may or may not have a terminal separator; implementations should tolerate any combination. (Folder with / without, file with / without).

Throws:

java.io.IOException

ccs.LoseException

ccs.ArghException

getMetadata

public abstract VFileMeta getMetadata()
                               throws java.io.IOException

Return metadata for yourself, if available. Else null.

Throws:

java.io.IOException

getSize

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

Files: return your size, if known, else -1L. This is part of what you need to return for getMetadata - hopefully this is slightly lighter weight.

Throws:

java.io.IOException

getTrackingParent

public VFile getTrackingParent()

Return your parent folder for tracking purposes. For result sets; everyone else can use the default.

prerecursionHook

public void prerecursionHook(boolean isRoot)

Directories: prepare to be recursed through. The default implementation does nothing (DiskVFiles need this hook). isRoot is set when this VFile is the root of the recursion, i.e. the PWD at the time. The rules for this are a bit different.

postrecursionHook

public void postrecursionHook(boolean isRoot)

Directories: we've finished recursing through you. The default implementation does nothing (DiskVFiles need this hook).

normaliseName

protected java.lang.String normaliseName(java.lang.String name,
                                         boolean isFolder)

Normalise the name of a leaf node. This consists of: a) decorating the name of a folder by adding a terminal separator; b) removing any terminal separator from the name of a non-folder; c) objecting to '?' characters in folder names (these tend to cause bustage); d) objecting to absolute paths; e) objecting to "." or ".." as names. NB. path separator chars within the name are not checked; under some circumstances this is OK. Use hasInternalSeparator to check for this if you have a problem with it.

Parameters:

name - The name to be normalised

isFolder - Whether this is the name of a folder.

Returns:

The normalised name.

hasInternalSeparator

protected boolean hasInternalSeparator(java.lang.String name)

Whether a file name contains an internal path-separator char. Terminal separator chars (which decorate folder names) don't count.

Parameters:

name - The name to check.

Returns:

As stated.