uk.ac.starlink.util
Class URLUtils

java.lang.Object
  extended by uk.ac.starlink.util.URLUtils

public class URLUtils
extends java.lang.Object

Provides convenience methods for resolving URLs. This class provides some static methods for turning strings into URLs. This tends to be a bit of a pain in java, since you have to watch out for MalformedURLExceptions all over and work out what the context is. The methods provided here assume that if a string looks like a URL it is one, if it doesn't it's a file name, and if it's not absolute or resolved against a given context it is relative to the current directory. From the point of view of a user providing text to an application, or an XML document providing an href, this is nearly always what is wanted. The strategy can lead to surprising situations in the case that wacky URL protocols are used; for instance if makeURL is called on the string "gftp://host/file" and no gftp handler is installed, it will be interpreted as a file-protocol URL referring to the (presumably non-existent) file "gftp://host/file". In this case the eventual upshot will presumably be a file-not-found type error rather than a MalformedURLException type error getting presented to the user. Users of this class should be of the opinion that this is not a particularly bad thing.

The systemId strings used by Sources have similar semantics to the strings which this class converts to URLs or contexts.

This class assumes that the "file:" protocol is legal for URLs, and will throw AssertionErrors if this turns out not to be the case.


Method Summary
static java.net.URL fixURL(java.net.URL url)
          Fixes file: URLs which don't have enough slashes in them.
static void installCustomHandlers()
          Attempts to install additional URL protocol handlers suitable for astronomy applications.
static java.net.URL makeFileURL(java.io.File file)
          Constructs a legal URL for a given File.
static java.net.URL makeURL(java.lang.String location)
          Obtains a URL from a string.
static java.net.URL makeURL(java.lang.String context, java.lang.String location)
          Obtains a URL from a string in a given context.
static boolean sameResource(java.net.URL url1, java.net.URL url2)
          Attempts to determine whether two URLs refer to the same resource.
static java.io.File urlToFile(java.lang.String url)
          Locates the local file, if any, represented by a URL.
static java.net.URI urlToUri(java.net.URL url)
          Turns a URL into a URI.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

makeURL

public static java.net.URL makeURL(java.lang.String location)
Obtains a URL from a string. If the String has the form of a URL, it is turned directly into a URL. If it does not, it is treated as a filename, and turned into a file-protocol URL. In the latter case a relative or absolute filename may be used. If it is null or a blank string (or something else equally un-filename like?) then null is returned.

Parameters:
location - a string representing the location of a resource
Returns:
a URL representing the location of the resource

makeURL

public static java.net.URL makeURL(java.lang.String context,
                                   java.lang.String location)
Obtains a URL from a string in a given context. The string context is turned into a URL as per the makeURL(String) method, unless it is null or the empty string, in which case it is treated as a reference to the current directory. The string location is then turned into a URL in the same way as using makeURL(String), except that if it represents a relative path it is resolved in the context of context, taking its protocol and/or relative position from it.

Parameters:
context - a string representing the context within which location is to be resolved
location - a string representing the location of a resource
Returns:
a URL representing the location of the resource

urlToUri

public static java.net.URI urlToUri(java.net.URL url)
                             throws java.net.MalformedURLException
Turns a URL into a URI.

Since URIs are syntactically and semantically a superset of URLs, this conversion should not cause any errors. If, however, the input URL is malformed in rather extreme ways, then the URI construction will fail. These ways include (but are not necesssarily limited to) the features discussed in URI.URI(String,String,String,String,String), namely that a scheme is present, but with a relative path, or that it has a registry-based authority part.

Because of the way the class does the conversion, the method will itself resolve some malformations of URLs. You should not rely on this, however, firstly because the method might in principle change, but mostly because you should avoid creating such malformed URLs in the first place.

The most common source of malformed URLs is that of file URLs which have inadequately escaped (windows) drive letters or spaces in the name: such URLs should be constructed using the File.toURI() or File.toURL() methods. Such URLs will be escaped by this method.

Parameters:
url - a URL to be converted. If this is null, then the method returns null
Returns:
the input URL as a URI, or null if the input was null
Throws:
java.net.MalformedURLException - if the URI cannot be constructed because the input URL turns out to be malformed

makeFileURL

public static java.net.URL makeFileURL(java.io.File file)
Constructs a legal URL for a given File. Unlike java, this gives you a URL which conforms to RFC1738 and looks like "file://localhost/abs-path" rather than "file:abs-or-rel-path".

Parameters:
file - file
Returns:
URL
See Also:
"RFC 1738"

fixURL

public static java.net.URL fixURL(java.net.URL url)
Fixes file: URLs which don't have enough slashes in them. Java generates invalid URLs of the form "file:abs-or-rel-path" when it should generate "file://localhost/abs-path".

Parameters:
url - input URL
Returns:
fixed URL
See Also:
"RFC 1738"

sameResource

public static boolean sameResource(java.net.URL url1,
                                   java.net.URL url2)
Attempts to determine whether two URLs refer to the same resource. Not likely to be foolproof, but slightly smarter than using equals.

Parameters:
url1 - first URL
url2 - second URL
Returns:
true if url1 and url2 appear to refer to the same resource

urlToFile

public static java.io.File urlToFile(java.lang.String url)
Locates the local file, if any, represented by a URL. If the URL string uses the "file:" protocol, and has no query or anchor parts, the filename will be extracted and the corresponding file returned. Otherwise, null is returned.

Parameters:
url - URL string
Returns:
local file referenced by url, or null

installCustomHandlers

public static void installCustomHandlers()
Attempts to install additional URL protocol handlers suitable for astronomy applications. Currently installs handlers which can supply MySpace connections using either "ivo:" or "myspace:" protocols.


Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.