|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.gridlab.gat.URI
public class URI
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 /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.
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 |
---|
public URI(String s) throws URISyntaxException
s
- The string to be parsed into a URI
URISyntaxException
URI.URI(String)
public URI(URI u)
URI
.
u
- the URI
.public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException
URISyntaxException
public URI(String scheme, String authority, String path, String query, String fragment) throws URISyntaxException
URISyntaxException
Method Detail |
---|
public static URI create(String s) throws URISyntaxException
s
- The string to be parsed into a URI
URISyntaxException
URI.create(String)
public boolean isLocal()
refersToLocalHost()
provides a more extensive check.
public boolean refersToLocalHost()
public String getPath()
null
if
the path is undefinedURI.getPath()
public String getUnresolvedPath()
public int compareTo(Object other)
compareTo
in interface Comparable<Object>
other
- The object to which this URI is to be compared
URI.compareTo(java.net.URI)
public boolean equals(Object o)
equals
in class Object
o
- The object to which this URI is to be compared
URI.equals(Object)
public String getAuthority()
null
if the authority is undefinedURI.getAuthority()
public String getFragment()
null
if the fragment is undefinedURI.getFragment()
public String getHost()
null
if the
host is undefinedURI.getHost()
public String resolveHost()
public int getPort()
URI.getPort()
public int getPort(int defaultPort)
defaultPort
- the default port
public String getQuery()
null
if the query is undefinedURI.getQuery()
public String getRawAuthority()
null
if the authority is undefinedURI.getRawAuthority()
public String getRawFragment()
null
if
the fragment is undefinedURI.getRawFragment()
public String getRawPath()
null
if the
path is undefinedURI.getRawPath()
public String getRawQuery()
null
if
the query is undefinedURI.getRawQuery()
public String getRawSchemeSpecificPart()
null
)URI.getRawSchemeSpecificPart()
public String getRawUserInfo()
null
if the user information is undefinedURI.getRawUserInfo()
public String getScheme()
null
if the
scheme is undefinedURI.getScheme()
public String getSchemeSpecificPart()
null
)URI.getSchemeSpecificPart()
public String getUserInfo()
null
if the user information is undefinedURI.getUserInfo()
public int hashCode()
hashCode
in class Object
URI.hashCode()
public boolean hasAbsolutePath()
public boolean isAbsolute()
URI.isAbsolute()
public boolean isOpaque()
URI.isOpaque()
public URI normalize()
URI.normalize()
public URI parseServerAuthority() throws URISyntaxException
URISyntaxException
- If the authority component of this URI is defined but
cannot be parsed as a server-based authority according to
RFC 2396URI.parseServerAuthority()
public URI relativize(URI arg0)
arg0
- The URI to be relativized against this URI
URI.relativize(java.net.URI)
public URI resolve(String arg0)
arg0
- The string to be parsed into a URI
URI.resolve(String)
public URI resolve(URI arg0)
arg0
- The URI to be resolved against this URI
URI.resolve(java.net.URI)
public String toASCIIString()
URI.toASCIIString()
public String toString()
toString
in class Object
URI.toString()
public URL toURL() throws MalformedURLException
MalformedURLException
- If a protocol handler for the URL could not be found, or
if some other error occurred while constructing the URLURI.toURL()
public URI toJavaURI()
URI
out of this URI.
URI
similar to this URI.public boolean isCompatible(String scheme)
scheme
- the scheme to compare to
public URI setScheme(String scheme) throws URISyntaxException
URISyntaxException
public URI setUserInfo(String userInfo) throws URISyntaxException
URISyntaxException
public URI setHost(String host) throws URISyntaxException
URISyntaxException
public URI setAuthority(String authority) throws URISyntaxException
URISyntaxException
public URI setPort(int port) throws URISyntaxException
URISyntaxException
public URI setPath(String path) throws URISyntaxException
URISyntaxException
public URI setQuery(String query) throws URISyntaxException
URISyntaxException
public URI setFragment(String fragment) throws URISyntaxException
URISyntaxException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |