oracle.ide.net
Class URLPath

java.lang.Object
  oracle.ide.model.DefaultSubDirtyable
      oracle.ide.net.URLPath

All Implemented Interfaces:

Copyable, Dirtyable, SubDirtyable

public class URLPath

extends DefaultSubDirtyable

implements Copyable

An instance of URLPath represents a path that is made up entirely of URLs. This can be a class path, source path, doc path, etc.

Access to the URL objects contained by URLPath is also allowed through these JavaBean accessor methods. The main reason for this is that URLPath can then be used with a JavaBeans-driven marshalling framework for persistence, such as Object2Dom. Therefore, an instance of URLPath can be embedded as a property within another JavaBean that is persisted by Object2Dom.

Constructor Summary

URLPath()
Creates a URLPath that is initially empty.

URLPath(int initialCapacity)
Creates an empty URLPath with the specified initial capacity.

URLPath(java.net.URL entry)
Creates a URLPath that initially contains the specified URL as its sole entry.

URLPath(java.net.URL[] entries)
Creates a URLPath initialized with the specified array of URL objects.

URLPath(URLPath urlPath)
Copy constructor.

Method Summary

void	add(java.net.URL entry) Adds the given URL to the end of the URLPath, if it is not already on the URLPath.
void	add(java.net.URL[] entries) Adds the given URL objects in order to the end of the URLPath.
void	add(URLPath urlPath) Adds the entries from the specified URLPath to this instance.
boolean	contains(java.net.URL entry) Returns true if the specified URL is currently on this URLPath.
java.lang.Object	copyTo(java.lang.Object object) Copies the internal state of this object to the specified copy.
protected void	copyToImpl(URLPath copy) Design pattern for supporting strongly typed copying.
boolean	equals(java.lang.Object o)
protected boolean	equalsImpl(URLPath urlPath) This is a helper method for equals(Object) that can also be used by subclasses that implement equals(Object).
java.util.List	getAllDirectories() Retrieves the list of all the directories currently present on this URLPath.
java.util.List	getDirectories(java.lang.String relPath) Retrieves the list of all directories existing immediately under a relative path.
java.net.URL[]	getEntries() Returns the path represented by this URLPath instance as an array of URLs.
java.util.List	getFiles(java.lang.String relPath) Retrieves a list of URLs representing all the files contained under a relative path.
java.util.List	getFilesAndDirectories(java.lang.String relPath, boolean dirsBeforeFiles) Returns a List of URLs enumerating all the files and directories contained within the specified relPath, relative to this URLPath.
java.net.URL	getFirstEntry() Convience method to get the first URL entry contained within the URLPath.
java.util.Iterator	iterator() Returns an Iterator whose elements are all instances of URL.
static URLPath	newURLPathFromString(java.lang.String entries) This is a factory method for creating a URLPath instance based on a typical path string, such as that that is returned by System.getProperty( "java.class.path" ).
void	remove(java.net.URL entry)
void	setEntries(java.net.URL[] entries) Sets the path represented by this URLPath instance to be equivalent to the specified array of URLs.
int	size() Returns the number of entries in the URLPath.
java.net.URL	toBoundURL(java.lang.String relativePath) Given a relative spec, this method attempts to construct a fully qualified URL that is bound to a corresponding resource on this URLPath.
java.net.URL	toQualifiedURL(java.lang.String relativePath) Given a relative spec, this method attempts to construct a fully qualified URL that points to the corresponding resource on this URLPath.
java.lang.String	toRelativePath(java.net.URL url) Given an URL, this method attempts to derive its relative path with respect to this instance of URLPath.
java.lang.String	toString()
java.lang.String[]	toStrings()
boolean	validateAllEntriesExist() Validates the URLPath entries

Methods inherited from class oracle.ide.model.DefaultSubDirtyable

getOwner, isDirty, markDirty, setOwner

Methods inherited from class java.lang.Object

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

Constructor Detail

URLPath

public URLPath()

Creates a URLPath that is initially empty.

URLPath

public URLPath(int initialCapacity)

Creates an empty URLPath with the specified initial capacity. Used to construct a URLPath whose contents are not initially known but where the number of entries can be estimated ahead of time.

Parameters:

initialCapacity - the initial capacity of the URLPath

URLPath

public URLPath(java.net.URL entry)

Creates a URLPath that initially contains the specified URL as its sole entry. If the entry is null, then the URLPath created is initially empty.

URLPath

public URLPath(java.net.URL[] entries)

Creates a URLPath initialized with the specified array of URL objects. If the entries array is null or empty, then the URLPath created is initially empty.

URLPath

public URLPath(URLPath urlPath)

Copy constructor.

Method Detail

copyTo

public java.lang.Object copyTo(java.lang.Object object)

Description copied from interface: Copyable

Copies the internal state of this object to the specified copy. If copy is null, then this method should create a new instance of this class and proceed to copy the internal state to the newly created object. Generally, only the persistent state of the object should be copied, but whether or not it is appropriate to copy transient properties is at the discretion of the individual implementor.

Regardless of whether the copy occurs to an existing object or to a newly created object, the return value is object to which this object's state was copied.

There is a standard implementation pattern for the copyTo method that helps avoid problems that arise when a Copyable object is subclassed. The pattern is:

