com.borland.primetime.vfs
Class Url

java.lang.Object
  |
  +--com.borland.primetime.vfs.Url

public final class Url

extends java.lang.Object

implements java.lang.Comparable

The Url class defines immutable resource references similar to the JDK URL class.

The Url class also serves as the registration point for Filesystem implementations:

• The method registerFilesystem associates a Url protocol (eg: "file") with a concrete implementation of the Filesystem class. Once registered, a filesystem cannot be unregistered.
• The findFilesystem method used by the Url maps all unrecognized protocols to null which will cause exceptions to be thrown when constructing Url instances. It is recommended that the constants FileFilesystem.PROTOCOL, ZipFilesystem.PROTOCOL, and NewFilesystem.PROTOCOL be used to avoid generating run-time errors.

The Url class differs from the JDK URL in a number of important ways:

• The protocol specified for a Url must map to a Filesystem instance registered via registerFilesystem.
• The form of a Url is always either <protocol>://<host>/<file> or <protocol>://<host>/<file>#<anchor> without exception. Any other format is rejected, and Url's toString method will never use any shortcuts in this representation.
• The <file> portion of the Url must use / as the subpath separator, but no other characters are translated. Notably, the Win32 drive seperator character (:) is left as a part of the <file> portion of a Url.
• Comparisons among Url instances are case dependant for the <protocol>, <host>, and <anchor> portions. The <file> portion is compared according to rules appropriate to the underlying filesystem.
• The character escaping used for non-printing characters along with '#' '/' and ':' in the file, host and anchor portions does not follow the formal URL specification. Instead the standard Strings.StringEncoding mechanism is used to map '#' to '%N', ';' to '%S' and ':' to '%|' along with the usual non-printing character mappings using '%' as the escape character.

Field Summary

static Url[]	EMPTY_ARRAY
static Strings.StringEncoding	URL_ENCODING

Constructor Summary

Url(java.io.File file)
Create a new Url from an existing java.io.File object, using "file" for the protocol, an empty String for the host and no anchor.

Url(Filesystem filesystem, java.lang.String host, java.lang.String file, java.lang.String anchor)
Create a new Url from the four components supplied.

Url(java.lang.String url)
Create a new Url by parsing a complete Url string in either of two forms: <protocol>://<host>/<file> or <protocol>://<host>/<file>#<anchor>

Url(java.lang.String protocol, java.lang.String file)
Create a new Url from the two components supplied, an empty String for the host and no anchor.

Url(java.lang.String protocol, java.lang.String host, java.lang.String file)
Create a new Url from the three components supplied and no anchor.

Url(java.lang.String protocol, java.lang.String host, java.lang.String file, java.lang.String anchor)
Create a new Url from the four components supplied.

Method Summary

int	compareTo(java.lang.Object other)
boolean	equals(java.lang.Object other) Retrieve the Url's anchor.
static Filesystem	findFilesystem(java.lang.String protocol) Find the filesystem registered for the protocol associated with the given Url.
java.lang.String	getAnchor() Retrieve the Url's anchor.
java.lang.String	getFile() Retrieve the Url's file.
java.lang.String	getFileExtension() Retrieve the file extension portion of a Url's file.
java.io.File	getFileObject() Describes the Url in terms of a java.io.File instance.
Filesystem	getFilesystem() Retrieve the Filesystem associated with this Url.
java.lang.Object	getFilesystemObject() For use only by Filesystem implementations.
java.lang.String	getHost() Retrieve the Url's host.
java.lang.String	getName() Returns a short name for the Url, typically consisting of the the last element of the file path.
Url	getParent() Returns a new Url with the last element of the file path removed.
static java.lang.String	getPath(Url[] urls) Produces a semicolon delimited string of Url descriptions from an array of Url objects.
java.lang.String	getProtocol() Retrieve the Url's protocol.
java.lang.String	getRelativePath(Url target) Create a relative path from an existing Url to specified target Url.
java.lang.String	getRelativePath(Url[] urls) Produces a semicolon delimited string of relative paths from an array of Url objects, assuming that the Url asked to perform the operation is the root from which relative paths are to be determined.
java.lang.String	getRelativePath(Url target, boolean onlyChildren) Create a relative path from an existing Url to specified target Url.
Url	getRelativeUrl(java.lang.String relativePath) Create a new Url from an existing root Url and a relative component.
int	hashCode() Retrieve the Url's hashCode.
boolean	isChild(Url url) Determines whether or not a given Url is subpath of this Url.
static Url[]	parsePath(java.lang.String path) Translates a semicolon delimited list of Url descriptions into an array of Url objects.
static Url[]	parseRelativePath(Url root, java.lang.String path) Translates a semicolon delimited list of relative paths into an array of Url objects.
static void	registerFilesystem(Filesystem filesystem) Add a new protocol / filesystem mapping to the Virtual File System.
void	setFilesystemObject(java.lang.Object filesystemObject) For use only by Filesystem implementations.
java.lang.String	toString() Retrieves the Url as a String formatted in the standard manner: <protocol>://<host>/<file> or <protocol>://<host>/<file>#<anchor>
java.net.URL	toURL() Creates a JDK-style URL which maps to a protocol handler capable of reading the contents of the underlying PrimeTime-style Url.
Url	withAnchor(java.lang.String newAnchor) Create a new Url derived from an existing Url by changing only the anchor portion.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ARRAY

