Package org.apache.pivot.web

Class Query<V>

  • Type Parameters:
    V - The type of the value retrieved or sent via the query. For GET operations, it is Object; for POST operations, the type is URL. For PUT and DELETE, it is Void.
    Direct Known Subclasses:
    DeleteQuery, GetQuery, PostQuery, PutQuery
    public abstract class Query<V>
extends IOTask<V>
    Abstract base class for web queries. A web query is an asynchronous operation that executes one of the following HTTP methods:
    • GET
    • POST
    • PUT
    • DELETE

    • Constructor Detail

      • Query

        public Query​(java.lang.String hostname,
             int port,
             java.lang.String path,
             boolean secure,
             java.util.concurrent.ExecutorService executorService)
        Creates a new web query.
        Parameters:
        hostname - Name of the host to contact for this web query.
        port - Port number on that host.
        path - The resource path on the host that is the target of this query.
        secure - A flag to say whether to use http or https as the protocol.
        executorService - The executor to use for running the query (in the background).
        Throws:
        java.lang.IllegalArgumentException - if the URL cannot be constructed.

    • Method Detail

      • getHostname

        public java.lang.String getHostname()

      • getPath

        public java.lang.String getPath()

      • getPort

        public int getPort()

      • isSecure

        public boolean isSecure()

      • getHostnameVerifier

        public javax.net.ssl.HostnameVerifier getHostnameVerifier()

      • setHostnameVerifier

        public void setHostnameVerifier​(javax.net.ssl.HostnameVerifier hostnameVerifier)

      • getProxy

        public java.net.Proxy getProxy()
        Gets the proxy associated with this query.
        Returns:
        This query's proxy, or null if the query is using the default JVM proxy settings

      • setProxy

        public void setProxy​(java.net.Proxy proxy)
        Sets the proxy associated with this query.
        Parameters:
        proxy - This query's proxy, or null to use the default JVM proxy settings

      • getLocation

        public java.net.URL getLocation()

      • getParameters

        public QueryDictionary getParameters()
        Returns the web query's parameter dictionary. Parameters are passed via the query string of the web query's URL.
        Returns:
        The current set of query parameters.

      • getRequestHeaders

        public QueryDictionary getRequestHeaders()
        Returns the web query's request header dictionary. Request headers are passed via HTTP headers when the query is executed.
        Returns:
        The current set of request headers.

      • getResponseHeaders

        public QueryDictionary getResponseHeaders()
        Returns the web query's response header dictionary. Response headers are returned via HTTP headers when the query is executed.
        Returns:
        The current set of response headers.

      • getStatus

        public int getStatus()
        Returns the status of the most recent execution.
        Returns:
        An HTTP code representing the most recent execution status.

      • getSerializer

        public Serializer<?> getSerializer()
        Returns the serializer used to stream the value passed to or from the web query. By default, an instance of JSONSerializer is used.
        Returns:
        The current serializer.

      • setSerializer

        public void setSerializer​(Serializer<?> serializer)
        Sets the serializer used to stream the value passed to or from the web query.
        Parameters:
        serializer - The serializer (must be non-null).
        Throws:
        java.lang.IllegalArgumentException - if the input is null.

      • getBytesSent

        public long getBytesSent()
        Gets the number of bytes that have been sent in the body of this query's HTTP request. This will only be non-zero for POST and PUT requests, as GET and DELETE requests send no content to the server.

        For POST and PUT requests, this number will increment in between the connected and requestSent phases of the QueryListener lifecycle methods. Interested listeners can poll for this value during that phase.

        Returns:
        Number of bytes sent by POST or PUT requests, or 0 for GET and DELETE.

      • getBytesReceived

        public long getBytesReceived()
        Gets the number of bytes that have been received from the server in the body of the server's HTTP response. This will generally only be non-zero for GET requests, as POST, PUT, and DELETE requests generally don't solicit response content from the server.

        This number will increment in between the requestSent and responseReceived phases of the QueryListener lifecycle methods. Interested listeners can poll for this value during that phase.

        Returns:
        The number of bytes received.

      • getBytesExpected

        public long getBytesExpected()
        Gets the number of bytes that are expected to be received from the server in the body of the server's HTTP response. This value reflects the Content-Length HTTP response header and is thus merely an expectation. The actual total number of bytes that will be received is not known for certain until the full response has been received.

        If the server did not specify a Content-Length HTTP response header, a value of -1 will be returned to indicate that this value is unknown.

        Returns:
        The expected number of bytes to received based on the content length.