nl.uva.vlet.vrl
Class VRL

java.lang.Object
  extended by nl.uva.vlet.vrl.VRL
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public final class VRL
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

URI compatible VRL class. Specifies the location of a resource.

This object is NON muteable ! (May not be changed, once instanciated) Use duplicators and/or constructors to modify VRLs!

Currenlty also compatible with the URL class!
Hierarchy: An absolute URL 'is a' VRL 'is a' URI. Note that each class has it subtile differences. Important:
a VRL object is an URI, but not all URIs are Locations! The URI class is used to decode/encode Locations.
One big difference is that "file:///A File" and "file:///A%20File" are different URIs but point to the same VRL ! The VRL URIs are decoded and normalized so they can be compared.
Current used (URI compatible) syntax is:
<scheme>://[<userinfo>@][<hostname[:port]<]/<path>[?<querystring>]

See Also:
VRLStreamHandlerFactory, URI, URL, Serialized Form

Field Summary
static char antiSepChar
          Stupid window backslahes.
static java.lang.String doubleSepCharStr
          Double Seperator character as String.
static char sepChar
          Seperator character.
static java.lang.String sepCharStr
          Seperator character as String.
 
Constructor Summary
VRL(java.lang.String locationString)
          Somewhat more flexible initializer then new URI(String).
VRL(java.lang.String scheme, java.lang.String newhost, int newport, java.lang.String newpath)
          Create new VRL with scheme, hostname, port and path
VRL(java.lang.String scheme, java.lang.String hostname, java.lang.String path)
          Create new VRL with scheme,hostname and path
VRL(java.lang.String scheme, java.lang.String user, java.lang.String host, int newPort, java.lang.String newPath)
          Create new VRL with scheme, userinformation, hostname, port and path
VRL(java.lang.String scheme, java.lang.String host, java.lang.String path, java.lang.String frag)
          Constructs VRL with scheme,hostname,path,fragment
VRL(java.net.URI uri)
          Construct new VRL from URI.
Important: This Constructor does not copy the URI as-is, since a VRL does not support all URI functionality.
VRL(java.net.URL url)
           
VRL(VRL base, java.lang.String relpath)
          Creates new VRL, resolves relative Uri String to baseLocation.
VRL(VRL baseLocation, java.lang.String relativeUri, boolean useDirname)
           
 
Method Summary
static java.lang.String basename(java.lang.String path)
          returns basename part (last part) of path String.
 VRL clone()
           
 int compareTo(VRL loc)
          Compares this location to loc.
static java.lang.String dirname(java.lang.String path)
          Returns the dirname part of the URI compatbile path ! (parent directory path) of path.
 VRL duplicate()
          Same as 'clone()' Method is here for historical reasons.
 VRL duplicateWithAddedPath(java.lang.String dirname)
          Creates new location by appending path to this one
 VRL duplicateWithNewBasename(java.lang.String optNewName)
           
 VRL duplicateWithNewPath(java.lang.String newPath)
          Create duplicate, but setpath to newPath
 VRL duplicateWithNewPort(int val)
          Changing a port in a Location object is not allowed due to the immutable paradigm of Location object (similar to URIs), so to change a port a new object must be created with the changed value.
 VRL duplicateWithNewScheme(java.lang.String newscheme)
          Used for scheme subtitution
static java.lang.String encode(java.lang.String string)
           
static java.lang.String extension(java.lang.String name)
           
 VRL getBaseLocation()
          Returns base VRL without Query ("?...") or Fragment ("#...") part
 java.lang.String getBasename()
           
 java.lang.String getBasename(boolean withExtension)
          returns basename part (last part) of this location.
 java.lang.String getDirname()
          Returns (decoded) parent directory part of path
 java.lang.String getExtension()
          Get last part of filename starting from a '.'
 java.lang.String getFragment()
          Return part afer '#'
 java.lang.String getHostname()
          Returns hostname part of VRL
 VRL getParent()
          Returns new location which *could* be the parent location
 java.lang.String getPassword()
          Deprecated. It is NOT save to use clear text password in any URI!
 java.lang.String getPath()
           
 java.lang.String[] getPathElements()
          Returns array of path elements.
 int getPort()
          Get port part of URI or 0 if non specified/default must be used
 java.lang.String getQuery()
           
 VAttributeSet getQueryAttributes()
          If a query has a set of properties in the form "?name=value&name2=..." return the set of properties as a VAtributeSet.
 java.lang.String[] getQueryParts()
          Returns list of expressions seperated by a '&'
 java.lang.String getRawPath()
          Return 'raw' path as specfied by URI.getRawPath()
 java.lang.String getScheme()
          Get Scheme or service type like: "gftp" from "gftp://" or "srb" from "srb://..."
 java.lang.String getUserinfo()
          Returns user name part form userInfo string Note that for SRB URIs this INCLUDES the domainName like 'user.domain@...' this method strips optional password information.
 java.lang.String getUserInfoWithPassword()
          Returns complete userInfo part of URI.
 int hashCode()
          Returns the hashcode of the String representation of this VRL.
 boolean hasSameServer(VRL remoteLoc)
          Checks wether server hostname and port are the same
