oracle.ide.net

Class URLFactory

java.lang.Object

oracle.ide.net.URLFactory

public final class URLFactory
extends java.lang.Object

This class contains methods which create new instances of URL. In order for URLs to be used effectively as keys in a hashtable, the URLs must be created in a very consistent manner. Therefore, when creating a new instance of URL, it is strongly recommended that you use one of the methods in this class rather than calling the URL constructor directly. This will help prevent subtle bugs that can come up when two URL instances that should be equal aren't equal (resulting in caching bugs) because of a difference in some detail of the URL that affects the result of the Object.equals(Object) method but doesn't affect the location pointed to by the URL (which means that code other than the caching will actually continue to work).

Additionally, by using the methods in this class to create instances of URL, dependencies on URL can be tracked more easily.

Method Summary

Modifier and Type	Method and Description
static java.net.URL	copyURL(java.net.URL url) This method returns a new instance of URL that is an exact copy of the specified URL in terms of the protocol, user info, host, port, path, query, and ref.
static java.net.URL	encodeURL(java.net.URL url) Encodes the specified URL into another URL instance in which the parts of the URL are encoded for use with a browser, HTTP server, or opening streams based on an URL.
static java.net.URL	encodeURL(java.net.URL url, java.lang.String encoding)
static java.net.URL	intern(java.net.URL url) Returns a canonical representation for the URL object.
static java.net.URL	newDirURL(java.io.File dir) Creates a new URL with the "file" protocol that is for the specified directory.
static java.net.URL	newDirURL(java.lang.String dirPath) Creates a new URL with the "file" protocol that is for the specified directory.
static java.net.URL	newDirURL(java.lang.String protocol, java.lang.String dirPath) Creates a new URL that is the combination of the specified protocol and the directory path.
static java.net.URL	newDirURL(java.net.URL baseURL, java.lang.String relativeSpec) Creates a new URL that is the combination of the specified base URL and the relative spec string.
static java.net.URL	newFileURL(java.io.File file) This method converts a File instance into an URL instance using an algorithm that is consistent with the other factory methods in URLFactory.
static java.net.URL	newFileURL(java.lang.String filePath) Creates a new URL using the "file" protocol.
static java.net.URL	newIdeURL(java.lang.String protocol, java.net.URL url) Creates a new URL where the specified url protocol is postfixed to the specified protocol.
static java.net.URL	newJarURL(java.io.File archiveFile, java.lang.String entryName) Builds an URL using the "jar" protocol based on the specified archive File and the entry name passed in.
static java.net.URL	newJarURL(java.net.URL archiveURL, java.lang.String entryName) Builds an URL using the "jar" protocol based on the specified archive URL and the entry name passed in.
static java.net.URL	newUniqueURL(java.net.URL baseURL, NameGenerator nameGen) Creates a new unique URL using the protocol of the specified baseURL.
static java.net.URL	newURL(java.lang.String urlSpec)
static java.net.URL	newURL(java.lang.String urlSpec, boolean forceDir, boolean assumeFile)
static java.net.URL	newURL(java.lang.String protocol, java.lang.String path) Standard way of specifying a protocol with a file path.
static java.net.URL	newURL(java.lang.String protocol, java.lang.String userinfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String ref) Creates a new URL whose parts have the exact values that are specified.
static java.net.URL	newURL(java.net.URL baseURL, java.lang.String relativeSpec) Creates a new URL that is the combination of the specified base URL and the relative spec string.
static java.net.URL	replaceHostPart(java.net.URL url, java.lang.String newHost) Returns a new URL that is identical to the specified URL except that the host part of the URL has been replaced with the specified newHost.
static java.net.URL	replacePathPart(java.net.URL url, java.lang.String newPath) Returns a new URL that is identical to the specified URL except that the path part of URL has been replaced with the specified newPath.
static java.net.URL	replacePortPart(java.net.URL url, int newPort) Returns a new URL that is identical to the specified URL except that the port part of the URL has been replaced with the specified newPort.
static java.net.URL	replaceProtocolPart(java.net.URL url, java.lang.String newProtocol) Returns a new URL that is identical to the specified URL except that the protocol part of the URL has been replaced with the specified newProtocol.
static java.net.URL	replaceQueryPart(java.net.URL url, java.lang.String newQuery) Returns a new URL that is identical to the specified URL except that the query part of the URL has been replaced with the specified newQuery.
static java.net.URL	replaceRefPart(java.net.URL url, java.lang.String newRef) Returns a new URL that is identical to the specified URL except that the reference part of the URL has been replaced with the specified newRef.

