javax.ide.net
Class VirtualFileSystemHelper

java.lang.Object
  javax.ide.net.VirtualFileSystemHelper

public class VirtualFileSystemHelper
extends java.lang.Object

The VirtualFileSystemHelper class specifies the VirtualFileSystem operations that may have scheme-specific handling. By default, the VirtualFileSystem delegates its operations to VirtualFileSystemHelper. However, a subclass of VirtualFileSystemHelper can be registered with the VirtualFileSystem to handle the VirtualFileSystem operations for a particular scheme. A helper class is registered through the VirtualFileSystem.registerHelper(String, VirtualFileSystemHelper) method.

Special implementation note: classes that extend VirtualFileSystemHelper must be completely thread-safe because a single instance of each registered helper is held by the VirtualFileSystem and reused for all threads.

See Also:

VirtualFileSystem

Constructor Summary

protected

VirtualFileSystemHelper()

Method Summary

protected boolean	appendRelativePath(java.net.URI uri, java.net.URI base, java.lang.StringBuffer relativeURI, boolean mustConsumeBase) This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.
protected boolean	areEqual(java.lang.String s1, java.lang.String s2) Compares the two string for equality.
protected boolean	areEqualPathElems(java.lang.String uriElem, java.lang.String baseElem) This is a helper for the appendRelativePath(URI, URI, StringBuffer, boolean) method, which uses the template method design pattern.
boolean	canCreate(java.net.URI uri) Tests whether the application can create the resource at the specified URI.
java.net.URI	canonicalize(java.net.URI uri) Returns a canonical form of the URI, if one is available.
boolean	canRead(java.net.URI uri) Tests whether the application can read the resource at the specified URI.
boolean	canWrite(java.net.URI uri) Tests whether the application can modify the resource at the specified URI.
java.net.URI	convertSuffix(java.net.URI uri, java.lang.String oldSuffix, java.lang.String newSuffix) Takes the given URI and checks if its Object.toString() representation ends with the specified oldSuffix.
java.net.URI	createTempFile(java.lang.String prefix, java.lang.String suffix, java.net.URI directory) Creates a new empty temporary file in the specified directory using the given prefix and suffix strings to generate its name.
boolean	delete(java.net.URI uri) Deletes the content pointed to by the specified URI.
java.net.URI	ensureSuffix(java.net.URI uri, java.lang.String suffix) This method ensures that the specified URI ends with the specified suffix.
boolean	equals(java.net.URI uri1, java.net.URI uri2) Compares the specified URI objects to determine whether they point to the same resource.
boolean	exists(java.net.URI uri) Tests whether a resource at the specified URI location currently exists.
java.net.URI	getBaseParent(java.net.URI uri, java.lang.String relativeSpec) This method gets the base directory fully containing the relative path.
java.lang.String	getFileName(java.net.URI uri) Returns the name of the file contained by the URI, not including any scheme, authority, directory path, query, or fragment.
long	getLength(java.net.URI uri) Returns the number of bytes contained in the resource that the specified URI points to.
java.lang.String	getName(java.net.URI uri) Returns the name of the file contained by the URI, not including any scheme, authority, directory path, file extension, query, or fragment.
java.net.URI	getParent(java.net.URI uri) Returns the URI representing the parent directory of the specified URI.
java.lang.String	getPath(java.net.URI uri) Returns the path part of the URI.
java.lang.String	getPathNoExt(java.net.URI uri) Returns the path part of the URI without the last file extension.
java.lang.String	getPlatformPathName(java.net.URI uri) Returns the platform-dependent String representation of the URI; the returned string should be considered acceptable for users to read.
java.lang.String	getSuffix(java.net.URI uri) If a dot ('.') occurs in the filename part of the path part of the URI, then all of the text starting at the last dot is returned, including the dot.
boolean	hasSuffix(java.net.URI uri, java.lang.String suffix) Returns true if the path part of the URI ends with the given suffix String.
protected boolean	haveSameAuthority(java.net.URI uri, java.net.URI base) This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.
protected boolean	haveSameHost(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs hosts are equal.
protected boolean	haveSamePath(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs paths are equal.
protected boolean	haveSamePort(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs ports are equal.
protected boolean	haveSameQuery(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs queries are equal.
protected boolean	haveSameRef(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs refs are equal.
protected boolean	haveSameScheme(java.net.URI uri, java.net.URI base) This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.
protected boolean	haveSameUserInfo(java.net.URI uri1, java.net.URI uri2) Returns true if the URIs user infos are equal.
boolean	isBaseURIFor(java.net.URI uri1, java.net.URI uri2) Returns true if uri1 represents a a directory and uri2 points to a location within uri1's directory tree.
boolean	isDirectory(java.net.URI uri) Tests whether the location indicated by the URI is a directory.
boolean	isDirectoryPath(java.net.URI uri) Tests whether the location indicated by the URI represents a directory path.
boolean	isHidden(java.net.URI uri) Tests whether the resource indiciated by the URI is a hidden file.
boolean	isReadOnly(java.net.URI uri) Returns true if the resource is read-only.
boolean	isRegularFile(java.net.URI uri) Tests whether the resource indiciated by the URI is a regular file.
boolean	isValid(java.net.URI uri) Tests whether the specified URI is valid.
long	lastModified(java.net.URI uri) Returns the last modified time of the resource pointed to by the URI.
java.net.URI[]	list(java.net.URI uri) Returns an array of URIs naming files and directories in the directory indicated by the URI.
java.net.URI[]	list(java.net.URI uri, URIFilter filter) Returns an array of URIs naming files and directories in the directory indicated by the URI; the specified URIFilter is applied to determine which URIs will be returned.
java.net.URI[]	listRoots() Lists the root "file systems" that are supported by this helper.
boolean	mkdir(java.net.URI uri) Creates the directory indicated by the URI.
boolean	mkdirs(java.net.URI uri) Creates the directory indicated by the specified URI including any necessary but nonexistent parent directories.
java.io.InputStream	openInputStream(java.net.URI uri) Opens an InputStream on the specified URI.
java.io.OutputStream	openOutputStream(java.net.URI uri) Opens an OutputStream on the URI.
boolean	renameTo(java.net.URI oldURI, java.net.URI newURI) Renames the resource indicated by the first URI to the name indicated by the second URI.
boolean	setLastModified(java.net.URI uri, long time) Sets the last-modified timestamp of the resource indicated by the URI to the time specified by time.
boolean	setReadOnly(java.net.URI uri, boolean readOnly) Sets the read-only status of the resource indicated by the URI according to the specified readOnly flag.
java.lang.String	toDisplayString(java.net.URI uri) Returns a displayable form of the complete URI.
java.lang.String	toRelativeSpec(java.net.URI uri, java.net.URI base) This method attempts all possible ways of deriving a relative URI reference as described in RFC 2396 using the uri parameter as the URI whose relative URI reference is to be determined and the base parameter as the URI that serves as the base document for the uri pararmeter.
java.lang.String	toRelativeSpec(java.net.URI uri, java.net.URI base, boolean mustConsumeBase) Variant of toRelativeSpec(URI, URI) that has a flag that indicates whether the base URI should be fully consumed in the process of calculating the relative spec.
java.net.URL	toURL(java.net.URI uri) Get an URL from an URI.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VirtualFileSystemHelper

protected VirtualFileSystemHelper()

Method Detail

canonicalize

public java.net.URI canonicalize(java.net.URI uri)
                          throws java.io.IOException

Returns a canonical form of the URI, if one is available.

The default implementation just returns the specified URI as-is.

Throws:

java.io.IOException

canRead

public boolean canRead(java.net.URI uri)

Tests whether the application can read the resource at the specified URI.

Returns:

true if and only if the specified URI points to a resource that exists and can be read by the application; false otherwise.

canWrite

public boolean canWrite(java.net.URI uri)

Tests whether the application can modify the resource at the specified URI.

Returns:

true if and only if the specified URI points to a file that exists and the application is allowed to write to the file; false otherwise.

canCreate

public boolean canCreate(java.net.URI uri)

Tests whether the application can create the resource at the specified URI. This method tests that all components of the path can be created. If the resource pointed by the URI is read-only, this method returns false.

Returns:

true if the resource at the specified URI exists or can be created; false otherwise.

isValid

public boolean isValid(java.net.URI uri)

Tests whether the specified URI is valid. If the resource pointed by the URI exists the method returns true. If the resource does not exist, the method tests that all components of the path can be created.

Returns:

true if the URI is valid.

convertSuffix

public java.net.URI convertSuffix(java.net.URI uri,
                                  java.lang.String oldSuffix,
                                  java.lang.String newSuffix)

Takes the given URI and checks if its Object.toString() representation ends with the specified oldSuffix. If it does, the suffix is replaced with newSuffix. Both suffix parameters must include the leading dot ('.') if the dot is part of the suffix. If the specified URI does not end with the oldSuffix, then the newSuffix is simply appended to the end of the original URI.

delete

public boolean delete(java.net.URI uri)

Deletes the content pointed to by the specified URI. If the content is a file (or analogous to a file), then the file is removed from its directory (or container). If the content is a directory (or analogous to a directory), then the directory is removed only if it is empty (i.e. contains no other files or directories).

The default implementation simply returns false without doing anything.

Returns:

true if and only if the file or directory is successfully deleted; false otherwise.

ensureSuffix

public java.net.URI ensureSuffix(java.net.URI uri,
                                 java.lang.String suffix)

This method ensures that the specified URI ends with the specified suffix. The suffix does not necessarily have to start with a ".", so if a leading "." is required, the specified suffix must contain it -- e.g. ".java", ".class".

If the URI already ends in the specified suffix, then the URI itself is returned. Otherwise, a new URI is created with the the specified suffix appended to the original URI's path part, and the new URI is returned.

The default implementation first checks with hasSuffix(URI, String) to see if the URI already ends with the specified suffix. If not, the suffix is simply appended to the path part of the URI, and the new URI is returned.

Returns:

An URI, based on the specified URI, whose path part ends with the specified suffix.

Throws:

java.lang.NullPointerException - if either the specified URI or suffix is null. The caller is responsible for checking that they are not null.

equals

public boolean equals(java.net.URI uri1,
                      java.net.URI uri2)

Compares the specified URI objects to determine whether they point to the same resource. This method returns true if the URIs point to the same resource and returns false if the URIs do not point to the same resource.

This method and all subclass implementations can assume that both URI parameters are not null. The VirtualFileSystem.equals(URI, URI) method is responsible for checking that the two URIs are not null.

It can also be assumed that both URI parameters have the same scheme and that the scheme is appropriate for this VirtualFileSystemHelper. This determination is also the responsibility of VirtualFileSystem.equals(URI, URI).

The default implementation for this method delegates to URI.equals(Object).

exists

public boolean exists(java.net.URI uri)

Tests whether a resource at the specified URI location currently exists. The test for existence only checks the actual location and does not check any in-memory caches. The default implementation simply returns false without doing anything.

Returns:

true if and only if a resource already exists at the specified URI location; false otherwise.

getFileName

public java.lang.String getFileName(java.net.URI uri)

Returns the name of the file contained by the URI, not including any scheme, authority, directory path, query, or fragment. This simply returns the simple filename. For example, if you pass in an URI whose string representation is:

scheme://userinfo@host:1010/dir1/dir2/file.ext?query#fragment

the returned value is "file.ext" (without the quotes).

Returns:

The simple filename of the specified URI. This value should only be used for display purposes and not for opening streams or otherwise trying to locate the document.

getLength

public long getLength(java.net.URI uri)

Returns the number of bytes contained in the resource that the specified URI points to. If the length cannot be determined, -1 is returned.

The default implementation returns -1.

Returns:

the size in bytes of the document at the specified URI.

getName

public java.lang.String getName(java.net.URI uri)

Returns the name of the file contained by the URI, not including any scheme, authority, directory path, file extension, query, or fragment. This simply returns the simple filename. For example, if you pass in an URI whose string representation is:

scheme://userinfo@host:1010/dir1/dir2/file.ext1.ext2?query#fragment

the returned value is "file" (without the quotes).

The returned file name should only be used for display purposes and not for opening streams or otherwise trying to locate the resource indicated by the URI.

The default implementation first calls getFileName(URI) to get the file name part. Then all characters starting with the first occurrence of '.' are removed. The remaining string is then returned.

getParent

public java.net.URI getParent(java.net.URI uri)

Returns the URI representing the parent directory of the specified URI. If there is no parent directory, then null is returned.

The default implementation returns the value of invoking uri.resolve( ".." ).

getPath

public java.lang.String getPath(java.net.URI uri)

Returns the path part of the URI. The returned string is acceptable to use in one of the URIFactory methods that takes a path.

The default implementation delegates to URI.getPath().

getPathNoExt

public java.lang.String getPathNoExt(java.net.URI uri)

Returns the path part of the URI without the last file extension. To clarify, the following examples demonstrate the different cases:

Path part of input URI	Output String
/dir/file.ext	/dir/file
/dir/file.ext1.ext2	/dir/file.ext1
/dir1.ext1/dir2.ext2/file.ext1.ext2	/dir1.ext1/dir2.ext2/file.ext1
/file.ext	/file
/dir.ext/file	/dir.ext/file
/dir/file	/dir/file
/file	/file
/.ext	/

The default implementation gets the path from getPath(URI) and then trims off all of the characters beginning with the last "." in the path, if and only if the last "." comes after the last "/" in the path. If the last "." comes before the last "/" or if there is no "." at all, then the entire path is returned.

getPlatformPathName

public java.lang.String getPlatformPathName(java.net.URI uri)

Returns the platform-dependent String representation of the URI; the returned string should be considered acceptable for users to read. In general, the returned string should omit as many parts of the URI as possible. For the "file" scheme, therefore, the platform pathname should just be the pathname alone (no scheme) using the appropriate file separator character for the current platform. For other schemes, it may be necessary to reformat the URI string into a more human-readable form. That decision is left to each VirtualFileSystemHelper implementor.

The default implementation returns uri.toString(). If the URI is null, the empty string is returned.

Returns:

The path portion of the specified URI in platform-dependent notation. This value should only be used for display purposes and not for opening streams or otherwise trying to locate the document.

getSuffix

public java.lang.String getSuffix(java.net.URI uri)

If a dot ('.') occurs in the filename part of the path part of the URI, then all of the text starting at the last dot is returned, including the dot. If the last dot is also the last character in the path, then the dot by itself is returned. If there is no dot in the file name (even if a dot occurs elsewhere in the path), then the empty string is returned.

Examples:

• file:/home/jsr198/foo.txt returns ".txt"
• file:/home/jsr198/foo.txt.bak returns ".bak"
• file:/home/jsr198/foo returns ""
• file:/home/jsr198/foo. returns "."
• file:/home/jsr198/foo/ returns ""
• file:/home/jsr198.1/foo returns ""
• file:/home/jsr198.1/foo.txt returns ".txt"

hasSuffix

public boolean hasSuffix(java.net.URI uri,
                         java.lang.String suffix)

Returns true if the path part of the URI ends with the given suffix String. The suffix can be any String and doesn't necessarily have to be one that begins with a dot ('.'). If you are trying to test whether the path part of the URI ends with a particular file extension, then the suffix parameter must begin with a '.' character to ensure that you get the right return value.

isBaseURIFor

public boolean isBaseURIFor(java.net.URI uri1,
                            java.net.URI uri2)

Returns true if uri1 represents a a directory and uri2 points to a location within uri1's directory tree.

isDirectory

public boolean isDirectory(java.net.URI uri)

Tests whether the location indicated by the URI is a directory.

The default implementation always returns false.

Returns:

true if and only if the location indicated by the URI exists and is a directory; false otherwise.

isDirectoryPath

public boolean isDirectoryPath(java.net.URI uri)

Tests whether the location indicated by the URI represents a directory path. The directory path specified by the URI need not exist.

This method is intended to be a higher performance version of the isDirectory(URI) method. Implementations of this method should attempt to ascertain whether the specified URI represents a directory path by simply examining the URI itself. Time consuming i/o operations should be avoided.

The default implementation returns true if the path part of the URI ends with a '/' and the query and ref parts of the URI are null.

Returns:

true if the location indicated by the URI represents a directory path; the directory path need not exist.

isHidden

public boolean isHidden(java.net.URI uri)

Tests whether the resource indiciated by the URI is a hidden file. The exact definition of hidden is scheme-dependent and possibly system-dependent. On UNIX systems, a file is considered to be hidden if its name begins with a period character ('.'). On Win32 systems, a file is considered to be hidden if it has been marked as such in the file system.

The default implementation always returns false.

isReadOnly

public boolean isReadOnly(java.net.URI uri)

Returns true if the resource is read-only. A return value of false means that trying to get an OutputStream or trying to write to an OutputStream based on the URI will cause an IOException to be thrown. If the read-only status cannot be determined for some reason, this method returns true.

The default implementation always returns true. This means that all resources are considered read-only unless a scheme-specific VirtualFileSystemHelper is registered for the specified URI and is able to determine that the resource underlying the specified URI is not read-only.

isRegularFile

public boolean isRegularFile(java.net.URI uri)

Tests whether the resource indiciated by the URI is a regular file. A regular is a file that is not a directory and, in addition, satisfies other system-dependent criteria.

The default implementation returns the value of exists( uri ) && !isDirectory( uri ).

Returns:

true if and only if the resource indicated by the URI exists and is a normal file.

lastModified

public long lastModified(java.net.URI uri)

Returns the last modified time of the resource pointed to by the URI. The returned long is the number of milliseconds since the epoch (00:00:00 GMT Jan 1, 1970). If no timestamp is available or if the URI passed in is null, -1 is returned.

The default implementation returns -1.

Returns:

The last modified time of the document pointed to by the specified URI.

list

public java.net.URI[] list(java.net.URI uri)

Returns an array of URIs naming files and directories in the directory indicated by the URI. If the specified URI does not represent a directory, then this method returns null. Otherwise, an array of URIs is returned, one for each file or directory in the directory. URIs representing the directory itself or its parent are not included in the result. There is no guarantee that the URIs will occur in any particular order.

The default implementation always returns an empty URI array.

Returns:

An array of URIs naming the files and directories in the directory indicated by the URI. The array will be empty if the directory is empty. Returns null if the URI does not represent a directory or if an I/O error occurs.

list

public java.net.URI[] list(java.net.URI uri,
                           URIFilter filter)

Returns an array of URIs naming files and directories in the directory indicated by the URI; the specified URIFilter is applied to determine which URIs will be returned. If the specified URI does not represent a directory, then this method returns null. Otherwise, an array of URIs is returned, one for each file or directory in the directory that is accepted by the specified filter. URIs representing the directory itself or its parent are not included in the result. There is no guarantee that the URIs will occur in any particular order.

If the specified URIFilter is null then no filtering behavior is done.

The default implementation calls list(URI) first and then applies the URIFilter to the resulting list.

Returns:

An array of URIs naming the files and directories in the directory indicated by the URI that are accepted by the specified URIFilter. The array will be empty if the directory is empty. Returns null if the URI does not represent a directory or if an I/O error occurs.

listRoots

public java.net.URI[] listRoots()

Lists the root "file systems" that are supported by this helper. The returned URIs are used by file chooser dialogs to list all of the roots that are available for the user to browse. If no root file systems are supported, this method must return null or an empty URI array. If the returned array is not empty, then each URI contained in it must represent a directory and must not be null.

The default implementation always returns null.

mkdir

public boolean mkdir(java.net.URI uri)

Creates the directory indicated by the URI.

The default implementation always returns false.

Returns:

true if and only if the directory was created; false otherwise.

mkdirs

public boolean mkdirs(java.net.URI uri)

Creates the directory indicated by the specified URI including any necessary but nonexistent parent directories. Note that if this operation fails, it may have succeeded in creating some of the necessary parent directories. This method returns true if the directory was created along with all necessary parent directories or if the directories already exist; it returns false otherwise.

Returns:

true if all directories were created successfully or exist; false if there was a failure somewhere. Note that even if false is returned, some directories may still have been created.

createTempFile

public java.net.URI createTempFile(java.lang.String prefix,
                                   java.lang.String suffix,
                                   java.net.URI directory)
                            throws java.io.IOException

Creates a new empty temporary file in the specified directory using the given prefix and suffix strings to generate its name. Subclasses must implement this method given that default implementation does nothing and returns null.

Parameters:

prefix - The prefix string to be used in generating the file's name; must be at least three characters long

suffix - The directory in which the file is to be created, or null if the default temporary-file directory is to be used

directory - The directory in which the file is to be created, or null if the default temporary-file directory is to be used

Returns:

The URI to the temporary file.

Throws:

java.io.IOException

openInputStream

public java.io.InputStream openInputStream(java.net.URI uri)
                                    throws java.io.IOException

Opens an InputStream on the specified URI.

The default implementation throws UnknownServiceException.

Returns:

The InputStream associated with the URI.

Throws:

java.io.FileNotFoundException - if the resource at the specified URI does not exist.

java.io.IOException - if an I/O error occurs when trying to open the InputStream.

java.net.UnknownServiceException - (a runtime exception) if the scheme does not support opening an InputStream.

openOutputStream

public java.io.OutputStream openOutputStream(java.net.URI uri)
                                      throws java.io.IOException

Opens an OutputStream on the URI. If the file does not exist, the file should be created. If the directory path to the file does not exist, all necessary directories should be created.

The default implementation throws UnknownServiceException.

Parameters:

uri - An OutputStream is opened on the given URI. The operation is scheme-dependent.

Returns:

The OutputStream associated with the URI.

Throws:

java.io.IOException - if an I/O error occurs when trying to open the OutputStream.

java.net.UnknownServiceException - (a runtime exception) if the scheme does not support opening an OutputStream.

renameTo

public boolean renameTo(java.net.URI oldURI,
                        java.net.URI newURI)

Renames the resource indicated by the first URI to the name indicated by the second URI.

The default implementation simply returns false without doing anything. If either URI parameter is null or if both of the specified URI parameters refer to the same resource, then the rename is not attempted and failure is returned.

If the specified URI parameters do not have the same scheme, then the VirtualFileSystem handles the rename by first copying the resource to the destination with VirtualFileSystem.copy(URI, URI) and then deleting the original resource with VirtualFileSystem.delete(URI); if either operation fails, then failure is returned.

Otherwise, the scheme helper is called to perform the actual rename operation. Scheme helper implementations may therefore assume that both URI parameters are not null, do not refer to the same resource, and have the same scheme.

If the original URI refers to a nonexistent resource, then the scheme helper implementations should return failure. It is left up to the scheme helper implementations to decide whether to overwrite the destination or return failure if the destination URI refers to an existing resource.

Parameters:

oldURI - the URI of the original resource

newURI - the desired URI for the renamed resource

Returns:

true if and only if the resource is successfully renamed; false otherwise.

See Also:

VirtualFileSystem.renameTo(URI, URI)

setLastModified

public boolean setLastModified(java.net.URI uri,
                               long time)

Sets the last-modified timestamp of the resource indicated by the URI to the time specified by time. The time is specified in the number of milliseconds since the epoch (00:00:00 GMT Jan 1, 1970). The return value indicates whether or not the setting of the timestamp succeeded.

The default implementation always returns false without doing anything.

setReadOnly

public boolean setReadOnly(java.net.URI uri,
                           boolean readOnly)

Sets the read-only status of the resource indicated by the URI according to the specified readOnly flag. The return value indicates whether or not the setting of the read-only flag succeeded.

The default implementation always returns false without doing anything.

toDisplayString

public java.lang.String toDisplayString(java.net.URI uri)

Returns a displayable form of the complete URI.

The default implementation delegates to URI.toString().

toRelativeSpec

public java.lang.String toRelativeSpec(java.net.URI uri,
                                       java.net.URI base)

This method attempts all possible ways of deriving a relative URI reference as described in RFC 2396 using the uri parameter as the URI whose relative URI reference is to be determined and the base parameter as the URI that serves as the base document for the uri pararmeter. If it is not possible to produce a relative URI reference because the two URIs are too different, then a full, absolute reference for the uri parameter is returned.

Whatever value is returned by this method, it can be used in conjunction with the base URI to reconstruct the fully-qualified URI by using one of the URI constructors that takes a context URI plus a String spec (i.e. the String returned by this method).

Both the uri and base parameters should point to documents and be absolute URIs. Specifically, the base parameter does not need to be modified to represent the base directory if the base parameter already points to a document that is in the directory to which the uri parameter will be made relative. This relationship between uri and base is exactly how relative references are treated within HTML documents. Relative references in an HTML page are resolved against the HTML page's base URI. The base URI is the HTML page itself, not the directory that contains it.

If either the uri or base parameter needs to represent a directory rather than a file, they must end with a "/" in the path part of the URI, such as:

http://host.com/root/my_directory/

The algorithm used by this method to determine the relative reference closely follows the recommendations made in RFC 2396. The following steps are performed, in order, to determine the relative reference:

1. The scheme parts are checked first. If they do not match exactly, then an absolute reference is returned.
2. The authority parts are checked next. If they do not match exactly, then an absolute reference is returned.
3. If the scheme and authority parts match exactly, then it is possible to calculate a relative reference. The path parts are then compared element-by-element to determine the relative path, using the following steps, in order:
   1. If no path elements are in common, then an absolute path is used and relative-path determination stops.
   2. Otherwise, any path parts that are in common are omitted from the relative path. Comparison of path elements when the scheme is "file" is done using instance of File so that, for example, on Win32 the comparison is case-insensitive, whereas on Unix the comparison is case-sensitive. When the scheme is not "file", comparison is always case-sensitive.
   3. If, after matching as many path elements as possible, there are still path elements remaining in the base URI (except for the document name itself), then a "../" sequence is prepended to the resulting relative path for each base path element that was not consumed while matching path elements.
   4. If not all of the path elements in uri were consumed, then those path elements are appended to the resulting relative path as well. If the first remaining path element in uri contains a ':' character and there is no "../" sequence was prepended to the relative reference, then a "./" sequence is prepended to prevent the ':' character from being interpreted as a scheme delimiter (this is a special case in RFC 2396).

After the path part has been processed, no further processing is done. In particular, the query part and path part of the uri are not appended.

This method is implemented using the template method design pattern, so it is possible for subclasses to override just part of the algorithm in order to handle scheme-specific details.

toRelativeSpec

public java.lang.String toRelativeSpec(java.net.URI uri,
                                       java.net.URI base,
                                       boolean mustConsumeBase)

Variant of toRelativeSpec(URI, URI) that has a flag that indicates whether the base URI should be fully consumed in the process of calculating the relative spec.

If mustConsumeBase is true, then this method will return a non-null relative spec if and only if the base URI was fully consumed in the process of calculating the relative spec. Otherwise, if any part of the base URI remained, then this method returns null.

If mustConsumeBase is false, then this method will return a non-null relative spec regardless of how much of the base URI is consumed during the determination.

getBaseParent

public java.net.URI getBaseParent(java.net.URI uri,
                                  java.lang.String relativeSpec)

This method gets the base directory fully containing the relative path. The uri should be absolute and point to a directory. It must end with a "/" in the path part of the URI, such as:

http://host.com/root/my_directory/

If the uri does not end with a "/", it will be assumed that the uri points to a document. The document name will then be stripped in order to determine the parent directory. The relativeSpec parameter should be a relative path. If the relativeSpec does not end with a "/", it will be assumed that the relativeSpec points to a document. The document name will then be stripped in order to determine the parent directory. For example, if the uri points to:

file://c:/root/dir1/dir2/dir3/

and the relativeSpec is:

dir2/dir3

The returned value would be:

file://c:/root/dir1/

If the relativeSpec path elements are not fully contained in the last part of the uri path the value returned is the uri itself if the uri path ends with a "/" or the uri parent otherwise.

toURL

public java.net.URL toURL(java.net.URI uri)
                   throws java.net.MalformedURLException

Get an URL from an URI. This method just calls the URI.toURL() method.

Throws:

java.net.MalformedURLException

haveSameUserInfo

protected boolean haveSameUserInfo(java.net.URI uri1,
                                   java.net.URI uri2)

Returns true if the URIs user infos are equal.

haveSameHost

protected boolean haveSameHost(java.net.URI uri1,
                               java.net.URI uri2)

Returns true if the URIs hosts are equal.

haveSamePath

protected boolean haveSamePath(java.net.URI uri1,
                               java.net.URI uri2)

Returns true if the URIs paths are equal.

haveSameQuery

protected boolean haveSameQuery(java.net.URI uri1,
                                java.net.URI uri2)

Returns true if the URIs queries are equal.

haveSameRef

protected boolean haveSameRef(java.net.URI uri1,
                              java.net.URI uri2)

Returns true if the URIs refs are equal.

haveSamePort

protected boolean haveSamePort(java.net.URI uri1,
                               java.net.URI uri2)

Returns true if the URIs ports are equal.

areEqual

protected final boolean areEqual(java.lang.String s1,
                                 java.lang.String s2)

Compares the two string for equality.

haveSameScheme

protected boolean haveSameScheme(java.net.URI uri,
                                 java.net.URI base)

This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.

By default, the uri and base parameters must have identical schemes as a prerequisite to being able to produce a relative URI spec.

haveSameAuthority

protected boolean haveSameAuthority(java.net.URI uri,
                                    java.net.URI base)

This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.

The "authority" part is a combination of the user info, hostname, and port number. The full syntax in the URI string is:

userinfo@hostname:port

It may appear in an URI such as:

ftp://jsr198eg@ide.com:21/builds/ri.zip

The authority part may be null, if the URI scheme does not require one.

By default, the uri and base parameters must have identical authority strings as a prerequisite to being able to produce a relative URI spec.

appendRelativePath

protected boolean appendRelativePath(java.net.URI uri,
                                     java.net.URI base,
                                     java.lang.StringBuffer relativeURI,
                                     boolean mustConsumeBase)

This is a helper for the toRelativeSpec(URI, URI) method, which uses the template method design pattern.

Returns:

true if the entire base URI was consumed in the process of determining the relative path; false otherwise (i.e. not all of the base URI was consumed).

areEqualPathElems

protected boolean areEqualPathElems(java.lang.String uriElem,
                                    java.lang.String baseElem)

This is a helper for the appendRelativePath(URI, URI, StringBuffer, boolean) method, which uses the template method design pattern.

The two Strings that are passed in represent elements of the path parts of the uri and base parameters that are passed into appendRelativePath(URI, URI, StringBuffer, boolean).

By default, path elements are compared exactly in a case-sensitive manner using regular String comparison.