ucar.nc2.util.net

Class HTTPMethod

java.lang.Object

ucar.nc2.util.net.HTTPMethod

@NotThreadSafe
public class HTTPMethod
extends Object

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.

Constructor Summary

Constructors

Constructor and Description
HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m)
HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m, HTTPSession session, String url)
HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m, String url)

Method Summary

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.
int	execute()
int	execute(String url)
static Set<String>	getAllowedMethods()
String	getCharSet()
org.apache.http.protocol.HttpContext	getContext()
org.apache.http.HttpRequest	getMethod()
Object	getMethodParameter(String key)
org.apache.http.params.HttpParams	getMethodParameters()
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()
Object	getResponseParameter(String name)
HTTPSession	getSession()
String	getSoTimeout()
int	getStatusCode()
String	getStatusLine()
String	getStatusText()
String	getURL()
boolean	hasStreamOpen()
boolean	isClosed()
boolean	isSessionLocal()
void	setContext(org.apache.http.protocol.HttpContext cxt)
void	setFollowRedirects(boolean tf)
static void	setGlobalParameter(String name, Object value)
void	setMethodHeaders(List<org.apache.http.Header> headers)
void	setRequestContentAsString(String content)
void	setRequestHeader(org.apache.http.Header h)
void	setRequestHeader(String name, String value)
void	setRequestParameter(String name, Object value)

Methods inherited from class java.lang.Object

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

Constructor Detail

HTTPMethod

public HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m)
           throws HTTPException

Throws:

HTTPException

HTTPMethod

public HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m,
                  String url)
           throws HTTPException

Throws:

HTTPException

HTTPMethod

public HTTPMethod(ucar.nc2.util.net.HTTPSession.Methods m,
                  HTTPSession session,
                  String url)
           throws HTTPException

Throws:

HTTPException

Method Detail

setGlobalParameter

public static void setGlobalParameter(String name,
                                      Object value)

execute

public int execute(String url)
            throws HTTPException

Throws:

HTTPException

execute

public int execute()
            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.

setContext

public void setContext(org.apache.http.protocol.HttpContext cxt)

getContext

public org.apache.http.protocol.HttpContext getContext()

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

setRequestParameter

public void setRequestParameter(String name,
                                Object value)

getMethodParameter

public Object getMethodParameter(String key)

getMethodParameters

public org.apache.http.params.HttpParams getMethodParameters()

getResponseParameter

public Object getResponseParameter(String name)

setRequestContentAsString

public void setRequestContentAsString(String content)
                               throws HTTPException

Throws:

HTTPException

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

getMethod

public org.apache.http.HttpRequest getMethod()

hasStreamOpen

public boolean hasStreamOpen()

isClosed

public boolean isClosed()