public Object copyTo( Object target )
{
final <this_class> copy =
target != null ? (<this_class>) target : new <this_class>();
copyToImpl( copy );
return copy;
} protected final void copyToImpl( <this_class> copy ) { super.copyToImpl( copy ); // if necessary // put code here for copying the properties of <this_class> }

The parameter passed into the copyToImpl method is the same type of this class. The responsibility of copyToImpl is to copy the state of this class through direct access of the fields. The copyToImpl method should not use getters and setters since these may be overridden, causing the state of this class to be incompletely copied.

Specified by:

copyTo in interface Copyable

Parameters:

object - The target object to which the state of this object should be copied. If target is null, then the copyTo method will return a new instance of this class.

Returns:

The object to which the state of this object was copied. If the target was non-null, then the return value is the same as the target object that was passed in; otherwise, the return value is a new instance of this class.

copyToImpl

protected final void copyToImpl(URLPath copy)

Design pattern for supporting strongly typed copying.

add

public void add(java.net.URL entry)

Adds the given URL to the end of the URLPath, if it is not already on the URLPath. If the parameter is null, then this method returns without doing anything.

add

public void add(java.net.URL[] entries)

Adds the given URL objects in order to the end of the URLPath. Each URL is added only if it is not already on the URLPath. Any null entries are ignored. If the entries array itself is null, then this method returns without doing anything.

add

public void add(URLPath urlPath)

Adds the entries from the specified URLPath to this instance.

getEntries

public java.net.URL[] getEntries()

Returns the path represented by this URLPath instance as an array of URLs. If the URLPath is empty, then then this method returns an URL array of size 0.

contains

public boolean contains(java.net.URL entry)

Returns true if the specified URL is currently on this URLPath.

getAllDirectories

public java.util.List getAllDirectories()

Retrieves the list of all the directories currently present on this URLPath. The directories are sorted in a case-sensitive order.

Returns:

a List containing the ordered list of directories.

getDirectories

public java.util.List getDirectories(java.lang.String relPath)

Retrieves the list of all directories existing immediately under a relative path. The directories are added as relative paths to the base URLs of the entries, not the specified relative path.

Parameters:

relPath - the relative path under which to look for directories.

Returns:

a List containing the ordered list of directories.

getFiles

public java.util.List getFiles(java.lang.String relPath)

Retrieves a list of URLs representing all the files contained under a relative path.

Parameters:

relPath - the relative path under which to look for files.

Returns:

a List containing the ordered list of file URLs.

getFilesAndDirectories

public java.util.List getFilesAndDirectories(java.lang.String relPath,
                                             boolean dirsBeforeFiles)

Returns a List of URLs enumerating all the files and directories contained within the specified relPath, relative to this URLPath.

getFirstEntry

public java.net.URL getFirstEntry()

Convience method to get the first URL entry contained within the URLPath. In numerous places in the IDE, we need the first path only.

Returns:

URL The first URL in the URLPath

iterator

public java.util.Iterator iterator()

Returns an Iterator whose elements are all instances of URL. Calling the remove() method on the iterator will write through and change the URLPath.

newURLPathFromString

public static URLPath newURLPathFromString(java.lang.String entries)

This is a factory method for creating a URLPath instance based on a typical path string, such as that that is returned by System.getProperty( "java.class.path" ). The exact format of the path string is platform-dependent, so the path string is tokenized using File.pathSeparator as the delimiter.

Relative paths are converted to absolute paths, and any path entries whose name ends in ".jar" or ".zip" will be created as jar URLs (i.e. an URL with the "jar" protocol).

remove

public void remove(java.net.URL entry)

setEntries

public void setEntries(java.net.URL[] entries)

Sets the path represented by this URLPath instance to be equivalent to the specified array of URLs. If the argument is null, then the URLPath is cleared; subsequent calls to getEntries() would then return an empty URL array.

size

public int size()

Returns the number of entries in the URLPath.

toQualifiedURL

public java.net.URL toQualifiedURL(java.lang.String relativePath)

Given a relative spec, this method attempts to construct a fully qualified URL that points to the corresponding resource on this URLPath. If no matching URL can be constructed, then null is returned. An URL is deemed to match iff the URL points to an existing resource. In practical terms, it means that calling the method exists() on URLFileSystem returns true. Note that toQualifiedURL will generally return null if the desired resource only exists in memory (for example, if it is bound to an unsaved Node). If in-memory resources are desired as well, use toBoundURL instead.

See Also:

toBoundURL(java.lang.String), URLFileSystem.exists(java.net.URL)

toBoundURL

public java.net.URL toBoundURL(java.lang.String relativePath)

Given a relative spec, this method attempts to construct a fully qualified URL that is bound to a corresponding resource on this URLPath. If no matching URL can be constructed, then null is returned. The determination of whether an URL is bound is based on using the URLFileSystem method isBound, which uses one or more instances of URLExistTest to determine whether someone claims ownership of the a resource bound that that URL. This differs from toQualifiedURL in that it may find in memory resources in addition to resources existing on the filesystem or some other more permanent location.

See Also:

URLFileSystem.exists(java.net.URL)

toRelativePath

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

Given an URL, this method attempts to derive its relative path with respect to this instance of URLPath. If the specified URL does not point to a location that is on this URLPath, then null is returned.

toStrings

public java.lang.String[] toStrings()

equals

public boolean equals(java.lang.Object o)

equalsImpl

protected final boolean equalsImpl(URLPath urlPath)

This is a helper method for equals(Object) that can also be used by subclasses that implement equals(Object). It assumes that the argument is not null.

toString

public java.lang.String toString()

validateAllEntriesExist

public boolean validateAllEntriesExist()

Validates the URLPath entries

Returns:

true if each entry in the URLPath exists or if there are no entries in the URLPath; false otherwise.