oracle.ide.net
Class URLFileSystemHelper

java.lang.Object
  oracle.ide.net.URLFileSystemHelper

Direct Known Subclasses:

HttpURLFileSystemHelper, IdeDisplayURLFileSystemHelper, IdeURLFileSystemHelper, URLFileSystemHelperDecorator

public class URLFileSystemHelper

extends java.lang.Object

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

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

See Also:

URLFileSystem

Constructor Summary

protected

URLFileSystemHelper()

Method Summary

protected boolean	appendRelativePath(java.net.URL url, java.net.URL base, java.lang.StringBuffer relativeURL, boolean mustConsumeBase) This is a helper for the toRelativeSpec(URL, URL) method, which uses the template method design pattern.
protected boolean	areEqual(java.lang.String s1, java.lang.String s2)
protected boolean	areEqualPathElems(java.lang.String urlElem, java.lang.String baseElem) This is a helper for the appendRelativePath(URL, URL, StringBuffer, boolean) method, which uses the template method design pattern.
boolean	canCreate(java.net.URL url) Tests whether the application can create the resource at the specified URL.
java.net.URL	canonicalize(java.net.URL url) Returns a canonical form of the URL, if one is available.
boolean	canRead(java.net.URL url) Tests whether the application can read the resource at the specified URL.
boolean	canWrite(java.net.URL url) Tests whether the application can modify the resource at the specified URL.
java.net.URL	convertSuffix(java.net.URL url, java.lang.String oldSuffix, java.lang.String newSuffix) Takes the given URL and checks if its Object.toString() representation ends with the specified oldSuffix.
java.net.URL	createTempFile(java.lang.String prefix, java.lang.String suffix, java.net.URL 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.URL url) Deletes the content pointed to by the specified URL.
java.net.URL	ensureSuffix(java.net.URL url, java.lang.String suffix) This method ensures that the specified URL ends with the specified suffix.
boolean	equals(java.net.URL url1, java.net.URL url2) Compares the specified URL objects to determine whether they point to the same resource.
boolean	exists(java.net.URL url) Returns true if the specified URL points to a resource that currently exists; returns false otherwise.
java.net.URL	getBaseParent(java.net.URL url, java.lang.String relativeSpec) This method gets the base directory fully containing the relative path.
javax.swing.Icon	getDefaultIcon(java.net.URL url) Returns one of the built-in JFileChooser icons for a hard drive, directory, or file, depending on the type of filesystem object represented by the URL.
java.lang.String	getFileName(java.net.URL url) Returns the name of the file contained by the URL, not including any protocol, hostname authentication, directory path, anchor, or query.
long	getLength(java.net.URL url) Returns the number of bytes contained in the resource that the specified URL points to.
java.lang.String	getName(java.net.URL url) Returns the name of the file contained by the URL, not including any protocol, hostname authentication, directory path, anchor, or query.
java.net.URL	getParent(java.net.URL url) Returns the URL representing the parent directory of the specified URL.
java.lang.String	getPath(java.net.URL url) Returns the path part of the URL.
java.lang.String	getPathNoExt(java.net.URL url) Returns the path part of the URL without the last file extension.
java.lang.String	getPlatformPathName(java.net.URL url) Returns the platform-dependent String representation of the URL; the returned string should be considered acceptable for users to read.
java.lang.String	getSuffix(java.net.URL url) If a dot ('.') occurs in the path portion of the URL, then all of the text starting at the last dot is returned, including the dot.
javax.swing.Icon	getSystemIcon(java.net.URL url) The default implementation returns the default icon obtained from URLFileSystem.getDefaultIcon(URL).
boolean	hasSuffix(java.net.URL url, java.lang.String suffix) Returns true if the path part of the URL ends with the given suffix String.
protected boolean	haveSameAuthority(java.net.URL url, java.net.URL base) This is a helper for the toRelativeSpec(URL, URL) method, which uses the template method design pattern.
protected boolean	haveSameHost(java.net.URL url1, java.net.URL url2)
protected boolean	haveSamePath(java.net.URL url1, java.net.URL url2)
protected boolean	haveSamePort(java.net.URL url1, java.net.URL url2)
protected boolean	haveSameProtocol(java.net.URL url, java.net.URL base) This is a helper for the toRelativeSpec(URL, URL) method, which uses the template method design pattern.
protected boolean	haveSameQuery(java.net.URL url1, java.net.URL url2)
protected boolean	haveSameRef(java.net.URL url1, java.net.URL url2)
protected boolean	haveSameUserInfo(java.net.URL url1, java.net.URL url2)
boolean	isBaseURLFor(java.net.URL url1, java.net.URL url2) Returns true if url1 represents a a directory and url2 points to a location within url1's directory tree.
boolean	isDirectory(java.net.URL url) Tests whether the location indicated by the URL is a directory.
boolean	isDirectoryPath(java.net.URL url) Tests whether the location indicated by the URL represents a directory path.
boolean	isHidden(java.net.URL url) Tests whether the resource indiciated by the URL is a hidden file.
boolean	isReadOnly(java.net.URL url) Returns true if the resource is read-only.
boolean	isRegularFile(java.net.URL url) Tests whether the resource indiciated by the URL is a regular file.
boolean	isValid(java.net.URL url) Tests whether the specified URL is valid.
long	lastModified(java.net.URL url) Returns the last modification time (timestamp) of the resource indicated by the specified URL in milliseconds since 00:00:00 GMT, Jan 1, 1970.
java.net.URL[]	list(java.net.URL url) Returns an array of URLs naming files and directories in the directory indicated by the URL.
java.net.URL[]	list(java.net.URL url, URLFilter filter) Returns an array of URLs naming files and directories in the directory indicated by the URL; the specified URLFilter is applied to determine which URLs will be returned.
java.net.URL[]	listRoots() Lists the root "file systems" that are supported by this helper.
URLFileSystem.FileInfo[]	ls(java.net.URL url) Returns an array of URLFileSystem.FileInfo objects describing files and directories in the directory indicated by the URL.
URLFileSystem.FileInfo[]	ls(java.net.URL url, URLFilter filter) Returns an array of URLFileSystem.FileInfo objects describing files and directories in the directory indicated by the URL that satisfy the specified URLFilter.
boolean	mkdir(java.net.URL url) Creates the directory indicated by the URL.
boolean	mkdirs(java.net.URL url) Creates the directory indicated by the specified URL including any necessary but nonexistent parent directories.
java.io.InputStream	openInputStream(java.net.URL url) Opens an InputStream on the specified URL.
java.io.OutputStream	openOutputStream(java.net.URL url) Opens an OutputStream on the URL.
boolean	renameTo(java.net.URL oldURL, java.net.URL newURL) Renames the resource indicated by the first URL to the name indicated by the second URL.
boolean	setLastModified(java.net.URL url, long time) Sets the last-modified timestamp of the resource indicated by the URL to the time specified by time.
boolean	setReadOnly(java.net.URL url, boolean readOnly) Sets the read-only status of the resource indicated by the URL according to the specified readOnly flag.
java.lang.String	toDisplayString(java.net.URL url) Returns a displayable form of the complete URL.
java.lang.String	toEncodedString(java.net.URL url)
java.lang.String	toRelativeSpec(java.net.URL url, java.net.URL base) This method attempts all possible ways of deriving a relative URI reference as described in RFC 2396 using the url parameter as the URL whose relative URI reference is to be determined and the base parameter as the URL that serves as the base document for the url pararmeter.
java.lang.String	toRelativeSpec(java.net.URL url, java.net.URL base, boolean mustConsumeBase) Variant of toRelativeSpec(URL, URL) that has a flag that indicates whether the base URL should be fully consumed in the process of calculating the relative spec.

