ucar.httpservices

Class HTTPMethod

java.lang.Object

ucar.httpservices.HTTPMethod

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Comparable<HTTPMethod>

@NotThreadSafe
public class HTTPMethod
extends java.lang.Object
implements java.io.Closeable, java.lang.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).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HTTPMethod.Executor

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	closed
protected org.apache.http.HttpEntity	content
protected org.apache.http.client.config.RequestConfig	debugconfig
protected boolean	executed
protected java.util.Map<java.lang.String,java.lang.String>	headers
protected boolean	islocalsession
protected org.apache.http.client.methods.HttpRequestBase	lastrequest
protected org.apache.http.HttpResponse	lastresponse
protected HTTPSession.Methods	methodkind
protected HTTPMethodStream	methodstream
protected java.net.URI	methodurl
protected long[]	range
protected HTTPSession	session
protected java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object>	settings
static boolean	TESTING
protected java.lang.String	userinfo

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HTTPMethod()

Method Summary

Modifier and Type	Method and Description
protected org.apache.http.client.methods.HttpRequestBase	buildRequest(org.apache.http.client.methods.RequestBuilder rb, java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings)
protected org.apache.http.client.config.RequestConfig	buildRequestConfig(java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings)
boolean	canHoldContent()
void	close() Calling close will force the method to close, and will force any open stream to terminate.
int	compareTo(HTTPMethod o)
protected void	configClient(org.apache.http.impl.client.HttpClientBuilder cb, java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings)
org.apache.http.client.methods.HttpRequestBase	debugRequest()
org.apache.http.HttpResponse	debugResponse()
int	execute() Create a request, add headers, and content, then send to HTTPSession to do the bulk of the work.
org.apache.http.HttpResponse	executeRaw() Create a request, add headers, and content, then send to HTTPSession to do the bulk of the work.
java.lang.String	getCharSet()
org.apache.http.client.config.RequestConfig	getDebugConfig()
java.lang.String	getMethodKind()
java.lang.String	getName() Deprecated.
java.lang.String	getPath()
protected org.apache.http.client.methods.RequestBuilder	getRequestBuilder()
com.google.common.collect.Multimap<java.lang.String,java.lang.String>	getRequestHeaders() Get all Request headers as a map of name to list of values.
java.util.Optional<java.lang.String>	getRequestHeaderValue(java.lang.String name)
com.google.common.collect.ImmutableSortedMap<java.lang.String,com.google.common.collect.ImmutableList<HttpNameValue>>	getRequestHeaderValues()
java.lang.String	getRequestLine()
byte[]	getResponseAsBytes()
byte[]	getResponseAsBytes(int maxbytes)
java.io.InputStream	getResponseAsStream()
java.lang.String	getResponseAsString()
java.lang.String	getResponseAsString(java.lang.String charset)
java.io.InputStream	getResponseBodyAsStream()
java.lang.String	getResponseCharSet()
com.google.common.collect.Multimap<java.lang.String,java.lang.String>	getResponseHeaders() Get all Response headers as a map of name to list of values.
java.util.Optional<java.lang.String>	getResponseHeaderValue(java.lang.String name)
com.google.common.collect.ImmutableSortedMap<java.lang.String,com.google.common.collect.ImmutableList<HttpNameValue>>	getResponseHeaderValues()
HTTPSession	getSession()
int	getStatusCode()
java.lang.String	getStatusLine()
java.lang.String	getStatusText()
java.net.URI	getURI()
boolean	hasStreamOpen()
boolean	isClosed()
boolean	isSessionLocal()
protected boolean	sessionCompatible(org.apache.http.auth.AuthScope other) Test that the given url is "compatible" with the session specified dataset.
protected boolean	sessionCompatible(org.apache.http.HttpHost otherhost) Deprecated.
protected boolean	sessionCompatible(java.net.URI otheruri)
HTTPMethod	setCompression(java.lang.String compressors)
protected void	setcontent(org.apache.http.client.methods.RequestBuilder rb)
HTTPMethod	setFollowRedirects(boolean tf)
protected void	setheaders(org.apache.http.client.methods.RequestBuilder rb, java.util.Map<java.lang.String,java.lang.String> headers)
HTTPMethod	setMaxRedirects(int n)
HTTPMethod	setMethodHeaders(java.util.List<org.apache.http.Header> headers) Deprecated.
HTTPMethod	setRange(long lo, long hi)
HTTPMethod	setRequestContent(org.apache.http.HttpEntity content)
protected HTTPMethod	setRequestHeader(org.apache.http.Header h) Deprecated.
HTTPMethod	setRequestHeader(java.lang.String name, java.lang.String value) Deprecated.
HTTPMethod	setSOTimeout(int n)
HTTPMethod	setUserAgent(java.lang.String agent)
HTTPMethod	setUseSessions(boolean tf)