Methods inherited from class java.lang.Object

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

Method Detail

copyURL

public static java.net.URL copyURL(java.net.URL url)

This method returns a new instance of URL that is an exact copy of the specified URL in terms of the protocol, user info, host, port, path, query, and ref. The only possible difference may be in the URLStreamHandler that is assigned by the URL class.

In general, URLs are immutable, so it not normally necessary to create a copy of an URL. However, under unusual circumstances, it may be necessary to "refresh" an URL so that its associated stream handler is updated to use the currently registered stream handler. This is necessary in situations where a default stream handler is associated with an URL during the IDE's startup sequence before the custom stream handler for the protocol is registered by the owning addin.

Non-sanitizing.

newURL

public static java.net.URL newURL(java.net.URL baseURL,
                                  java.lang.String relativeSpec)

Creates a new URL that is the combination of the specified base URL and the relative spec string. The base URL is treated as a directory, whether or not the URL ends with the "/" character, and the relative spec is always treated as relative, even if it begins with a "/".

Non-sanitizing.

Parameters:

baseURL - the URL of a directory. Must not be null.

relativeSpec - a relative path from the baseURL directory. Must not be null.

newDirURL

public static java.net.URL newDirURL(java.net.URL baseURL,
                                     java.lang.String relativeSpec)

Creates a new URL that is the combination of the specified base URL and the relative spec string. The base URL is treated as a directory whether or not it ends with the "/" character. The returned URL will return with the "/" character in the path part.

Non-sanitizing.

newURL

public static java.net.URL newURL(java.lang.String protocol,
                                  java.lang.String path)

Standard way of specifying a protocol with a file path. The file path is used in the URL verbatim, without any changes to the file separator character or any other characters. For an URL whose protocol is "file", the newFileURL(String) factory method should be used instead.

Non-sanitizing.

newDirURL

public static java.net.URL newDirURL(java.lang.String protocol,
                                     java.lang.String dirPath)

Creates a new URL that is the combination of the specified protocol and the directory path. The directory path is used in the URL verbatim, without any changes to the file separator character or any other characters. The returned URL will return with the "/" character in the path part.

Non-sanitizing.

newUniqueURL

public static java.net.URL newUniqueURL(java.net.URL baseURL,
                                        NameGenerator nameGen)

Creates a new unique URL using the protocol of the specified baseURL. The nameGen object is called to generate a unique name that will be appended to the base url. Non-sanitizing.

replaceProtocolPart

public static java.net.URL replaceProtocolPart(java.net.URL url,
                                               java.lang.String newProtocol)

Returns a new URL that is identical to the specified URL except that the protocol part of the URL has been replaced with the specified newProtocol.

Non-sanitizing.

replacePortPart

public static java.net.URL replacePortPart(java.net.URL url,
                                           int newPort)

Returns a new URL that is identical to the specified URL except that the port part of the URL has been replaced with the specified newPort.

Non-sanitizing.

replaceHostPart

public static java.net.URL replaceHostPart(java.net.URL url,
                                           java.lang.String newHost)

Returns a new URL that is identical to the specified URL except that the host part of the URL has been replaced with the specified newHost.

Non-sanitizing.

replacePathPart

public static java.net.URL replacePathPart(java.net.URL url,
                                           java.lang.String newPath)

Returns a new URL that is identical to the specified URL except that the path part of URL has been replaced with the specified newPath.

Non-sanitizing.

replaceRefPart

public static java.net.URL replaceRefPart(java.net.URL url,
                                          java.lang.String newRef)

Returns a new URL that is identical to the specified URL except that the reference part of the URL has been replaced with the specified newRef.

Non-sanitizing.

replaceQueryPart

public static java.net.URL replaceQueryPart(java.net.URL url,
                                            java.lang.String newQuery)

Returns a new URL that is identical to the specified URL except that the query part of the URL has been replaced with the specified newQuery.