public static final Url[] EMPTY_ARRAY

URL_ENCODING

public static final Strings.StringEncoding URL_ENCODING

Constructor Detail

Url

public Url(java.io.File file)

Create a new Url from an existing java.io.File object, using "file" for the protocol, an empty String for the host and no anchor.

Parameters:

file - The file object.

Url

public Url(java.lang.String protocol,
           java.lang.String file)

Create a new Url from the two components supplied, an empty String for the host and no anchor.

Parameters:

protocol - A String representing the protocol. Must not be null.

file - A String representing the file. Must not be null.

Url

public Url(java.lang.String protocol,
           java.lang.String host,
           java.lang.String file)

Create a new Url from the three components supplied and no anchor.

Parameters:

protocol - A String representing the protocol. Must not be null.

host - A String representing the host. Must not be null.

file - A String representing the file. Must not be null.

Url

public Url(java.lang.String protocol,
           java.lang.String host,
           java.lang.String file,
           java.lang.String anchor)

Create a new Url from the four components supplied.

Parameters:

protocol - A String representing the protocol. Must not be null.

host - A String representing the host. Must not be null.

file - A String representing the file. Must not be null.

anchor - A String representing the anchor, or null if the Url is to have no anchor.

Url

public Url(Filesystem filesystem,
           java.lang.String host,
           java.lang.String file,
           java.lang.String anchor)

Create a new Url from the four components supplied.

Parameters:

filesystem - A Filesystem representing the protocol. Must not be null.

host - A String representing the host. Must not be null.

file - A String representing the file. Must not be null.

anchor - A String representing the anchor, or null if the Url is to have no anchor.

Url

public Url(java.lang.String url)
    throws InvalidUrlException

Create a new Url by parsing a complete Url string in either of two forms: <protocol>://<host>/<file> or <protocol>://<host>/<file>#<anchor>

Parameters:

url - The String to be parsed.

Throws:

InvalidUrlException - If the supplied string does not conform to either of the two formats.

Method Detail

registerFilesystem

public static void registerFilesystem(Filesystem filesystem)

Add a new protocol / filesystem mapping to the Virtual File System.

Parameters:

protocol - The protocol for which the filesystem should be used.

filesystem - The appropriate filesystem for use with the specified protocol.

findFilesystem

public static Filesystem findFilesystem(java.lang.String protocol)

Find the filesystem registered for the protocol associated with the given Url.

Parameters:

protocol - The protocol for which the filesystem should be used.

Returns:

The appropriate filesystem for use with the specified protocol, or null if no matching filesystem is found.

getRelativeUrl

public Url getRelativeUrl(java.lang.String relativePath)

Create a new Url from an existing root Url and a relative component. For the purposes of relative pathing, the anchor is considered a part of the last subpath in the path.

Parameters:

root - The Url root.

relativePath - The relative path from the root.

Returns:

The newly derived Url.

getRelativePath

public java.lang.String getRelativePath(Url target)

Create a relative path from an existing Url to specified target Url. For the purposes of relative pathing, the anchor is considered a part of the last subpath in the path.

Parameters:

target - The Url target.

Returns:

The relative path to the target Url from this Url, or null if there is no valid path from the root Url to the target Url.

getRelativePath

public java.lang.String getRelativePath(Url target,
                                        boolean onlyChildren)

Create a relative path from an existing Url to specified target Url. For the purposes of relative pathing, the anchor is considered a part of the last subpath in the path.

Parameters:

target - The Url target.

onlyChildren - True if the target must be a descendant of the root, false if absolute paths and paths with leading "../" entries should be considered.

Returns:

The relative path to the target Url from this Url, or null if there is no valid path from the root Url to the target Url.

