org.gridlab.gat
Class URI

java.lang.Object
  extended by org.gridlab.gat.URI
All Implemented Interfaces:
Serializable, Comparable<Object>

public class URI
extends Object
implements Serializable, Comparable<Object>

This class implements URIs. It is API compatible with the java.net.URI. However, URIs have a slightly different meaning in JavaGAT. The java.net.URI only accepts absolute path names for URIs with a scheme and a host. The JavaGAT URI also accepts relative path names for URIs with a scheme and a host. This may be useful for protocols that have an entry point (the working directory after a connection has been established), which is not the same as the root of the file system.

For instance, if you ssh to a machine, your entry point is typically your $HOME directory, which might be the only place on that machine where you're allowed to do something. It might also be the case that you don't know beforehand the path of your $HOME (it might start with '/home/user' or '/home3/user', etc.). Although you don't know the absolute path name to a file '$HOME/somedir/somefile' in your $HOME, you do know the path name which is relative to the ssh entry point.

Now let's see what would happen if you do want to specify this URI using the java.net.URI:

any://myhost/somedir/somefile

According to the java.net.URI, this URI can be split up in the following parts:

scheme: any
host: myhost
path: /somedir/somefile

It's impossible to specify a path like this:

path: somedir/somefile

We can try by leaving the first '/' of the path out. The URI would then be:

any://myhostsomedir/somefile

Which would be split up in these parts:

scheme: any
host: myhostsomedir
path: /somefile

Which is also not what we want. Therefore the JavaGAT URI semantics aren't exactly the same as the java.net.URI. The JavaGAT URI treats the first '/' of the java.net.URI path not as part of the path, but as a separator between the previous parts of the URI and the path. The 'real' path starts after the first '/'. Let's show a few examples of the JavaGAT URI. Suppose we want to specify the same path somedir/somefile using the JavaGAT URI. This would be:

any://myhost/somedir/somefile

According to JavaGAT URI, this URI can be split up in the following parts:

scheme: any
host: myhost
path: somedir/somefile

Which is exactly what we want. If we did want to specify the absolute path /somedir/somefile, then the URI would be:

any://myhost//somedir/somefile

According to JavaGAT URI, this URI can be split up in the following parts:

scheme: any
host: myhost
path: /somedir/somefile

A few more examples will show correct JavaGAT URIs and how they're split up:

This JavaGAT URI '/somedir/somefile' splits up into:

scheme: null
host: null
path: /somedir/somefile

This JavaGAT URI 'file:somedir/somefile' splits up into:

scheme: file
host: null
path: somedir/somefile

This JavaGAT URI 'any:////somedir/somefile' splits up into:

scheme: any
host: null
path: /somedir/somefile

This JavaGAT URI 'any:///somedir/somefile' splits up into:

scheme: any
host: null
path: somedir/somefile

JavaGAT supports the "any" protocol, which means that any protocol may be used to retrieve this URI.

Please be careful with using the "any" protocol in combination with relative path names! Suppose protocol A has the entry point '/home/user' and protocol B has the entry point '/tmp'. Then the URI 'any://myhost/somedir/somefile' would point to two different location depending on the protocol. So, for protocol A it would be resolved to '/home/user/somedir/somefile' as for B it would be '/tmp/somedir/somefile'.

As far as we know, there is no good general solution for this problem. So, try to use URIs with an absolute path as much as possible, and be careful when you use URIs with relative paths.

One further note: for local files, 'file:///bla' means the file 'bla' in the current directory (which is the directory where the jvm is started), while 'file://hostname/bla' means the file named 'bla' relative to the entry point for the host, just like with the "any" protocol. The entry point in this case is assumed to be your home directory: the user.home system property. The hostname can be either "localhost" or the real hostname for your local machine.

Author:
rob
See Also:
Serialized Form

Nested Class Summary
 class URI.URIEncoder
          A utility class that encodes/decodes Strings into a valid URI format.
 
Constructor Summary
URI(String s)
           
URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
           
URI(String scheme, String authority, String path, String query, String fragment)
           