static boolean hostnamesAreEquivelant(java.lang.String host1, java.lang.String host2)
          returns true if and only true if both hostnames point to the same physical host.
 boolean isLocalHostname()
           
 boolean isParentOf(VRL subLocation)
          check whether URI (and path) is a parent location of subLocation.
 boolean isRootPath()
           
 boolean isURL()
           
 boolean isVLink()
           
 VRL plus(java.lang.String path)
          Add path and return new VRL
 VRL resolve(java.lang.String reluri)
          Resolves optional relative URI using this URI as base location.
 VRL resolvePath(java.lang.String relpath)
          Resolve DECODED (no %-chars) relative path against this URI, assuming this URI is a (directory) PATH and not a file or url location.
static java.lang.String reverseDNSlookup(java.lang.String name)
          Returns fully qualified hostname by means of reverse DNS lookup
static java.lang.String stripExtension(java.lang.String name)
           
 java.net.URL toDirURL()
          Return URL, but with an added "/".
 java.lang.String toString()
          This method returns the DECODED URI string.
 java.net.URI toURI()
          Returns URI compatible object of VRL.
Here path components might be encoded in %XX format!
use toString for unencoded VRL String.
 java.lang.String toURIString()
          Returns URI compatible and optionally encoded string, use toString() for default (non-encoded) VRL String!
 java.net.URL toURL()
          Since 06-06-2006 this now provides a fully VRL compatible URL object.