Methods inherited from class java.lang.Object

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

Field Detail

TESTING

public static boolean TESTING

session

protected HTTPSession session

islocalsession

protected boolean islocalsession

methodurl

protected java.net.URI methodurl

userinfo

protected java.lang.String userinfo

content

protected org.apache.http.HttpEntity content

methodkind

protected HTTPSession.Methods methodkind

methodstream

protected HTTPMethodStream methodstream

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

headers

protected java.util.Map<java.lang.String,java.lang.String> headers

settings

protected java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings

debugconfig

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

Constructor Detail

HTTPMethod

protected HTTPMethod()
              throws HTTPException

Throws:

HTTPException

Method Detail

compareTo

public int compareTo(HTTPMethod o)

Specified by:

compareTo in interface java.lang.Comparable<HTTPMethod>

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 java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

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(java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings)
                                                                  throws HTTPException

Throws:

HTTPException

configClient

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

Throws:

HTTPException

setheaders

protected void setheaders(org.apache.http.client.methods.RequestBuilder rb,
                          java.util.Map<java.lang.String,java.lang.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,
                                                                      java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> settings)
                                                               throws HTTPException

Throws:

HTTPException

getMethodKind

public java.lang.String getMethodKind()

getStatusCode

public int getStatusCode()

getStatusLine

public java.lang.String getStatusLine()

getRequestLine

public java.lang.String getRequestLine()

getPath

public java.lang.String getPath()

canHoldContent

public boolean canHoldContent()

getResponseBodyAsStream

public java.io.InputStream getResponseBodyAsStream()

getResponseAsStream

public java.io.InputStream getResponseAsStream()

getResponseAsBytes

public byte[] getResponseAsBytes(int maxbytes)

getResponseAsBytes

public byte[] getResponseAsBytes()

getResponseAsString

public java.lang.String getResponseAsString(java.lang.String charset)

getResponseAsString

public java.lang.String getResponseAsString()

getRequestHeaderValue

public java.util.Optional<java.lang.String> getRequestHeaderValue(java.lang.String name)

getRequestHeaders

public com.google.common.collect.Multimap<java.lang.String,java.lang.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.

getResponseHeaderValue

public java.util.Optional<java.lang.String> getResponseHeaderValue(java.lang.String name)

getResponseHeaders

public com.google.common.collect.Multimap<java.lang.String,java.lang.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<java.lang.String,com.google.common.collect.ImmutableList<HttpNameValue>> getRequestHeaderValues()

getResponseHeaderValues

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

setRequestContent

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

getCharSet

public java.lang.String getCharSet()

getURI

public java.net.URI getURI()

getStatusText

public java.lang.String getStatusText()

getResponseCharSet

public java.lang.String getResponseCharSet()

getSession

public HTTPSession getSession()

isSessionLocal

public boolean isSessionLocal()

hasStreamOpen

public boolean hasStreamOpen()

isClosed

public boolean isClosed()

setRange

public HTTPMethod setRange(long lo,
                           long hi)

setCompression

public HTTPMethod setCompression(java.lang.String compressors)

setFollowRedirects

public HTTPMethod setFollowRedirects(boolean tf)

setMaxRedirects

public HTTPMethod setMaxRedirects(int n)

setSOTimeout

public HTTPMethod setSOTimeout(int n)

setUserAgent

public HTTPMethod setUserAgent(java.lang.String agent)

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(java.net.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 java.lang.String getName()

Deprecated.

Deprecated: use getMethodKind

Returns:

Name of the method: e.g. GET, HEAD, ...

setMethodHeaders

@Deprecated
public HTTPMethod setMethodHeaders(java.util.List<org.apache.http.Header> headers)
                                        throws HTTPException

Deprecated.

Throws:

HTTPException

setRequestHeader

@Deprecated
public HTTPMethod setRequestHeader(java.lang.String name,
                                               java.lang.String value)
                                        throws HTTPException

Deprecated.

Throws:

HTTPException

setRequestHeader

@Deprecated
protected HTTPMethod setRequestHeader(org.apache.http.Header h)
                                           throws HTTPException

Deprecated.

Throws:

HTTPException