Package ucar.httpservices

Class HTTPMethod

  • All Implemented Interfaces:
    Closeable, AutoCloseable, Comparable<HTTPMethod>
    @NotThreadSafe
public class HTTPMethod
extends Object
implements Closeable, Comparable<HTTPMethod>
    HTTPMethod is the encapsulation of specific kind of server request: GET, HEAD, POST, etc. The general processing sequence is as follows.
    1. Create an HTTPMethod object using one of the methods of HTTPFactory (e.g. HTTPFactory.Get()).

    2. Set parameters and headers of the returned HTTPMethod instance.

    3. Invoke the execute() method to actually make the request.

    4. Extract response headers.

    5. Extract any body of the response in one of several forms: an Inputstream, a byte array, or a String.

    6. Close the method.
    HTTPMethod is designed, at the moment, to be executed only once. Note also that HTTPMethod is not thread safe but since it cannot be executed multiple times, this should be irrelevant.

    The arguments to the factory method are as follows.

    • An HTTPSession instance (optional).
    • A URL.
    An HTTPMethod instance is assumed to be operating in the context of an HTTPSession instance as specified by the session argument. If not present, the HTTPMethod instance will create a session that will be reclaimed when the method is closed (see the discussion about one-shot operation below).

    Method URLs may be specified in any of three ways.

    1. It may be inherited from the URL specified when the session was created.

    2. It may be specified as part of the HTTPMethod constructor (via the factory). If none is specified, then the session URL is used.

    Legal url arguments to HTTPMethod are constrained by the URL specified in creating the HTTPSession instance. If the session was constructed with a specified URL, then any url specified to HTTMethod (via the factory) must be "compatible" with the session URL. The term "compatible" basically means that the session url's host+port is the same as that of the specified method url. This maintains the semantics of the Session but allows flexibility in accessing data from the server.

    One-Shot Operation: A reasonably common use case is when a client wants to create a method, execute it, get the response, and close the method. For this use case, creating a session and making sure it gets closed can be a tedious proposition. To support this use case, HTTPMethod supports what amounts to a one-shot use. The steps are as follows:

    1. HTTPMethod method = HTTPFactory.Get(); note that this implicitly creates a session internal to the method instance.

    2. Set any session parameters or headers using method.getSession().setXXX

    3. Set any parameters and headers on method

    4. method.execute();

    5. Get any response method headers

    6. InputStream stream = method.getResponseBodyAsStream()

    7. process the stream

    8. stream.close()
    There are several things to note.
    • Closing the method (directly or through stream.close()) will close the one-shot session created by the method.
    • Closing the stream will close the underlying method, so it is not necessary to call method.close(). However, if you, for example, get the response body using getResponseBodyAsString(), then you need to explicitly call method.close(). The reason is that the stream is likely to be passed out of the scope in which the method was created, hence method.close() is not easily accessible. In the second case, however, this will occur in the same scope as the method and so method.close() is accessible.

    For testing purposes, it is possible to set a special execution action (see executeRaw).

    • Field Detail

      • TESTING

        public static boolean TESTING

      • islocalsession

        protected boolean islocalsession

      • methodurl

        protected URI methodurl

      • userinfo

        protected String userinfo

      • content

        protected org.apache.http.HttpEntity content

      • lastrequest

        protected org.apache.http.client.methods.HttpRequestBase lastrequest

      • lastresponse

        protected org.apache.http.HttpResponse lastresponse

      • range

        protected long[] range

      • closed

        protected boolean closed

      • executed

        protected boolean executed

      • settings

        protected Map<ucar.httpservices.HTTPSession.Prop,​Object> settings

      • debugconfig

        protected org.apache.http.client.config.RequestConfig debugconfig

    • Method Detail

      • setcontent

        protected void setcontent​(org.apache.http.client.methods.RequestBuilder rb)

      • close

        public void close()
        Calling close will force the method to close, and will force any open stream to terminate. If the session is local, Then that too will be closed.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable

      • execute

        public int execute()
            throws HTTPException
        Create a request, add headers, and content, then send to HTTPSession to do the bulk of the work.
        Returns:
        statuscode
        Throws:
        HTTPException

      • executeRaw

        public org.apache.http.HttpResponse executeRaw()
                                        throws HTTPException
        Create a request, add headers, and content, then send to HTTPSession to do the bulk of the work.
        Returns:
        statuscode
        Throws:
        HTTPException

      • buildRequestConfig

        protected org.apache.http.client.config.RequestConfig buildRequestConfig​(Map<ucar.httpservices.HTTPSession.Prop,​Object> settings)
                                                                  throws HTTPException
        Throws:
        HTTPException

      • configClient

        protected void configClient​(org.apache.http.impl.client.HttpClientBuilder cb,
                            Map<ucar.httpservices.HTTPSession.Prop,​Object> settings)
                     throws HTTPException
        Throws:
        HTTPException

      • setheaders

        protected void setheaders​(org.apache.http.client.methods.RequestBuilder rb,
                          Map<String,​String> headers)

      • getRequestBuilder

        protected org.apache.http.client.methods.RequestBuilder getRequestBuilder()
                                                                   throws HTTPException
        Throws:
        HTTPException

      • buildRequest

        protected org.apache.http.client.methods.HttpRequestBase buildRequest​(org.apache.http.client.methods.RequestBuilder rb,
                                                                      Map<ucar.httpservices.HTTPSession.Prop,​Object> settings)
                                                               throws HTTPException
        Throws:
        HTTPException

      • getMethodKind

        public String getMethodKind()

      • getStatusCode

        public int getStatusCode()

      • getStatusLine

        public String getStatusLine()

      • getRequestLine

        public String getRequestLine()

      • getPath

        public String getPath()

      • canHoldContent

        public boolean canHoldContent()

      • getResponseBodyAsStream

        public InputStream getResponseBodyAsStream()

      • getResponseAsStream

        public InputStream getResponseAsStream()

      • getResponseAsBytes

        public byte[] getResponseAsBytes​(int maxbytes)

      • getResponseAsBytes

        public byte[] getResponseAsBytes()

      • getResponseAsString

        public String getResponseAsString​(String charset)

      • getResponseAsString

        public String getResponseAsString()

      • getRequestHeaders

        public com.google.common.collect.Multimap<String,​String> getRequestHeaders()
        Get all Request headers as a map of name to list of values. A value may be null.
        Returns:
        Map, may be empty but not null.

      • getResponseHeaders

        public com.google.common.collect.Multimap<String,​String> getResponseHeaders()
        Get all Response headers as a map of name to list of values. A value may be null.
        Returns:
        Map, may be empty but not null.

      • getRequestHeaderValues

        public com.google.common.collect.ImmutableSortedMap<String,​com.google.common.collect.ImmutableList<HttpNameValue>> getRequestHeaderValues()

      • getResponseHeaderValues

        public com.google.common.collect.ImmutableSortedMap<String,​com.google.common.collect.ImmutableList<HttpNameValue>> getResponseHeaderValues()

      • setRequestContent

        public HTTPMethod setRequestContent​(org.apache.http.HttpEntity content)

      • getCharSet

        public String getCharSet()

      • getURI

        public URI getURI()

      • getStatusText

        public String getStatusText()

      • getResponseCharSet

        public String getResponseCharSet()

      • isSessionLocal

        public boolean isSessionLocal()

      • hasStreamOpen

        public boolean hasStreamOpen()

      • isClosed

        public boolean isClosed()

      • setRange

        public HTTPMethod setRange​(long lo,
                           long hi)

      • setFollowRedirects

        public HTTPMethod setFollowRedirects​(boolean tf)

      • setMaxRedirects

        public HTTPMethod setMaxRedirects​(int n)

      • setSOTimeout

        public HTTPMethod setSOTimeout​(int n)

      • setUseSessions

        public HTTPMethod setUseSessions​(boolean tf)

      • sessionCompatible

        protected boolean sessionCompatible​(org.apache.http.auth.AuthScope other)
        Test that the given url is "compatible" with the session specified dataset. Wrapper around HTTPAuthUtil.httphostCompatible().
        Parameters:
        other - to test for compatibility against this method's
        Returns:
        true if compatible, false otherwise.

      • sessionCompatible

        protected boolean sessionCompatible​(URI otheruri)

      • sessionCompatible

        @Deprecated
protected boolean sessionCompatible​(org.apache.http.HttpHost otherhost)
        Deprecated.

      • getDebugConfig

        public org.apache.http.client.config.RequestConfig getDebugConfig()

      • debugRequest

        public org.apache.http.client.methods.HttpRequestBase debugRequest()

      • debugResponse

        public org.apache.http.HttpResponse debugResponse()

      • getName

        @Deprecated
public String getName()
        Deprecated.
        Deprecated: use getMethodKind
        Returns:
        Name of the method: e.g. GET, HEAD, ...