Non-sanitizing.

encodeURL

public static java.net.URL encodeURL(java.net.URL url)

Encodes the specified URL into another URL instance in which the parts of the URL are encoded for use with a browser, HTTP server, or opening streams based on an URL.

encodeURL

public static java.net.URL encodeURL(java.net.URL url,
                                     java.lang.String encoding)

intern

public static java.net.URL intern(java.net.URL url)

Returns a canonical representation for the URL object.

This class maintains a pool of URL objects. If the pool already contains a URL equal to the one passed into this method (as determined by URLFileSystem.equals(URL,URL)), then the instance from the pool is returned. Otherwise, the URL is added to the pool the same instance is returned.

The pool holds URL instances using week references. This allows the URL instances to be garbage collected once the URL is no longer in use. But as long as any pooled instance is in use, any callers of this method are guaranteed to get that same pooled instance.

Generally, this method should be used when a URL object will be stored for a significant amount of time, for instance when it is referenced by an object which is cached in memory. This prevents more than one copy of the URL from being pinned on the heap, which reduces memory usage.

Parameters:

url - the URL to be interned

Returns:

the interned URL

newURL

public static java.net.URL newURL(java.lang.String urlSpec)

newURL

public static java.net.URL newURL(java.lang.String urlSpec,
                                  boolean forceDir,
                                  boolean assumeFile)

newFileURL

public static java.net.URL newFileURL(java.lang.String filePath)

Creates a new URL using the "file" protocol. The specified filePath can be expressed in the notation of the platform that the Java VM is currently running on, or it can be expressed using the forward slash character ("/") as its file separator character, which is the standard file separator for URLs. Note that technically, the forward slash character is the only officially recognized hierarchy separator character for an URL (see RFC 2396).

Sanitizing.

newFileURL

public static java.net.URL newFileURL(java.io.File file)

This method converts a File instance into an URL instance using an algorithm that is consistent with the other factory methods in URLFactory.

Sanitizing.

Returns:

An URL corresponding to the given File. The URL is produced using a mechanism that ensures uniformity of the URL format across platforms.

newDirURL

public static java.net.URL newDirURL(java.lang.String dirPath)

Creates a new URL with the "file" protocol that is for the specified directory. Leading and trailing "/" characters are added if they are missing. If the specified dirPath is null, then the returned URL is null.

Sanitizing.

newDirURL

public static java.net.URL newDirURL(java.io.File dir)

Creates a new URL with the "file" protocol that is for the specified directory. Leading and trailing "/" characters are added if they are missing. This method does not check whether the specified File is actually a directory on disk; it just assumes that it is. If the specified dirPath is null, then the returned URL is null.

Sanitizing.

newIdeURL

public static java.net.URL newIdeURL(java.lang.String protocol,
                                     java.net.URL url)

Creates a new URL where the specified url protocol is postfixed to the specified protocol. The specified protocol must start with "ide.", otherwise, a null URL is returned.

newJarURL

public static java.net.URL newJarURL(java.io.File archiveFile,
                                     java.lang.String entryName)

Builds an URL using the "jar" protocol based on the specified archive File and the entry name passed in. The entry name is relative to the root of the jar file, so it should not begin with a slash. The entry name may be the empty string or null, which means that the returned URL should represent the jar file itself. Sanitizing for archiveFile; non-sanitizing for entryName.

newJarURL

public static java.net.URL newJarURL(java.net.URL archiveURL,
                                     java.lang.String entryName)

Builds an URL using the "jar" protocol based on the specified archive URL and the entry name passed in. The entry name is relative to the root of the jar file, so it should not begin with a slash. The entry name may be the empty string or null, which means that the returned URL should represent the jar file itself.

Non-sanitizing for both archiveURL and entryName.

newURL

public static java.net.URL newURL(java.lang.String protocol,
                                  java.lang.String userinfo,
                                  java.lang.String host,
                                  int port,
                                  java.lang.String path,
                                  java.lang.String query,
                                  java.lang.String ref)

Creates a new URL whose parts have the exact values that are specified. In general, you should avoid calling this method directly.

This method is the ultimate place where all of the other URLFactory methods end up when creating an URL. Non-sanitizing.