URI(URI u)
          Constructs a JavaGAT URI out of a URI.
 
Method Summary
 int compareTo(Object other)
          Compares this URI to another object, which must be a URI.
static URI create(String s)
          Creates a URI by parsing the given string.
 boolean equals(Object o)
          Tests this URI for equality with another object.
 String getAuthority()
          Returns the decoded authority component of this URI.
 String getFragment()
          Returns the decoded fragment component of this URI.
 String getHost()
          Returns the host component of this URI.
 String getPath()
          Returns the decoded path component of this URI.
 int getPort()
          Returns the port number of this URI.
 int getPort(int defaultPort)
          Returns the port number of this URI or the default port if the port is undefined.
 String getQuery()
          Returns the decoded query component of this URI.
 String getRawAuthority()
          Returns the raw authority component of this URI.
 String getRawFragment()
          Returns the raw fragment component of this URI.
 String getRawPath()
          Returns the raw path component of this URI.
 String getRawQuery()
          Returns the raw query component of this URI.
 String getRawSchemeSpecificPart()
          Returns the raw scheme-specific part of this URI.
 String getRawUserInfo()
          Returns the raw user-information component of this URI.
 String getScheme()
          Returns the scheme component of this URI.
 String getSchemeSpecificPart()
          Returns the decoded scheme-specific part of this URI.
 String getUnresolvedPath()
           
 String getUserInfo()
          Returns the decoded user-information component of this URI.
 boolean hasAbsolutePath()
          Tells whether or not this URI has an absolute path.
 int hashCode()
          Returns a hash-code value for this URI.
 boolean isAbsolute()
          Tells whether or not this URI is absolute.
 boolean isCompatible(String scheme)
          Checks whether this URI is "compatible" with the given scheme.
 boolean isLocal()
          Small, but not complete check whether this URI refers to the local machine.
 boolean isOpaque()
          Tells whether or not this URI is opaque.
 URI normalize()
          Normalizes this URI's path.
 URI parseServerAuthority()
          Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.
 boolean refersToLocalHost()
          Extensive check whether URI refers to the local machine.
 URI relativize(URI arg0)
          Relativizes the given URI against this URI.
 URI resolve(String arg0)
          Constructs a new URI by parsing the given string and then resolving it against this URI.
 URI resolve(URI arg0)
          Resolves the given URI against this URI.
 String resolveHost()
          Returns the host component of the URI with a resolved host.
 URI setAuthority(String authority)
           
 URI setFragment(String fragment)
           
 URI setHost(String host)
           
 URI setPath(String path)
           
 URI setPort(int port)
           
 URI setQuery(String query)
           
 URI setScheme(String scheme)
           
 URI setUserInfo(String userInfo)
           
 String toASCIIString()
          Returns the content of this URI as a US-ASCII string.
 URI toJavaURI()
          Constructs a java.net.URI out of this URI.
 String toString()
          Returns the content of this URI as a string.
 URL toURL()
          Constructs a URL from this URI.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

URI

public URI(String s)
    throws URISyntaxException
Parameters:
s - The string to be parsed into a URI
Throws:
URISyntaxException
See Also:
URI.URI(String)

URI

public URI(URI u)
Constructs a JavaGAT URI out of a URI.

Parameters:
u - the URI.

URI

public URI(String scheme,
           String userInfo,
           String host,
           int port,
           String path,
           String query,
           String fragment)
    throws URISyntaxException
Throws:
URISyntaxException

URI

public URI(String scheme,
           String authority,
           String path,
           String query,
           String fragment)
    throws URISyntaxException
Throws:
URISyntaxException
Method Detail

create

public static URI create(String s)
                  throws URISyntaxException
Creates a URI by parsing the given string.

Parameters:
s - The string to be parsed into a URI
Returns:
The new URI
Throws:
URISyntaxException
See Also:
URI.create(String)

isLocal

public boolean isLocal()
Small, but not complete check whether this URI refers to the local machine. If the URI contains a hostname it is assumed to be remote. The refersToLocalHost() provides a more extensive check.