Methods inherited from class java.lang.Object

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

Constructor Detail

URLFileSystemHelper

protected URLFileSystemHelper()

Method Detail

canonicalize

public java.net.URL canonicalize(java.net.URL url)

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

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

canRead

public boolean canRead(java.net.URL url)

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

Returns:

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

canWrite

public boolean canWrite(java.net.URL url)

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

Returns:

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

canCreate

public boolean canCreate(java.net.URL url)

Tests whether the application can create the resource at the specified URL.

Returns:

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

isValid

public boolean isValid(java.net.URL url)

Tests whether the specified URL is valid. If the resource pointed by the URL 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 URL is valid.

convertSuffix

public java.net.URL convertSuffix(java.net.URL url,
                                  java.lang.String oldSuffix,
                                  java.lang.String newSuffix)

Takes the given URL 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 URL does not end with the oldSuffix, then the newSuffix is simply appended to the end of the original URL.

delete

public boolean delete(java.net.URL url)

Deletes the content pointed to by the specified URL. 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.URL ensureSuffix(java.net.URL url,
                                 java.lang.String suffix)

This method ensures that the specified URL 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 URL already ends in the specified suffix, then the URL itself is returned. Otherwise, a new URL is created with the the specified suffix appended to the original URL's path part, and the new URL is returned.

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

