ucar.httpservices

Class HTTPMethod

java.lang.Object

ucar.httpservices.HTTPMethod

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class HTTPMethod
extends java.lang.Object
implements java.io.Closeable

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.

In practice, one has an HTTPMethod instance, one can repeat the steps 2-5. Of course this assumes that one is doing the same kind of action (e.g. GET).

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.

3. It may be specified as an argument to the execute() method. If none is specified, then the factory constructor URL is used (which might, in turn have come from the session).

Legal url arguments to HTTPMethod are constrained by the URL specified in creating the HTTPSession instance, if any. If the session was constructed with a specified URL, then any url specified to HTTMethod (via the factory or via execute()) 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 tricky 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 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().
• Closing the method (directly or through stream.close()) will close the one-shot session created by the method.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	closed
protected org.apache.http.HttpEntity	content
protected java.util.List<org.apache.http.Header>	headers
protected boolean	localsession
protected ucar.httpservices.HTTPSession.Methods	methodkind
protected HTTPMethodStream	methodstream
protected java.net.URI	methodurl
protected long[]	range
protected org.apache.http.client.methods.HttpRequestBase	request
protected org.apache.http.client.methods.CloseableHttpResponse	response
protected HTTPSession	session
protected java.lang.String	userinfo

Method Summary

Modifier and Type	Method and Description
protected org.apache.http.client.methods.RequestBuilder	buildrequest()
boolean	canHoldContent()
void	close() Calling close will force the method to close, and will force any open stream to terminate.
org.apache.http.HttpMessage	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.
static java.util.Set<java.lang.String>	getAllowedMethods()
java.lang.String	getCharSet()
org.apache.http.client.config.RequestConfig	getDebugConfig()
java.lang.String	getMethodKind()
java.lang.String	getName() Deprecated.
java.lang.String	getPath()
org.apache.http.Header	getRequestHeader(java.lang.String name)
org.apache.http.Header[]	getRequestHeaders()
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()
org.apache.http.Header	getResponseHeader(java.lang.String name)
org.apache.http.Header[]	getResponseHeaders()
HTTPSession	getSession()
int	getStatusCode()
java.lang.String	getStatusLine()
java.lang.String	getStatusText()
java.lang.String	getURL()
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)
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	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

session

protected HTTPSession session

localsession

protected boolean localsession

methodurl

protected java.net.URI methodurl

userinfo

protected java.lang.String userinfo

content

protected org.apache.http.HttpEntity content

methodkind

protected ucar.httpservices.HTTPSession.Methods methodkind

methodstream

protected HTTPMethodStream methodstream

closed

protected boolean closed

request

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

response

protected org.apache.http.client.methods.CloseableHttpResponse response

range

protected long[] range

headers

protected java.util.List<org.apache.http.Header> headers

Method Detail

getAllowedMethods

public static java.util.Set<java.lang.String> getAllowedMethods()

buildrequest

protected org.apache.http.client.methods.RequestBuilder buildrequest()
                                                              throws HTTPException

Throws:

HTTPException

setheaders

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

setcontent

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

execute

public int execute()
            throws HTTPException

Create a request, add headers, and content, then send to HTTPSession to do the bulk of the work.

Throws:

HTTPException

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

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()

getRequestHeader

public org.apache.http.Header getRequestHeader(java.lang.String name)

getResponseHeader

public org.apache.http.Header getResponseHeader(java.lang.String name)

getResponseHeaders

public org.apache.http.Header[] getResponseHeaders()

setRequestContent

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

getCharSet

public java.lang.String getCharSet()

getURL

public java.lang.String getURL()

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)

getRequestHeaders

public org.apache.http.Header[] getRequestHeaders()

getDebugConfig

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

setCompression

public HTTPMethod setCompression(java.lang.String compressors)

setFollowRedirects

public HTTPMethod setFollowRedirects(boolean tf)

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.

debugRequest

public org.apache.http.HttpMessage 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