Returns:
true if the URI refers to the localhost, false otherwise.

refersToLocalHost

public boolean refersToLocalHost()
Extensive check whether URI refers to the local machine. This method checks for the hostname "localhost", the short hostname, the full hostname and the ip address. When the URI specifies a port number, it is assumed to be a tunnel and this call will return FALSE.

Returns:
true if the URI refers to the localhost, false otherwise

getPath

public String getPath()
Returns the decoded path component of this URI.

Returns:
The decoded path component of this URI, or null if the path is undefined
See Also:
URI.getPath()

getUnresolvedPath

public String getUnresolvedPath()

compareTo

public int compareTo(Object other)
Compares this URI to another object, which must be a URI.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
other - The object to which this URI is to be compared
Returns:
A negative integer, zero, or a positive integer as this URI is less than, equal to, or greater than the given URI
See Also:
URI.compareTo(java.net.URI)

equals

public boolean equals(Object o)
Tests this URI for equality with another object.

Overrides:
equals in class Object
Parameters:
o - The object to which this URI is to be compared
Returns:
true if, and only if, the given object is a URI that is identical to this URI
See Also:
URI.equals(Object)

getAuthority

public String getAuthority()
Returns the decoded authority component of this URI.

Returns:
The decoded authority component of this URI, or null if the authority is undefined
See Also:
URI.getAuthority()

getFragment

public String getFragment()
Returns the decoded fragment component of this URI.

Returns:
The decoded fragment component of this URI, or null if the fragment is undefined
See Also:
URI.getFragment()

getHost

public String getHost()
Returns the host component of this URI.

Returns:
The host component of this URI, or null if the host is undefined
See Also:
URI.getHost()

resolveHost

public String resolveHost()
Returns the host component of the URI with a resolved host. If the URI refers to the local host, this will try to get the local host name and return that. If that fails, "localhost" is returned.

Returns:
the host

getPort

public int getPort()
Returns the port number of this URI.

Returns:
The port component of this URI, or -1 if the port is undefined
See Also:
URI.getPort()

getPort

public int getPort(int defaultPort)
Returns the port number of this URI or the default port if the port is undefined.

Parameters:
defaultPort - the default port
Returns:
the port number of this URI or the default port if the port is undefined

getQuery

public String getQuery()
Returns the decoded query component of this URI.

Returns:
The decoded query component of this URI, or null if the query is undefined
See Also:
URI.getQuery()

getRawAuthority

public String getRawAuthority()
Returns the raw authority component of this URI.

Returns:
The raw authority component of this URI, or null if the authority is undefined
See Also:
URI.getRawAuthority()

getRawFragment

public String getRawFragment()
Returns the raw fragment component of this URI.

Returns:
The raw fragment component of this URI, or null if the fragment is undefined
See Also:
URI.getRawFragment()

getRawPath

public String getRawPath()
Returns the raw path component of this URI.

Returns:
The path component of this URI, or null if the path is undefined
See Also:
URI.getRawPath()

getRawQuery

public String getRawQuery()
Returns the raw query component of this URI.

Returns:
The raw query component of this URI, or null if the query is undefined
See Also:
URI.getRawQuery()

getRawSchemeSpecificPart

public String getRawSchemeSpecificPart()
Returns the raw scheme-specific part of this URI.

Returns:
The raw scheme-specific part of this URI (never null)
See Also:
URI.getRawSchemeSpecificPart()

getRawUserInfo

public String getRawUserInfo()
Returns the raw user-information component of this URI.

Returns:
The raw user-information component of this URI, or null if the user information is undefined
See Also:
URI.getRawUserInfo()

getScheme

public String getScheme()
Returns the scheme component of this URI.

Returns:
The scheme component of this URI, or null if the scheme is undefined
See Also:
URI.getScheme()

getSchemeSpecificPart

public String getSchemeSpecificPart()
Returns the decoded scheme-specific part of this URI.

Returns:
The decoded scheme-specific part of this URI (never null)
See Also:
URI.getSchemeSpecificPart()

getUserInfo

public String getUserInfo()
Returns the decoded user-information component of this URI.