Returns:

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

Throws:

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

equals

public boolean equals(java.net.URL url1,
                      java.net.URL url2)

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

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

It can also be assumed that both URL parameters have the same protocol and that the protocol is appropriate for this URLFileSystemHelper. This determination is also the responsibility of URLFileSystem.equals(URL, URL).

The default implementation for this method checks to see if the various parts of the URLs are equal. Unlike URL.equals(java.lang.Object), the host names are not resolved to InetAddresses.

exists

public boolean exists(java.net.URL url)

Returns true if the specified URL points to a resource that currently exists; returns false otherwise.

The default implementation simply returns false without doing anything.

getDefaultIcon

public javax.swing.Icon getDefaultIcon(java.net.URL url)

Returns one of the built-in JFileChooser icons for a hard drive, directory, or file, depending on the type of filesystem object represented by the URL.

getFileName

public java.lang.String getFileName(java.net.URL url)

Returns the name of the file contained by the URL, not including any protocol, hostname authentication, directory path, anchor, or query. This simply returns the simple filename. For example, if you pass in an URL whose string representation is:

protocol://host:1010/dir1/dir2/file.ext#anchor?query

the returned value is "file.ext" (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 URL.

getLength

public long getLength(java.net.URL url)

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

The default implementation attempts to get the content length from the URLConnection associated with the URL. If that fails for some reason (e.g. the resource does not exist, there was some other an I/O exception, etc.), -1 is returned.

See Also:

URLConnection

getName

public java.lang.String getName(java.net.URL url)

Returns the name of the file contained by the URL, not including any protocol, hostname authentication, directory path, anchor, or query. This simply returns the simple filename. For example, if you pass in an URL whose string representation is:

protocol://host:1010/dir1/dir2/file.ext1.ext2#anchor?query

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 URL.

The default implementation first calls getFileName(URL) 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.URL getParent(java.net.URL url)

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

The default implementation returns the value of invoking URLFactory.newURL( url, ".." ).

getPath

public java.lang.String getPath(java.net.URL url)

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

The default implementation delegates to URL.getPath().

getPathNoExt

public java.lang.String getPathNoExt(java.net.URL url)

Returns the path part of the URL without the last file extension. To clarify, the following examples demonstrate the different cases that come up:

Path part of input URL	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(URL) 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.URL url)

Returns the platform-dependent String representation of the URL; the returned string should be considered acceptable for users to read. In general, the returned string should omit as many parts of the URL as possible. For the "file" protocol, therefore, the platform pathname should just be the pathname alone (no protocol) using the appropriate file separator character for the current platform. For other protocols, it may be necessary to reformat the URL string into a more human-readable form. That decision is left to each URLFileSystemHelper implementor. The default implementation returns url.toString(). If the URL is null, the empty string is returned.

Returns:

The path portion of the specified URL 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.URL url)

If a dot ('.') occurs in the path portion of the URL, 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 path, then the empty string is returned.

getSystemIcon

public javax.swing.Icon getSystemIcon(java.net.URL url)

The default implementation returns the default icon obtained from URLFileSystem.getDefaultIcon(URL).

hasSuffix

public boolean hasSuffix(java.net.URL url,
                         java.lang.String suffix)

Returns true if the path part of the URL 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 URL ends with a particular file extension, then the suffix parameter should begin with a '.' character to ensure that you get the right return value.

isBaseURLFor

public boolean isBaseURLFor(java.net.URL url1,
                            java.net.URL url2)

Returns true if url1 represents a a directory and url2 points to a location within url1's directory tree.

isDirectory

public boolean isDirectory(java.net.URL url)

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

