oracle.ide.net

Class URLPath

java.lang.Object

oracle.ide.model.DefaultSubDirtyable

oracle.ide.net.URLPath

All Implemented Interfaces:

java.lang.Iterable<java.net.URL>, SubDirtyable, Dirtyable, Copyable

public class URLPath
extends DefaultSubDirtyable
implements Copyable, java.lang.Iterable<java.net.URL>

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. Therefore, an instance of URLPath can be embedded as a property within another JavaBean that is persisted.

URLPath is essentially a wrapper on an underlying List of URL. Access to the URLPath from multiple threads is safe if the underlying List implementation is thread safe, and if all iteration through the iterator returned by iterator() is done while holding the intrinsic lock on the object returned by iteratorLock().

Constructor Summary

Constructors

Constructor and Description
URLPath() Creates a URLPath that is initially empty.
URLPath(int initialCapacity) Creates an empty URLPath with the specified initial capacity.
URLPath(java.util.List entries) Creates a URLPath instance that is linked directly to the specified List.
URLPath(ListStructure entries) Creates a URLPath instance that is linked directly to the specified ListStructure.
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

Modifier and Type	Method and Description
void	add(java.util.Collection<?> entries) Adds the entries from the specified Collection to this instance.
void	add(java.util.List entries) Deprecated. since 11.0. Use add(Collection). This method is being retained only for binary compatibility with 10.1.3.
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.
java.util.List<java.net.URL>	asList() Returns the contents of the URLPath as a read-only List.
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).
void	expandToIncludeManifestClassPaths() Do not call this method unless you are certain it is necessary.
void	expandToIncludeManifestClassPathsInterruptibly() Do not call this method unless you are certain it is necessary.
java.util.List<java.lang.String>	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.util.List<java.lang.String>	getDirectories(java.lang.String relPath, URLFilter urlFilter) Retrieves the list of all directories existing immediately under a relative path that pass the specified filter.
java.net.URL[]	getEntries() Returns the path represented by thisURLPath instance as an array of URL.
java.util.List<java.net.URL>	getFiles(java.lang.String relPath) Retrieves a list of URLs representing all the files contained under a relative path.
java.util.List<java.net.URL>	getFiles(java.lang.String relPath, URLFilter urlFilter) Retrieves a list of URLs representing all the files contained under a relative path that pass the specified filter.
java.util.List	getFilesAndDirectories(java.lang.String relPath, boolean dirsBeforeFiles) Returns a List of URLs for all the files and directories contained within the specified relPath, relative to this URLPath.
java.util.List<java.net.URL>	getFilesAndDirectories(java.lang.String relPath, boolean dirsBeforeFiles, URLFilter urlFilter) Returns a List of URLs for all the files and directories that pass the specified filter and are contained within the specified relPath, relative to this URLPath.
java.net.URL	getFirstEntry() Convenience method to get the first URL entry contained within the URLPath.
java.net.URL	getLongestMatchingEntry(java.net.URL url) Returns the URLPath entry that is the closest parent to the specified URL.
static URLPath	getURLPath(HashStructure hash, java.lang.String urlPathName) Retrieves the URLPath that is stored within the specified HashStructure at the specified name.
java.util.Iterator<java.net.URL>	iterator() Returns an Iterator whose elements are all instances of URL.
java.lang.Object	iteratorLock() Get the Object whose intrinsic lock which must be held while iterating this path using the iterator returned by iterator().
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	remove(java.net.URL[] entries)
void	remove(URLPath urlPath)
void	setEntries(java.net.URL[] entries) Sets the path represented by this URLPath instance to be equivalent to the specified array of URLs.
static boolean	setURLPath(HashStructure hash, java.lang.String urlPathName, URLPath urlPath) Stores the specified URLPath into the HashStructure at the specified name.
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.net.URL[]	toQualifiedURL(java.lang.String relativePath, boolean firstMatch) Given a relative spec, this method attempts to construct an array of fully qualified URLs 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	toShortestRelativePath(java.net.URL url) Returns the path for the URL relative to the closest parent on this 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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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(ListStructure entries)