Returns:
The decoded user-information component of this URI, or null if the user information is undefined
See Also:
URI.getUserInfo()

hashCode

public int hashCode()
Returns a hash-code value for this URI.

Overrides:
hashCode in class Object
Returns:
A hash-code value for this URI
See Also:
URI.hashCode()

hasAbsolutePath

public boolean hasAbsolutePath()
Tells whether or not this URI has an absolute path.

Returns:
true if this URI has an absolute path, false otherwise.

isAbsolute

public boolean isAbsolute()
Tells whether or not this URI is absolute.

Returns:
true if, and only if, this URI is absolute
See Also:
URI.isAbsolute()

isOpaque

public boolean isOpaque()
Tells whether or not this URI is opaque.

Returns:
true if, and only if, this URI is opaque
See Also:
URI.isOpaque()

normalize

public URI normalize()
Normalizes this URI's path.

Returns:
A URI equivalent to this URI, but whose path is in normal form
See Also:
URI.normalize()

parseServerAuthority

public URI parseServerAuthority()
                         throws URISyntaxException
Attempts to parse this URI's authority component, if defined, into user-information, host, and port components.

Returns:
A URI whose authority field has been parsed as a server-based authority
Throws:
URISyntaxException - If the authority component of this URI is defined but cannot be parsed as a server-based authority according to RFC 2396
See Also:
URI.parseServerAuthority()

relativize

public URI relativize(URI arg0)
Relativizes the given URI against this URI.

Parameters:
arg0 - The URI to be relativized against this URI
Returns:
The resulting URI
See Also:
URI.relativize(java.net.URI)

resolve

public URI resolve(String arg0)
Constructs a new URI by parsing the given string and then resolving it against this URI.

Parameters:
arg0 - The string to be parsed into a URI
Returns:
The resulting URI
See Also:
URI.resolve(String)

resolve

public URI resolve(URI arg0)
Resolves the given URI against this URI.

Parameters:
arg0 - The URI to be resolved against this URI
Returns:
The resulting URI
See Also:
URI.resolve(java.net.URI)

toASCIIString

public String toASCIIString()
Returns the content of this URI as a US-ASCII string.

Returns:
The string form of this URI, encoded as needed so that it only contains characters in the US-ASCII charset
See Also:
URI.toASCIIString()

toString

public String toString()
Returns the content of this URI as a string.

Overrides:
toString in class Object
Returns:
The string form of this URI
See Also:
URI.toString()

toURL

public URL toURL()
          throws MalformedURLException
Constructs a URL from this URI.

Returns:
A URL constructed from this URI
Throws:
MalformedURLException - If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL
See Also:
URI.toURL()

toJavaURI

public URI toJavaURI()
Constructs a java.net.URI out of this URI.

Returns:
the java.net.URI similar to this URI.

isCompatible

public boolean isCompatible(String scheme)
Checks whether this URI is "compatible" with the given scheme. If this URI has the same scheme, it is compatible. When this URI has "any" as scheme, it is also compatible. If the scheme parameter is "any", this method always returns true. No scheme is interpreted as a "file" scheme.

Parameters:
scheme - the scheme to compare to
Returns:
true: the URIs are compatible

setScheme

public URI setScheme(String scheme)
              throws URISyntaxException
Throws:
URISyntaxException

setUserInfo

public URI setUserInfo(String userInfo)
                throws URISyntaxException
Throws:
URISyntaxException

setHost

public URI setHost(String host)
            throws URISyntaxException
Throws:
URISyntaxException

setAuthority

public URI setAuthority(String authority)
                 throws URISyntaxException
Throws:
URISyntaxException

setPort

public URI setPort(int port)
            throws URISyntaxException
Throws:
URISyntaxException

setPath

public URI setPath(String path)
            throws URISyntaxException
Throws:
URISyntaxException

setQuery

public URI setQuery(String query)
             throws URISyntaxException
Throws:
URISyntaxException

setFragment

public URI setFragment(String fragment)
                throws URISyntaxException
Throws:
URISyntaxException