The default implementation always returns false.

Returns:

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

isDirectoryPath

public boolean isDirectoryPath(java.net.URL url)

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

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

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

Returns:

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

isHidden

public boolean isHidden(java.net.URL url)

Tests whether the resource indiciated by the URL is a hidden file. The exact definition of hidden is protocol-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.URL url)

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 URL will cause an exception to be thrown.

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

isRegularFile

public boolean isRegularFile(java.net.URL url)

Tests whether the resource indiciated by the URL 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( url ) && !isDirectory( url ).

Returns:

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

lastModified

public long lastModified(java.net.URL url)

Returns the last modification time (timestamp) of the resource indicated by the specified URL in milliseconds since 00:00:00 GMT, Jan 1, 1970. If the timestamp can't be determined, -1 is returned.

The default implementation attemps to get the last modified time from the URLConnection associated with the URL. If that fails for some reason (e.g. the resource does not exist, there was some other I/O exception, etc.), -1 is returned.

See Also:

URLConnection

list

public java.net.URL[] list(java.net.URL url)

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

The default implementation always returns an empty URL array.

Returns:

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

list

public java.net.URL[] list(java.net.URL url,
                           URLFilter filter)

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

The default implementation calls list(URL) first and then applies the URLFilter to the resulting list.

Returns:

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

listRoots

public java.net.URL[] listRoots()

Lists the root "file systems" that are supported by this helper. The returned URLs are used by the URLChooser 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 URL array. If the returned array is not empty, then each URL contained in it must represent a directory and must not be null.

The default implementation always returns null.

ls

public URLFileSystem.FileInfo[] ls(java.net.URL url)

Returns an array of URLFileSystem.FileInfo objects describing files and directories in the directory indicated by the URL.

If the specified URL does not represent a directory, then this method returns null. Otherwise, an array of URLFileSystem.FileInfo objects is returned, one for each file or directory in the directory. URLFilesystem.FileInfo objects representing the directory itself or its parent are not included in the result.

There is no guarantee that the URLFileSystem.FileInfo objects will be returned in any specific order; in particular, they are not guaranteed to be returned in alphabetical order.

The default implementation calls ls(URL, null).

Returns:

An array of URLFileSystem.FileInfo objects describing the files and directories in the directory indicated by the URL. The array will be empty if the directory is empty. Returns null if the URL does not represent a directory or if an I/O error occurs.

ls

public URLFileSystem.FileInfo[] ls(java.net.URL url,
                                   URLFilter filter)

Returns an array of URLFileSystem.FileInfo objects describing files and directories in the directory indicated by the URL that satisfy the specified URLFilter.

The behavior of this method is the same as ls(URL), except that the URLs indicated by the returned array must satisfy the filter. If the given filter is null, then all URLs are accepted. Otherwise, an URL satisfies the filter if and only if the value of true results when the URLFilter.accept(URL) method of the filter is invoked on the URL of a file or directory in the directory that it denotes.

The default implementation calls URLFileSystem.list(URL, URLFilter) and builds the URLFileSystem.FileInfo objects from the returned URLs.

Returns:

An array of URLFileSystem.FileInfo objects describing the files and directories in the directory indicated by the URL. The array will be empty if the directory is empty. Returns null if the URL does not represent a directory or if an I/O error occurs.

mkdir

public boolean mkdir(java.net.URL url)

Creates the directory indicated by the URL.

The default implementation always returns false.

Returns:

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

mkdirs

public boolean mkdirs(java.net.URL url)

