ucar.httpservices

Class HTTPMethod

java.lang.Object

ucar.httpservices.HTTPMethod

All Implemented Interfaces:

AutoCloseable

public class HTTPMethod
extends Object
implements AutoCloseable

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 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, as a string, must be a prefix of the specified method url. This maintains the semantics of the Session but allows flexibility in accessing data from the server.

As an example, the session url might be "http://motherlode.ucar.edu" and the method url might be a more specific URL such as http://motherlode.ucar.edu/path/file.nc.dds.

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 List<org.apache.http.Header>	headers
protected String	legalurl
protected boolean	localsession
protected ucar.httpservices.HTTPSession.Methods	methodclass
protected HTTPMethodStream	methodstream
protected org.apache.http.client.methods.HttpRequestBase	request
protected org.apache.http.HttpResponse	response
protected HTTPSession	session

Constructor Summary

Constructors

Constructor and Description
HTTPMethod(ucar.httpservices.HTTPSession.Methods m)
HTTPMethod(ucar.httpservices.HTTPSession.Methods m, HTTPSession session, String url)
HTTPMethod(ucar.httpservices.HTTPSession.Methods m, String url)

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canHoldContent()
void	close() Calling close will force the method to close, and will force any open stream to terminate.
protected static boolean	compatibleURL(String u1, String u2) Define URI compatibility.
protected void	configure(org.apache.http.client.methods.HttpRequestBase request)
protected org.apache.http.client.methods.HttpRequestBase	createRequest()
org.apache.http.HttpMessage	debugRequest()
org.apache.http.HttpResponse	debugResponse()
int	execute()
static Set<String>	getAllowedMethods()
String	getCharSet()
String	getName()
String	getPath()
String	getProtocolVersion()
org.apache.http.Header	getRequestHeader(String name)
org.apache.http.Header[]	getRequestHeaders()
String	getRequestLine()
byte[]	getResponseAsBytes()
byte[]	getResponseAsBytes(int maxbytes)
InputStream	getResponseAsStream()
String	getResponseAsString()
String	getResponseAsString(String charset)
InputStream	getResponseBodyAsStream()
String	getResponseCharSet()
org.apache.http.Header	getResponseHeader(String name)
org.apache.http.Header[]	getResponseHeaders()
HTTPSession	getSession()
String	getSoTimeout()
int	getStatusCode()
String	getStatusLine()
String	getStatusText()
String	getURL()
boolean	hasStreamOpen()
boolean	isClosed()
boolean	isSessionLocal()
protected boolean	sessionCompatible(String other) Test that the given url is "compatible" with the session specified dataset.
protected org.apache.http.auth.AuthScope	setAuthentication() Handle authentication.
protected void	setcontent(org.apache.http.client.methods.HttpRequestBase request)
void	setFollowRedirects(boolean tf)
void	setMethodHeaders(List<org.apache.http.Header> headers)
void	setRequestContent(org.apache.http.HttpEntity content)
void	setRequestHeader(org.apache.http.Header h)
void	setRequestHeader(String name, String value)

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

legalurl

protected String legalurl

headers

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

content

protected org.apache.http.HttpEntity content

methodclass

protected ucar.httpservices.HTTPSession.Methods methodclass

methodstream

protected HTTPMethodStream methodstream

closed

protected boolean closed

request

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

response

protected org.apache.http.HttpResponse response

Constructor Detail

HTTPMethod

public HTTPMethod(ucar.httpservices.HTTPSession.Methods m)
           throws HTTPException

Throws:

HTTPException

HTTPMethod

public HTTPMethod(ucar.httpservices.HTTPSession.Methods m,
          String url)
           throws HTTPException

Throws:

HTTPException

HTTPMethod

public HTTPMethod(ucar.httpservices.HTTPSession.Methods m,
          HTTPSession session,
          String url)
           throws HTTPException

Throws:

HTTPException

Method Detail

createRequest

protected org.apache.http.client.methods.HttpRequestBase createRequest()
                                                                throws HTTPException

Throws:

HTTPException

setcontent

protected void setcontent(org.apache.http.client.methods.HttpRequestBase request)

execute

public int execute()
            throws HTTPException

Throws:

HTTPException

configure

protected void configure(org.apache.http.client.methods.HttpRequestBase request)
                  throws HTTPException

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 AutoCloseable

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

setMethodHeaders

public void setMethodHeaders(List<org.apache.http.Header> headers)
                      throws HTTPException

Throws:

HTTPException

setRequestHeader

public void setRequestHeader(String name,
                    String value)
                      throws HTTPException

Throws:

HTTPException

setRequestHeader

public void setRequestHeader(org.apache.http.Header h)
                      throws HTTPException

Throws:

HTTPException

getRequestHeader

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

getRequestHeaders

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

getResponseHeader

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

getResponseHeaders

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

setRequestContent

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

getCharSet

public String getCharSet()

getName

public String getName()

getURL

public String getURL()

getProtocolVersion

public String getProtocolVersion()

getSoTimeout

public String getSoTimeout()

getStatusText

public String getStatusText()

getAllowedMethods

public static Set<String> getAllowedMethods()

setFollowRedirects

public void setFollowRedirects(boolean tf)

getResponseCharSet

public String getResponseCharSet()

getSession

public HTTPSession getSession()

isSessionLocal

public boolean isSessionLocal()

hasStreamOpen

public boolean hasStreamOpen()

isClosed

public boolean isClosed()

sessionCompatible

protected boolean sessionCompatible(String other)

Test that the given url is "compatible" with the session specified dataset. Compatible means: 1. remove any query 2. HTTPAuthStore.compatibleURL must return true;

* @param url to test for compatibility

Returns:

setAuthentication

protected org.apache.http.auth.AuthScope setAuthentication()
                                                    throws HTTPException

Handle authentication. We do not know, necessarily, which scheme(s) will be encountered, so most testing occurs in HTTPAuthProvider

Returns:

an authprovider encapsulting the request

Throws:

HTTPException

compatibleURL

protected static boolean compatibleURL(String u1,
                    String u2)

Define URI compatibility.

debugRequest

public org.apache.http.HttpMessage debugRequest()

debugResponse

public org.apache.http.HttpResponse debugResponse()