Package com.facilita.fc.web

Class Url

  • public class Url
extends java.lang.Object
    Represents a URL, specified by a protocol, optional credentials host, port, path, optional query data, and optional reference.

    e.g. protocol://user:password@host:port/path?query_data#reference

    A Url object is immutable - that is, it cannot be changed after it has been created. To modify a URL, various with*() methods can be used on an existing Url object to create a copy of the object with different attributes.

    A Url object may not necessarily represent a valid URL.

    • Constructor Summary

      Constructors 
      Constructor Description
      Url​(long cPtr, boolean cMemoryOwn)
      For internal use only.
      Url​(Protocol protocol, IpEndPoint ipEndPoint)
      Creates a Url object with the specified protocol and ipEndPoint (host/port).
      Url​(Protocol protocol, IpEndPoint ipEndPoint, java.lang.String path)
      Creates a Url object with the specified protocol, ipEndPoint (host/port) and path.
      Url​(Protocol protocol, IpEndPoint ipEndPoint, java.lang.String path, QueryData queryData)
      Creates a Url object with the specified protocol, ipEndPoint (host/port), path and QueryData object.
      Url​(Protocol protocol, IpEndPoint ipEndPoint, java.lang.String path, QueryData queryData, java.lang.String unsafeCharacters)
      Creates a Url object with the specified protocol, ipEndPoint (host/port), path and QueryData object.
      Url​(Protocol protocol, IpEndPoint ipEndPoint, java.lang.String path, java.lang.String queryText)
      Creates a Url object with the specified protocol, ipEndPoint (host/port), path and queryText String.
      Url​(Protocol protocol, java.lang.String host)
      Creates a Url object with the specified protocol and host.
      Url​(Protocol protocol, java.lang.String host, java.lang.String path)
      Creates a Url object with the specified protocol, host and path.
      Url​(Url url, java.lang.String relativeUrlText, boolean checkSlash)
      For internal use only.
      Url​(java.lang.String urlText)
      Creates a Url object from the specified urlText.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Url appendPath​(java.lang.String path)
      Creates a new Url object using the attributes of this Url, but with the specified path appended to the existing path.
      void delete()  
      static long getCPtr​(Url obj)
      For internal use only.
      java.lang.String getDirectoryPath()
      Gets the directory components of the path in this Url, excluding the filename.
      java.lang.String getEncodedPathAndQuery()
      Gets the section of the URL used in an HTTP request.
      java.lang.String getFileName()
      Gets the name of the file at the end of the path in this Url.
      IpEndPoint getIpEndPoint()
      Gets the IpEndPoint pointed to by this Url.
      java.lang.String getPassword()
      Gets the password specified in this Url.
      java.lang.String getPath()
      Gets the path component of this Url, excluding the first / after the hostname.
      Protocol getProtocol()
      Gets the Protocol used for this Url.
      java.lang.String getQuery()
      Gets the percent-encoded query data section of this Url.
      QueryData getQueryData()
      Get a QueryData object representing the query data section of this Url.
      java.lang.String getReference()
      Gets the reference (also known as the fragment ID) of this Url.
      java.lang.String getUser()
      Gets the username specified in this Url.
      boolean isRelativePath()
      Returns true if the return value of getPath() doesn't begin with /.
      boolean isStandardPortForProtocol()
      Returns true if a standard port is being used.
      java.lang.String toString()
      Returns a String representation of this Url.
      java.lang.String toString​(boolean encodedPath)
      Returns a String representation of this Url, specifying whether to percent-encode the path.
      java.lang.String toString​(boolean encodedPath, boolean outputStandardPorts)
      Returns a String representation of this Url, specifying whether to percent-encode the path and include the port component of the URL if it is a standard port.
      Url withCredentials​(java.lang.String user, java.lang.String password)
      Creates a new Url object using the attributes of this Url, but with the specified user and password (replacing the existing credentials if present).
      Url withPath​(java.lang.String path)
      Creates a new Url object using the attributes of this Url, but with the specified path (replacing the existing path if present).
      Url withPort​(int port)
      Creates a new Url object using the attributes of this Url, but with the specified port (replacing the existing port if present).
      Url withQuery​(Form form)
      Creates a new Url object using the attributes of this Url, but with query data from the specified Form object (replacing the existing query data if present).
      Url withQuery​(Form form, java.lang.String unsafeCharacters)
      Creates a new Url object using the attributes of this Url, but with query data from the specified Form object percent-encoded using the supplied list of unsafeCharacters (replacing the existing query data if present).
      Url withQuery​(QueryData queryData)
      Creates a new Url object using the attributes of this Url, but with the specified QueryData object (replacing the existing query data if present).
      Url withQuery​(QueryData queryData, java.lang.String unsafeCharacters)
      Creates a new Url object using the attributes of this Url, but with the specified QueryData object (replacing the existing query data if present).
      Url withQuery​(java.lang.String queryText)
      Creates a new Url object using the attributes of this Url, but with the specified queryText String (replacing the existing query data if present).
      Url withReference​(java.lang.String reference)
      Creates a new Url object using the attributes of this Url, but with the specified reference String (replacing the existing reference, also known as the fragment ID, if present).

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Url

        public Url​(long cPtr,
           boolean cMemoryOwn)
        For internal use only. Of no interest to the user.
        Parameters:
        cPtr - pointer to the CPP wrapped object
        cMemoryOwn - indicates if this object is responsible for memory management of the CPP object

      • Url

        public Url​(java.lang.String urlText)
        Creates a Url object from the specified urlText.

        e.g. 

        
 // This will have the default HTTP port (80)
 Url url = new Url("http://www.myCompany.co.uk/index.php");
        Parameters:
        urlText - a String representation of a URL

      • Url

        public Url​(Protocol protocol,
           java.lang.String host)
    throws NoSuchValueException
        Creates a Url object with the specified protocol and host.

        e.g. 

        
 // These will have the default HTTP port (80)
 Url url1 = new Url(Protocol.HTTP, "www.myCompany.co.uk");
 Url url2 = new Url(Protocol.HTTP, "192.168.01.123");
        Parameters:
        protocol - the protocol to use
        host - a dotted IP address or host name
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           IpEndPoint ipEndPoint)
    throws NoSuchValueException
        Creates a Url object with the specified protocol and ipEndPoint (host/port).

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer);
 // This refers to http://www.myCompany.co.uk:8080
        Parameters:
        protocol - the protocol to use
        ipEndPoint - the hostname/IP address and port
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           IpEndPoint ipEndPoint,
           java.lang.String path)
    throws NoSuchValueException
        Creates a Url object with the specified protocol, ipEndPoint (host/port) and path.

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");
 // This refers to http://www.myCompany.co.uk:8080/index.php
        Parameters:
        protocol - the protocol to use
        ipEndPoint - the hostname/IP address and port
        path - the path to be appended to the URL
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           java.lang.String host,
           java.lang.String path)
    throws NoSuchValueException
        Creates a Url object with the specified protocol, host and path.

        e.g. 

        
 // This will have the default HTTP port (80)
 Url url = new Url(Protocol.HTTP, "www.myCompany.co.uk", "index.php");
        Parameters:
        protocol - the protocol to use
        host - a dotted IP address or host name
        path - the path to be appended to the URL
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           IpEndPoint ipEndPoint,
           java.lang.String path,
           QueryData queryData)
    throws NoSuchValueException
        Creates a Url object with the specified protocol, ipEndPoint (host/port), path and QueryData object.

        e.g. 

        
 QueryData queryData = new QueryData();
 queryData.add("sessionID", "12345");

 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php", queryData);
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        protocol - the protocol to use
        ipEndPoint - the hostname/IP address and port
        path - the path to be appended to the URL
        queryData - a collection of key/value pairs to be appended to the URL
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           IpEndPoint ipEndPoint,
           java.lang.String path,
           QueryData queryData,
           java.lang.String unsafeCharacters)
    throws NoSuchValueException
        Creates a Url object with the specified protocol, ipEndPoint (host/port), path and QueryData object.

        The QueryData object will be percent-encoded using the supplied list of unsafeCharacters.

        e.g. 

        
 QueryData queryData = new QueryData();
 queryData.add("sessionID", "12345");

 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php", queryData, "<>\"%{}|\\^[]` \n\t\r&");
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        protocol - the protocol to use
        ipEndPoint - the hostname/IP address and port
        path - the path to be appended to the URL
        queryData - a collection of key/value pairs to be appended to the URL
        unsafeCharacters - a list of unsafe characters that will be percent-encoded in the query data of the URL
        Throws:
        NoSuchValueException - Invalid protocol

      • Url

        public Url​(Protocol protocol,
           IpEndPoint ipEndPoint,
           java.lang.String path,
           java.lang.String queryText)
    throws NoSuchValueException
        Creates a Url object with the specified protocol, ipEndPoint (host/port), path and queryText String.

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php", "sessionID=12345");
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        protocol - the protocol to use
        ipEndPoint - the hostname/IP address and port
        path - the path to be appended to the URL
        queryText - a percent-encoded String of key/value pairs to be appended to the URL, separated by the & character
        Throws:
        NoSuchValueException - Invalid protocol
        See Also:
        Coder.urlEncode(String)

      • Url

        public Url​(Url url,
           java.lang.String relativeUrlText,
           boolean checkSlash)
        For internal use only. Of no interest to the user.
        Parameters:
        url - internal use only
        relativeUrlText - internal use only
        checkSlash - internal use only

    • Method Detail

      • getCPtr

        public static long getCPtr​(Url obj)
        For internal use only. Of no interest to the user.
        Parameters:
        obj - a reference to an object of this class
        Returns:
        a long containing the address of the CPP wrapped object

      • delete

        public void delete()

      • appendPath

        public Url appendPath​(java.lang.String path)
        Creates a new Url object using the attributes of this Url, but with the specified path appended to the existing path.
        Parameters:
        path - the path to append
        Returns:
        a new Url object which is the same as this Url but with the specified path appended to the existing path

      • withPort

        public Url withPort​(int port)
        Creates a new Url object using the attributes of this Url, but with the specified port (replacing the existing port if present).
        Parameters:
        port - the port to add
        Returns:
        a new Url object which is the same as this Url but with the specified port

      • withPath

        public Url withPath​(java.lang.String path)
        Creates a new Url object using the attributes of this Url, but with the specified path (replacing the existing path if present).
        Parameters:
        path - the path to add
        Returns:
        a new Url object which is the same as this Url but with the specified path

      • withCredentials

        public Url withCredentials​(java.lang.String user,
                           java.lang.String password)
        Creates a new Url object using the attributes of this Url, but with the specified user and password (replacing the existing credentials if present).

        If a username and password are present in a URL, they appear before the host.

        e.g. http://username:password@www.myCompany.co.uk

        Parameters:
        user - a username
        password - a password
        Returns:
        a new Url object which is the same as this Url but with the specified user and password

      • withQuery

        public Url withQuery​(java.lang.String queryText)
        Creates a new Url object using the attributes of this Url, but with the specified queryText String (replacing the existing query data if present).

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");

 Url url2 = url.withQuery("sessionID=12345");
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        queryText - a percent-encoded String of key/value pairs to be appended to the URL, separated by the & character
        Returns:
        a new Url object which is the same as this Url but with the specified query data
        See Also:
        for percent-encoding

      • withQuery

        public Url withQuery​(QueryData queryData)
        Creates a new Url object using the attributes of this Url, but with the specified QueryData object (replacing the existing query data if present).

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");

 QueryData queryData = new QueryData();
 queryData.add("sessionID", "12345");

 Url url2 = url.withQuery(queryData);
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        queryData - a collection of key/value pairs to be appended to the URL
        Returns:
        a new Url object which is the same as this Url but with the specified queryData

      • withQuery

        public Url withQuery​(QueryData queryData,
                     java.lang.String unsafeCharacters)
        Creates a new Url object using the attributes of this Url, but with the specified QueryData object (replacing the existing query data if present).

        The QueryData object will be percent-encoded using the supplied list of safeCharacter's.

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");

 QueryData queryData = new QueryData();
 queryData.add("sessionID", "~12345");

 Url url2 = url.withQuery(queryData, Coder.getDefaultUnsafeCharacters() + "~");
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        queryData - a collection of key/value pairs to be appended to the URL
        unsafeCharacters - a list of unsafe characters that will be percent-encoded in the query data of the URL
        Returns:
        a new Url object which is the same as this Url but with the specified queryData

      • withQuery

        public Url withQuery​(Form form)
        Creates a new Url object using the attributes of this Url, but with query data from the specified Form object (replacing the existing query data if present).

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");

 Form form = response.extractForm("contactForm");
 form.getInputElement("sessionID").setValue("12345");

 Url url2 = url.withQuery(form);
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        form - a collection of key/value pairs represented as a HTML form
        Returns:
        a new Url object which is the same as this Url but with query data from the specified form

      • withQuery

        public Url withQuery​(Form form,
                     java.lang.String unsafeCharacters)
        Creates a new Url object using the attributes of this Url, but with query data from the specified Form object percent-encoded using the supplied list of unsafeCharacters (replacing the existing query data if present).

        e.g. 

        
 IpEndPoint myServer = new IpEndPoint("www.myCompany.co.uk", 8080);
 Url url = new Url(Protocol.HTTP, myServer, "index.php");

 Form form = response.extractForm("contactForm");
 form.getInputElement("sessionID").setValue("~12345");

 Url url2 = url.withQuery(form, Coder.getDefaultUnsafeCharacters() + "~");
 // This refers to http://www.myCompany.co.uk:8080/index.php?sessionID=12345
        Parameters:
        form - a collection of key/value pairs represented as a HTML form
        unsafeCharacters - a list of unsafe characters that will be percent-encoded in the query data of the URL
        Returns:
        a new Url object which is the same as this Url but with query data from the specified form

      • getProtocol

        public Protocol getProtocol()
                     throws NoSuchValueException
        Gets the Protocol used for this Url. This appears before the :// at the start of a URL, and is also known as the scheme.
        Returns:
        the protocol used for this Url
        Throws:
        NoSuchValueException - Invalid protocol

      • getIpEndPoint

        public IpEndPoint getIpEndPoint()
        Gets the IpEndPoint pointed to by this Url.
        Returns:
        the host/port combination pointed to by this Url
        See Also:
        withPort(int)

      • getUser

        public java.lang.String getUser()
        Gets the username specified in this Url.

        If a username and password are present, they appear before the host in the URL.

        e.g. http://username:password@www.myCompany.co.uk

        Returns:
        the username specified in this Url, or an empty String if no username is specified
        See Also:
        withCredentials(String, String)

      • getPassword

        public java.lang.String getPassword()
        Gets the password specified in this Url.

        If a username and password are present, they appear before the host in the URL.

        e.g. http://username:password@www.myCompany.co.uk

        Returns:
        the password specified in this Url, or an empty String if no password is specified
        See Also:
        withCredentials(String, String)

      • getPath

        public java.lang.String getPath()
        Gets the path component of this Url, excluding the first / after the hostname.
        Returns:
        the path component of this Url, or an empty String if no path is present
        See Also:
        withPath(String)

      • getQuery

        public java.lang.String getQuery()
        Gets the percent-encoded query data section of this Url.
        Returns:
        the percent-encoded query data section of this Url
        See Also:
        Coder.urlEncode(String), withQuery(QueryData)

      • getQueryData

        public QueryData getQueryData()
        Get a QueryData object representing the query data section of this Url.
        Returns:
        the query data section of this Url.
        See Also:
        getQuery(), withQuery(QueryData)

      • getReference

        public java.lang.String getReference()
        Gets the reference (also known as the fragment ID) of this Url. The reference follows a # at the end of a URL, and is often used to refer to a specific location in a HTML document.

        e.g. http://www.myCompany.co.uk/index.php#chapter3

        Returns:
        the reference of this Url
        See Also:
        withReference(String)

      • getFileName

        public java.lang.String getFileName()
        Gets the name of the file at the end of the path in this Url.

        e.g. 

        
 new Url("http://www.myCompany.co.uk/").getFileName();  // returns ""
 new Url("http://www.myCompany.co.uk/index.php").getFileName();  // returns "index.php"
 new Url("http://www.myCompany.co.uk/directory/subdirectory/").getFileName();  // returns ""
        Returns:
        the name of the file at the end of the path in this Url, or an empty String if this Url has no path component or the path ends with a / character

      • getDirectoryPath

        public java.lang.String getDirectoryPath()
        Gets the directory components of the path in this Url, excluding the filename.

        e.g. 

        
 new Url("http://www.myCompany.co.uk/").getDirectoryPath();  // returns "/"
 new Url("http://www.myCompany.co.uk/directory/index.php").getDirectoryPath();  // returns "/directory"
 new Url("http://www.myCompany.co.uk/directory/subdirectory/").getDirectoryPath();  // returns "/directory/subdirectory"
        Returns:
        the directory components of the path in this Url, excluding the filename, or an empty String if this Url has no path component

      • isRelativePath

        public boolean isRelativePath()
        Returns true if the return value of getPath() doesn't begin with /.
        Returns:
        true if the return value of getPath() doesn't begin with /

      • isStandardPortForProtocol

        public boolean isStandardPortForProtocol()
        Returns true if a standard port is being used.
        Returns:
        true if a standard port is being used

      • toString

        public java.lang.String toString​(boolean encodedPath,
                                 boolean outputStandardPorts)
        Returns a String representation of this Url, specifying whether to percent-encode the path and include the port component of the URL if it is a standard port.
        Parameters:
        encodedPath - true if the path component of the URL should be percent-encoded
        outputStandardPorts - true if the port component of the URL should be included even if it is a standard port for this Url object's protocol
        Returns:
        a String representation of this Url
        See Also:
        Coder.urlEncode(String)

      • toString

        public java.lang.String toString​(boolean encodedPath)
        Returns a String representation of this Url, specifying whether to percent-encode the path.
        Parameters:
        encodedPath - true if the path component of the URL should be percent-encoded
        Returns:
        a String representation of this Url
        See Also:
        Coder.urlEncode(String)

      • toString

        public java.lang.String toString()
        Returns a String representation of this Url.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this Url

      • withReference

        public Url withReference​(java.lang.String reference)
        Creates a new Url object using the attributes of this Url, but with the specified reference String (replacing the existing reference, also known as the fragment ID, if present).

        The reference follows a # at the end of a URL, and is often used to refer to a specific location in a HTML document.

        e.g. http://www.myCompany.co.uk/index.php#chapter3

        Parameters:
        reference - the new reference
        Returns:
        a new Url object which is the same as this Url but with the specified reference