Creates a URLPath instance that is linked directly to the specified ListStructure. Any changes made to the URLPath will be reflected in the ListStructure and vice versa.

Throws:

java.lang.IllegalArgumentException - if any item in the ListStructure is null or is not a URL.

URLPath

public URLPath(java.util.List entries)

Creates a URLPath instance that is linked directly to the specified List. Any changes made to the URLPath will be reflected in the List and vice versa.

If the URLPath or the underlying List will be used on more than one thread, it is the callers responsibility to ensure that the List is a thread-safe implementation, such as those returned by the java.util.Collections.synchronized... methods. Further, it is assumed that the lock used to synchornize access to the List is the intrinsic lock of the List itself.

Throws:

java.lang.IllegalArgumentException - if any item in the List is null or is not a URL.

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(java.util.Collection<?> entries)

Adds the entries from the specified Collection to this instance. The collection is not bound to the URLPath in any way; the items are simply copied from the specified collection into this URLPath instance.

Parameters:

entries - a collection of entries to add. If null is passed, the URLPath will not be modified.

add

@Deprecated
public void add(java.util.List entries)

Deprecated. since 11.0. Use add(Collection). This method is being retained only for binary compatibility with 10.1.3.

This method is retained only for binary compatibility with 10.1.3.

add

public void add(URLPath urlPath)

Adds the entries from the specified URLPath to this instance.

asList

public java.util.List<java.net.URL> asList()

Returns the contents of the URLPath as a read-only List.