Creates the directory indicated by the specified URL 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.URL createTempFile(java.lang.String prefix,
                                   java.lang.String suffix,
                                   java.net.URL 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 URL to the temporary file.

Throws:

java.io.IOException

openInputStream

public java.io.InputStream openInputStream(java.net.URL url)
                                    throws java.io.IOException

Opens an InputStream on the specified URL.

The default implementation attempts to open the InputStream through the URLConnection associated with the URL. If the URLConnection implementation does not support an InputStream then an UnknownServiceException (a runtime exception) will be thrown.

Throws:

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

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

java.net.UnknownServiceException - if the URLConnection backing the specified URL does not support an InputStream.

See Also:

IOException, URLConnection, UnknownServiceException

openOutputStream

public java.io.OutputStream openOutputStream(java.net.URL url)
                                      throws java.io.IOException

Opens an OutputStream on the URL. 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 attempts to open the OutputStream through the URLConnection associated with the URL. If the URLConnection implementation does not support an OutputStream then an UnknownServiceException (a runtime exception) will be thrown.

Throws:

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

java.net.UnknownServiceException - if the URLConnection backing the specified URL does not support an OutputStream.

See Also:

IOException, URLConnection, UnknownServiceException

renameTo

public boolean renameTo(java.net.URL oldURL,
                        java.net.URL newURL)

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

The default implementation simply returns false without doing anything.

See Also:

URLFileSystem.renameTo(URL, URL)

setLastModified

public boolean setLastModified(java.net.URL url,
                               long time)

Sets the last-modified timestamp of the resource indicated by the URL 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.URL url,
                           boolean readOnly)

Sets the read-only status of the resource indicated by the URL 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.URL url)

Returns a displayable form of the complete URL.

The default implementation delegates to URL.toString().

toEncodedString

public java.lang.String toEncodedString(java.net.URL url)

toRelativeSpec

public java.lang.String toRelativeSpec(java.net.URL url,
                                       java.net.URL base)

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

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

Both the url and base parameters should point to documents and be absolute URLs. 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 url parameter will be made relative. This relationship between url 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 URL. The base URL is the HTML page itself, not the directory that contains it.

If either the url or base parameter needs to represent a directory rather than a file, they must end with a "/" in the path part of the URL, 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 protocol 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 protocol 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 protocol 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 protocol is not "file", comparison is always case-sensitive. (This distinction is made by FileURLFileSystemHelper, which overrides the relevant part of the algorithm.)
   3. If, after matching as many path elements as possible, there are still path elements remaining in the base URL (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 url were consumed, then those path elements are appended to the resulting relative path as well. If the first remaining path element in url 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 protocol 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 url 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 protocol-specific details.

toRelativeSpec

public java.lang.String toRelativeSpec(java.net.URL url,
                                       java.net.URL base,
                                       boolean mustConsumeBase)

Variant of toRelativeSpec(URL, URL) that has a flag that indicates whether the base URL 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 URL was fully consumed in the process of calculating the relative spec. Otherwise, if any part of the base URL 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 URL is consumed during the determination.

getBaseParent

public java.net.URL getBaseParent(java.net.URL url,
                                  java.lang.String relativeSpec)

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

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

If the url does not end with a "/", it will be assumed that the url 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 url 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 url path the value returned is the url itself if the url path ends with a "/" or the url parent otherwise.

haveSameUserInfo

protected boolean haveSameUserInfo(java.net.URL url1,
                                   java.net.URL url2)

haveSameHost

protected boolean haveSameHost(java.net.URL url1,
                               java.net.URL url2)

haveSamePath

protected boolean haveSamePath(java.net.URL url1,
                               java.net.URL url2)

haveSameQuery

protected boolean haveSameQuery(java.net.URL url1,
                                java.net.URL url2)

haveSameRef

protected boolean haveSameRef(java.net.URL url1,
                              java.net.URL url2)

haveSamePort

protected boolean haveSamePort(java.net.URL url1,
                               java.net.URL url2)

areEqual

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

haveSameProtocol

protected boolean haveSameProtocol(java.net.URL url,
                                   java.net.URL base)

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

By default, the url and base parameters must have identical protocols as a prerequisite to being able to produce a relative URL spec.

haveSameAuthority

protected boolean haveSameAuthority(java.net.URL url,
                                    java.net.URL base)

This is a helper for the toRelativeSpec(URL, URL) 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 URL string is:

userinfo@hostname:port

It may appear in an URL such as:

ftp://jdijamco@javatools-dev:21/jtinteg/JDev50.zip

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

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

appendRelativePath

protected boolean appendRelativePath(java.net.URL url,
                                     java.net.URL base,
                                     java.lang.StringBuffer relativeURL,
                                     boolean mustConsumeBase)

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

Returns:

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

areEqualPathElems

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

This is a helper for the appendRelativePath(URL, URL, 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 url and base parameters that are passed into appendRelativePath(URL, URL, StringBuffer, boolean).

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