static java.lang.String uripath(java.lang.String orgpath)
          Produce URI compatible path (forward slashes) and do other normalization (change 'c:' into '/c:/' This method is mainly used to tranform windows paths...
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

sepChar

public static final char sepChar
Seperator character. Default = '/'

See Also:
Constant Field Values

antiSepChar

public static final char antiSepChar
Stupid window backslahes. URI paths use FORWARD slash

See Also:
Constant Field Values

sepCharStr

public static final java.lang.String sepCharStr
Seperator character as String. Default = "/"

See Also:
Constant Field Values

doubleSepCharStr

public static final java.lang.String doubleSepCharStr
Double Seperator character as String. Default = "//"

See Also:
Constant Field Values
Constructor Detail

VRL

public VRL(java.net.URI uri)
Construct new VRL from URI.
Important: This Constructor does not copy the URI as-is, since a VRL does not support all URI functionality. The URI is stripped and only the currently used fields are used.
In short: a VRL is a URI, but not all URIs are VRLs.

Parameters:
uri -

VRL

public VRL(java.lang.String locationString)
    throws VlURISyntaxException
Somewhat more flexible initializer then new URI(String). Checks for MyVle specified URIs and checks whether the string is %-encoded or decoded. Paths,hostnames, etc are checked and normalized.

Throws:
VlURISyntaxException

VRL

public VRL(java.lang.String scheme,
           java.lang.String host,
           java.lang.String path,
           java.lang.String frag)
Constructs VRL with scheme,hostname,path,fragment


VRL

public VRL(java.lang.String scheme,
           java.lang.String newhost,
           int newport,
           java.lang.String newpath)
Create new VRL with scheme, hostname, port and path


VRL

public VRL(java.lang.String scheme,
           java.lang.String user,
           java.lang.String host,
           int newPort,
           java.lang.String newPath)
Create new VRL with scheme, userinformation, hostname, port and path


VRL

public VRL(java.lang.String scheme,
           java.lang.String hostname,
           java.lang.String path)
Create new VRL with scheme,hostname and path


VRL

public VRL(VRL base,
           java.lang.String relpath)
    throws VlURISyntaxException
Creates new VRL, resolves relative Uri String to baseLocation. Typically this concats 'relativeUri' to 'baseLocation'

Throws:
VlException
VlException
VlURISyntaxException

VRL

public VRL(VRL baseLocation,
           java.lang.String relativeUri,
           boolean useDirname)
    throws VlURISyntaxException
Throws:
VlURISyntaxException

VRL

public VRL(java.net.URL url)
    throws VlException
Throws:
VlException
Method Detail

reverseDNSlookup

public static java.lang.String reverseDNSlookup(java.lang.String name)
Returns fully qualified hostname by means of reverse DNS lookup


hostnamesAreEquivelant

public static boolean hostnamesAreEquivelant(java.lang.String host1,
                                             java.lang.String host2)
returns true if and only true if both hostnames point to the same physical host. For example HOST equivelant with HOST.DOMAIN and/or raw IP-adresses !


getFragment

public java.lang.String getFragment()
Return part afer '#'


toURI

public java.net.URI toURI()
                   throws VlURISyntaxException
Returns URI compatible object of VRL.
Here path components might be encoded in %XX format!
use toString for unencoded VRL String.

Throws:
VlException
VlURISyntaxException
See Also:
toString, URI

hashCode

public int hashCode()
Returns the hashcode of the String representation of this VRL.

Overrides:
hashCode in class java.lang.Object
See Also:
String.hashCode();

toString

public java.lang.String toString()
This method returns the DECODED URI string. For an URI compatible string (with %XX encodeing) use toURI().toString() ! Also, Locations are URI compatible but not all URI Strings are VRL Strings!

Overrides:
toString in class java.lang.Object

getScheme

public java.lang.String getScheme()
Get Scheme or service type like: "gftp" from "gftp://" or "srb" from "srb://..."


getHostname

public java.lang.String getHostname()
Returns hostname part of VRL


getPath

public java.lang.String getPath()
Returns:
decoded path component of URI

getUserInfoWithPassword

public java.lang.String getUserInfoWithPassword()
Returns complete userInfo part of URI. This could contain scheme specific authentication information like a password. To get the user part or password part only, use getUser or getPassword.

Returns:
decoded userinfo component of URI.

getUserinfo

public java.lang.String getUserinfo()
Returns user name part form userInfo string Note that for SRB URIs this INCLUDES the domainName like 'user.domain@...' this method strips optional password information. The get the password string, use getPassword().


getPassword

public java.lang.String getPassword()
Deprecated. It is NOT save to use clear text password in any URI!

Returns password part (if specified !) from userInfo string


getQuery

public java.lang.String getQuery()
Returns:
decoded query component of URI (part after '?')

getQueryParts

public java.lang.String[] getQueryParts()
Returns list of expressions seperated by a '&'


getDirname

public java.lang.String getDirname()
Returns (decoded) parent directory part of path

See Also:
dirname, basename

getExtension

public java.lang.String getExtension()
Get last part of filename starting from a '.'


dirname

public static java.lang.String dirname(java.lang.String path)
Returns the dirname part of the URI compatbile path ! (parent directory path) of path. Note: use VRL.uripath to sanitize and normalize a path!

Special cases:

  • dirname of null is null
  • dirname of the empty string "" is ""
  • The dirname of "/" = "/"

    See Also:
    basename

  • getBasename

    public java.lang.String getBasename(boolean withExtension)
    returns basename part (last part) of this location.

    Parameters:
    withExtension - whether to keep the extension.

    getBasename

    public java.lang.String getBasename()

    isParentOf

    public boolean isParentOf(VRL subLocation)
    check whether URI (and path) is a parent location of subLocation.

    Parameters:
    subLocation -
    Returns:

    compareTo

    public int compareTo(VRL loc)
    Compares this location to loc. Currently String compare is used. So it is important that the toString() method returns same strings for same locations. Note that HOSTNAMEs aliases are NOT checked here. Make sure that fully qualified hostnames are present in the VRL.

    See Also:
    toString

    duplicate

    public VRL duplicate()
    Same as 'clone()' Method is here for historical reasons.


    clone

    public VRL clone()
    Overrides:
    clone in class java.lang.Object

    hasSameServer

    public boolean hasSameServer(VRL remoteLoc)
    Checks wether server hostname and port are the same


    getPort

    public int getPort()
    Get port part of URI or 0 if non specified/default must be used


    getParent

    public VRL getParent()
    Returns new location which *could* be the parent location


    plus

    public VRL plus(java.lang.String path)
    Add path and return new VRL


    duplicateWithAddedPath

    public VRL duplicateWithAddedPath(java.lang.String dirname)
    Creates new location by appending path to this one


    isVLink

    public boolean isVLink()

    stripExtension

    public static java.lang.String stripExtension(java.lang.String name)

    isLocalHostname

    public boolean isLocalHostname()

    isRootPath

    public boolean isRootPath()

    isURL

    public boolean isURL()

    toURL

    public java.net.URL toURL()
                       throws VlURISyntaxException
    Since 06-06-2006 this now provides a fully VRL compatible URL object.

    Returns:
    Throws:
    VlException
    VlURISyntaxException

    getBaseLocation

    public VRL getBaseLocation()
    Returns base VRL without Query ("?...") or Fragment ("#...") part


    getQueryAttributes

    public VAttributeSet getQueryAttributes()
    If a query has a set of properties in the form "?name=value&name2=..." return the set of properties as a VAtributeSet. The property seperator is '&' (ampersand).

    Returns:

    duplicateWithNewPort

    public VRL duplicateWithNewPort(int val)
    Changing a port in a Location object is not allowed due to the immutable paradigm of Location object (similar to URIs), so to change a port a new object must be created with the changed value.

    Parameters:
    val -
    Returns:

    duplicateWithNewPath

    public VRL duplicateWithNewPath(java.lang.String newPath)
    Create duplicate, but setpath to newPath


    duplicateWithNewScheme

    public VRL duplicateWithNewScheme(java.lang.String newscheme)
    Used for scheme subtitution


    getPathElements

    public java.lang.String[] getPathElements()
    Returns array of path elements. For example "/dev/zero" = {"dev","zero"}


    duplicateWithNewBasename

    public VRL duplicateWithNewBasename(java.lang.String optNewName)

    resolve

    public VRL resolve(java.lang.String reluri)
                throws VlURISyntaxException
    Resolves optional relative URI using this URI as base location. Note: the last part (basename) of the URI is stripped, assuming the URI starts from a file, for example "http://myhost/index.html", base location = "http://myhost/". Any relative url starts from "http://myhost/" NOT "http://myhost/index.html" Also the supplied string must match URI paths (be %-encoded).

    Returns:
    Throws:
    VlException
    VlURISyntaxException

    resolvePath

    public VRL resolvePath(java.lang.String relpath)
                    throws VlURISyntaxException
    Resolve DECODED (no %-chars) relative path against this URI, assuming this URI is a (directory) PATH and not a file or url location. The default URI.resolve() method strips the last part (basename) of an URI and uses that as base URI (for example the "index.html" part). Also the relative URIs must be %-coded when they contain spaces ! This method doesn't strip the last part of the URI.

    Parameters:
    relpath -
    Returns:
    Throws:
    VlException
    VlURISyntaxException

    toDirURL

    public java.net.URL toDirURL()
    Return URL, but with an added "/". Some implementations, like Globus, specify that URLs ending with a "/" are (always?) directories ! This is a nice feature but not always the rule.

    Returns:
    URL with as last character a '/'.

    getRawPath

    public java.lang.String getRawPath()
    Return 'raw' path as specfied by URI.getRawPath()

    Returns:
    raw path (undecoded string) of uri.
    See Also:
    URI.getRawPath()

    uripath

    public static java.lang.String uripath(java.lang.String orgpath)
    Produce URI compatible path (forward slashes) and do other normalization (change 'c:' into '/c:/' This method is mainly used to tranform windows paths... Also all path MUST be absolute= starting with a '/' For path comparison it is important to normalize paths. TODO: more efficient string handling, some already replaced with regexp


    encode

    public static java.lang.String encode(java.lang.String string)

    extension

    public static java.lang.String extension(java.lang.String name)

    basename

    public static java.lang.String basename(java.lang.String path)
    returns basename part (last part) of path String.


    toURIString

    public java.lang.String toURIString()
                                 throws VlURISyntaxException
    Returns URI compatible and optionally encoded string, use toString() for default (non-encoded) VRL String!

    Throws:
    VlException
    VlURISyntaxException