textbender.a.r.page.navdo
Class VersionedFile

java.lang.Object
  java.io.File
      VersionedFile

All Implemented Interfaces:

Serializable, Comparable<File>

Direct Known Subclasses:

NewSv1File

@ThreadSafe
public class VersionedFile
extends File

A modified version of an original working file. Its filename is a mangled form of the original. Its location is the same directory, so relative links to other files are unbroken.

Each modification of the original creates a new series of versioned files. Each modification of a versioned file creates a new versioned file in the same series. For example, here is an original file, and a single series:

     myfile.xht
     .myfile_navdo-0v0.xht
     .myfile_navdo-0v1.xht
     .myfile_navdo-0v2.xht
      ~ ~ ~
     

Versioned filenames follow the general pattern:

     .BODY_navdo-SvV(DOTX)?
     

     where:

     . (dot) prefix is actually ~ (tilde) on Windows
     BODY is originalNameBody
     S is series
     V is version
     DOTX is originalNameDotExtension
     

Version 1 is the initial modification of the series. Version 0 is the baseline copy of the original. It is created at the same time as version 1. It serves to store the original file contents, in case the original file is subsequently overwritten (by saving one of the modified versions, for example).

Re-modifying the original file — by reloading it in the browser, for example — results in a new series. In this case, the navigation history might look something like:

     myfile.xht
     .myfile_navdo-0v0.xht
     .myfile_navdo-0v1.xht
     .myfile_navdo-0v2.xht
      ~ ~ ~
     myfile.xht
     .myfile_navdo-1v0.xht
     .myfile_navdo-1v1.xht
     .myfile_navdo-1v2.xht
      ~ ~ ~
     

Re-modifying a versioned file — by reloading it in the browser, for example — results in a new versioned file. New versioned files are always given new numbers; old ones are never overwritten. All versioned files are deleted when the VM exits.

New versioned files are created using after. It is important to make use of initRedirect, as well

See Also:

Serialized Form

Field Summary

(package private) static String	DISCRIMINATOR Unique discriminator in the name of each versioned file.
static Object	loadAsNewVersion_releaseReason
static Pattern	NAME_PATTERN Matches the simple (end-of-path) name of a versioned file.
(package private) String	originalNameBody Body part of the simple name of the original file.
(package private) String	originalNameDotExtension Dot-extension of original file.
(package private) int	series Series number of this versioned file.
(package private) int	version Version number of this versioned file.

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

VersionedFile(File originalFile, int series, String originalNameBody, String discriminator, int version, String originalNameDotExtension)
Creates a VersionedFile.

Method Summary

static VersionedFile	after(File oldFile) Creates a VersionedFile.
static VersionedFile	fromFile(File file) Returns the file as a VersionedFile; or null if it is not actually a versioned file.
static File	getOrCreateDocumentAsModifiableFile(PageVisit pageVisit) If the current page source is local, returns it as a file.
boolean	initRedirect(RhiWindow window) If this is a new series, initializes it and redirects the browser to the first versioned file.
void	loadAsNewVersion(PageVisit pageVisit) Loads the newly created versioned file into the browser, for initial viewing.
File	originalFile() Original file of the series, typically the user's working document.
void	saveToOriginal() Saves this versioned file's contents to the original file.

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, toString, toURI, toURL

Methods inherited from class java.lang.Object

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

Field Detail

loadAsNewVersion_releaseReason

public static final Object loadAsNewVersion_releaseReason

See Also:

loadAsNewVersion(PageVisit)

NAME_PATTERN

public static final Pattern NAME_PATTERN

Matches the simple (end-of-path) name of a versioned file. Does not match transient new-Sv1 files, however.

DISCRIMINATOR

static final String DISCRIMINATOR

Unique discriminator in the name of each versioned file.

See Also:

Constant Field Values

originalNameBody

final String originalNameBody

Body part of the simple name of the original file.

See Also:

FileX.BODY_DOTX_PATTERN

originalNameDotExtension

final String originalNameDotExtension

Dot-extension of original file. May be empty.

See Also:

FileX.BODY_DOTX_PATTERN

series

final int series

Series number of this versioned file.

version

final int version

Version number of this versioned file.

Constructor Detail

VersionedFile

VersionedFile(File originalFile,
              int series,
              String originalNameBody,
              String discriminator,
              int version,
              String originalNameDotExtension)

Creates a VersionedFile.

Method Detail

after

public static VersionedFile after(File oldFile)
                           throws IOException

Creates a VersionedFile. Physically creates the empty file too, as a side-effect. Usage:

• VersionedFile newFile = VersionedFile.after(oldFile);
• write modified content to newFile
• newFile.load() // show to the user

The physical file is deleted either at VM exit, or sooner in the case of a transient new-Sv1 file.

Parameters:

oldFile - prior to modification

Throws:

IOException

See Also:

initRedirect(RhiWindow)

fromFile

public static VersionedFile fromFile(File file)

Returns the file as a VersionedFile; or null if it is not actually a versioned file.

getOrCreateDocumentAsModifiableFile

public static File getOrCreateDocumentAsModifiableFile(PageVisit pageVisit)

If the current page source is local, returns it as a file.

In future, this method might download a remote source to a new local file. Currently, it does not. Currently, only local files are supported.

Throws:

UnsupportedOperationException - if the current page is remote

initRedirect

public final boolean initRedirect(RhiWindow window)
                           throws IOException

If this is a new series, initializes it and redirects the browser to the first versioned file. Otherwise does nothing. This method ought to be called for every newly loaded page.

Returns:

true if redirection was performed; false otherwise

Throws:

IOException

loadAsNewVersion

public final void loadAsNewVersion(PageVisit pageVisit)

Loads the newly created versioned file into the browser, for initial viewing. Sets the page visit release reason to loadAsNewVersion_releaseReason. Takes care of any multi-step load requirements, involving redirection. (For these reasons, use this method rather than loading the file by name.)

originalFile

public final File originalFile()

Original file of the series, typically the user's working document.

saveToOriginal

public final void saveToOriginal()
                          throws IOException

Saves this versioned file's contents to the original file. In future, this method will implement an overwrite guard, to avoid clobbering file content that was generated by another process; but currently it does not.

Throws:

IOException