isChild

public boolean isChild(Url url)

Determines whether or not a given Url is subpath of this Url.

Parameters:

url - The potential child Url.

Returns:

True if it is a subpath, false otherwise.

withAnchor

public Url withAnchor(java.lang.String newAnchor)

Create a new Url derived from an existing Url by changing only the anchor portion.

Parameters:

newAnchor - The anchor portion for the new Url. A null value is interpreted as requesting a Url that has no anchor portion.

Returns:

The newly derived Url.

parsePath

public static Url[] parsePath(java.lang.String path)
                       throws InvalidUrlException

Translates a semicolon delimited list of Url descriptions into an array of Url objects.

Parameters:

path - The semicolon delimited string of Urls.

Returns:

The array of Url objects.

getPath

public static java.lang.String getPath(Url[] urls)

Produces a semicolon delimited string of Url descriptions from an array of Url objects.

Parameters:

urls - The array of Url objects.

The - semicolon delimited string of Urls.

parseRelativePath

public static Url[] parseRelativePath(Url root,
                                      java.lang.String path)
                               throws InvalidUrlException

Translates a semicolon delimited list of relative paths into an array of Url objects.

Parameters:

root - The Url root from which all relative paths are interpreted.

path - The semicolon delimited string of relative paths.

Returns:

The array of Url objects.

getRelativePath

public java.lang.String getRelativePath(Url[] urls)
                                 throws InvalidUrlException

Produces a semicolon delimited string of relative paths from an array of Url objects, assuming that the Url asked to perform the operation is the root from which relative paths are to be determined.

Parameters:

urls - The array of Url objects.

Returns:

The semicolon delimited string of relative paths.

getFilesystem

public Filesystem getFilesystem()

Retrieve the Filesystem associated with this Url.

Returns:

a Filesystem instance used to manipulate the information this Url represents. This value is guaranteed to be non-null.

getProtocol

public java.lang.String getProtocol()

Retrieve the Url's protocol.

Returns:

A String representing the Url's protocol. This value is guaranteed be non-null.

getHost

public java.lang.String getHost()

Retrieve the Url's host.

Returns:

A String representing the Url's host. This value is guaranteed be non-null.

getFile

public java.lang.String getFile()

Retrieve the Url's file.

Returns:

A String representing the Url's file portion. This value is guaranteed be non-null.

getFileExtension

public java.lang.String getFileExtension()

Retrieve the file extension portion of a Url's file.

Returns:

A String representing the Url's file extension, or an empty string if the filename does not have an extension.

getFileObject

public java.io.File getFileObject()

Describes the Url in terms of a java.io.File instance. Note that this may not be appropriate for many filesystem types, and will return null in these cases.

Returns:

An appropriate File object representation of the resource this Url refers to, or null if there is no equivelant File object.

getAnchor

public java.lang.String getAnchor()

Retrieve the Url's anchor.

Returns:

A String representing the Url's file portion. This value will be null if the Url does not have an anchor.

getParent

public Url getParent()

Returns a new Url with the last element of the file path removed.

Returns:

The parent Url, unless the last element in the file path is the only element, in which case null is returned.

getName

public java.lang.String getName()

Returns a short name for the Url, typically consisting of the the last element of the file path.

Returns:

The Url's short name.

toURL

public java.net.URL toURL()

Creates a JDK-style URL which maps to a protocol handler capable of reading the contents of the underlying PrimeTime-style Url.

compareTo

public int compareTo(java.lang.Object other)

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object other)

Retrieve the Url's anchor.

Overrides:

equals in class java.lang.Object

Parameters:

other - Another object to compare the Url with.

Returns:

True if other represents a Url with the same protocol, host, and anchor and an equivelant filename according to local filesystem rules. False if any of these conditions are not met.

hashCode

public int hashCode()

Retrieve the Url's hashCode.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code for this Url.

toString

public java.lang.String toString()

Retrieves the Url as a String formatted in the standard manner: <protocol>://<host>/<file> or <protocol>://<host>/<file>#<anchor>

Overrides:

toString in class java.lang.Object

Returns:

The formatted String.

getFilesystemObject

public java.lang.Object getFilesystemObject()

For use only by Filesystem implementations. Fetches the values most recently stored by setFilesystemObject.

setFilesystemObject

public void setFilesystemObject(java.lang.Object filesystemObject)

For use only by Filesystem implementations. The filesystemObject is a generic cache provided to allow a filesystem to improve performance when repeatedly referencing a Url instance. The type and meaning of the value are determined by the filesystem.