Note that this method must create a copy of the underying URL list for thread safety. If you are just using this method to iterate the URL instances, it is generally more efficient to use the iterator() method, while holding the lock returned by iteratorLock(). If you are calling this method just to get the first entry, then it is much more efficient to call {#getFirstEntry} instead.

getEntries

public java.net.URL[] getEntries()

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

Note that this method copies the underying URL list into an array. If you are just using this method to iterate the URL instances, it is generally more efficient to use the iterator() method, while holding the lock returned by iteratorLock(). If you are calling this method just to get the first entry, then it is much more efficient to call {#getFirstEntry} instead.

Returns:

the URL entries in this path, or an empty array if the path is empty

contains

public boolean contains(java.net.URL entry)

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

getAllDirectories

public java.util.List<java.lang.String> 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.

expandToIncludeManifestClassPaths

public void expandToIncludeManifestClassPaths()

Do not call this method unless you are certain it is necessary. It is a low-level expansion operation that is typically already performed by compile-time tools and runtime environments, so this will only drag performance if used haphazardly.

This method iterates through each URL currently in in this URLPath, and if the URL is for a jar file, checks if the jar file has a manifest file with a Class-Path main attribute, and if that attribute exists, expands this URLPath to reference those jars and directories explicitly. This expansion proceeds recursively, avoiding duplicates and cycles, until all Class-Path attributes have attributes have been expanded. Calling this method performs the operation only once. Any URLs added subsequently will not be expanded automatically; another call to expandToIncludeManifestClassPaths() would be necessary.

Since:

11.0

expandToIncludeManifestClassPathsInterruptibly

public void expandToIncludeManifestClassPathsInterruptibly()
                                                    throws java.lang.InterruptedException

Do not call this method unless you are certain it is necessary. It is a low-level expansion operation that is typically already performed by compile-time tools and runtime environments, so this will only drag performance if used haphazardly.

This method iterates through each URL currently in in this URLPath, and if the URL is for a jar file, checks if the jar file has a manifest file with a Class-Path main attribute, and if that attribute exists, expands this URLPath to reference those jars and directories explicitly. This expansion proceeds recursively, avoiding duplicates and cycles, until all Class-Path attributes have attributes have been expanded. Calling this method performs the operation only once. Any URLs added subsequently will not be expanded automatically; another call to expandToIncludeManifestClassPaths() would be necessary.

Throws:

java.lang.InterruptedException - if the calling thread is interrupted while expanding the path

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.

getDirectories

public java.util.List<java.lang.String> getDirectories(java.lang.String relPath,
                                                       URLFilter urlFilter)

Retrieves the list of all directories existing immediately under a relative path that pass the specified filter. If the filter is null, all directories are accepted. 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<java.net.URL> 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.

getFiles

public java.util.List<java.net.URL> getFiles(java.lang.String relPath,
                                             URLFilter urlFilter)

Retrieves a list of URLs representing all the files contained under a relative path that pass the specified filter. If the filter is null, all files are accepted.

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 for all the files and directories contained within the specified relPath, relative to this URLPath.

getFilesAndDirectories

public java.util.List<java.net.URL> getFilesAndDirectories(java.lang.String relPath,
                                                           boolean dirsBeforeFiles,
                                                           URLFilter urlFilter)

Returns a List of URLs for all the files and directories that pass the specified filter and are contained within the specified relPath, relative to this URLPath. If the filter is null, all files and directories are accepted.

getFirstEntry

public java.net.URL getFirstEntry()

Convenience method to get the first URL entry contained within the URLPath.

Returns:

URL The first URL in the URLPath, or null if the path is empty

getURLPath

public static URLPath getURLPath(HashStructure hash,
                                 java.lang.String urlPathName)

Retrieves the URLPath that is stored within the specified HashStructure at the specified name. For the retrieval to succeed, the URLPath must have been stored into the HashStructure with setURLPath(HashStructure, String, URLPath). If the HashStructure does not contain any property by the specified urlPathName, an empty URLPath is returned. This method will never return null.

setURLPath

public static boolean setURLPath(HashStructure hash,
                                 java.lang.String urlPathName,
                                 URLPath urlPath)

Stores the specified URLPath into the HashStructure at the specified name. The URLPath can subsequently be retrieved by calling getURLPath(HashStructure, String). If the URLPath is null, the corresponding ListStructure in the HashStructure is deleted. To set an empty ListStructure instead, pass in a non-null, empty URLPath. Returns true if the underlying storage was modified; false otherwise. If the specified URLPath is identical to what was already stored in the HashStructure, then no modification is made and this method returns false.

iterator

public java.util.Iterator<java.net.URL> 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.

You must hold the lock returned by iteratorLock() while using the iterator returned by this method. Failure to do so can result in ConcurrentModificationException.

Specified by:

iterator in interface java.lang.Iterable<java.net.URL>

iteratorLock

public java.lang.Object iteratorLock()

Get the Object whose intrinsic lock which must be held while iterating this path using the iterator returned by iterator(). This includes both explicit calls to iterator() as well as implicit calls made by for-each loops.

Returns:

the Object whose intrinsic lock which must be held while iterating this path

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)

remove

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

remove

public void remove(URLPath urlPath)

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 asList() would then return an empty URL list.

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 oracle.ide.model.Node. If in-memory resources are desired as well, use toBoundURL(String) instead.

See Also:

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

toQualifiedURL

public java.net.URL[] toQualifiedURL(java.lang.String relativePath,
                                     boolean firstMatch)

Given a relative spec, this method attempts to construct an array of fully qualified URLs 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 oracle.ide.model.Node. If in-memory resources are desired as well, use toBoundURL(String) 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 URLExistsTest 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.

toShortestRelativePath

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

Returns the path for the URL relative to the closest parent on this URLPath. It is not necessarily the same as the first matching parent on the URLPath. To get the first matching parent, use toRelativePath(URL). If no entry on this URLPath is a parent for the specified URL or if the specified URL is null, this method returns null.

getLongestMatchingEntry

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

Returns the URLPath entry that is the closest parent to the specified URL. Returns null if no entry is a parent for the specified URL.

toStrings

public java.lang.String[] toStrings()

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

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()

Overrides:

toString in class java.lang.Object

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.