HTTPMethod (httpservices 4.6.1 API)

java.lang.Object
- ucar.httpservices.HTTPMethod

All Implemented Interfaces:

java.lang.AutoCloseable
```
public class HTTPMethod
extends java.lang.Object
implements java.lang.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 java.util.List<org.apache.http.Header>`	`headers`
`protected java.lang.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, java.lang.String url)`
`HTTPMethod(ucar.httpservices.HTTPSession.Methods m, java.lang.String url)`

Method Summary

All Methods Static Methods Instance Methods Concrete 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(java.lang.String u1, java.lang.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 java.util.Set<java.lang.String>`	`getAllowedMethods()`
`java.lang.String`	`getCharSet()`
`java.lang.String`	`getName()`
`java.lang.String`	`getPath()`
`java.lang.String`	`getProtocolVersion()`
`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()`
`java.lang.String`	`getSoTimeout()`
`int`	`getStatusCode()`
`java.lang.String`	`getStatusLine()`
`java.lang.String`	`getStatusText()`
`java.lang.String`	`getURL()`
`boolean`	`hasStreamOpen()`
`boolean`	`isClosed()`
`boolean`	`isSessionLocal()`
`protected boolean`	`sessionCompatible(java.lang.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(java.util.List<org.apache.http.Header> headers)`
`void`	`setRequestContent(org.apache.http.HttpEntity content)`
`void`	`setRequestHeader(org.apache.http.Header h)`
`void`	`setRequestHeader(java.lang.String name, java.lang.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 java.lang.String legalurl
```

headers

protected java.util.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,
                  java.lang.String url)
           throws HTTPException

Throws:: HTTPException

HTTPMethod

public HTTPMethod(ucar.httpservices.HTTPSession.Methods m,
                  HTTPSession session,
                  java.lang.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 java.lang.AutoCloseable

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

setMethodHeaders

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

Throws:: HTTPException

setRequestHeader

public void setRequestHeader(java.lang.String name,
                             java.lang.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(java.lang.String name)

getRequestHeaders

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

getResponseHeader

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

getResponseHeaders

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

setRequestContent

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

getCharSet
```
public java.lang.String getCharSet()
```

getName
```
public java.lang.String getName()
```

getURL
```
public java.lang.String getURL()
```

getProtocolVersion

public java.lang.String getProtocolVersion()

getSoTimeout

public java.lang.String getSoTimeout()

getStatusText

public java.lang.String getStatusText()

getAllowedMethods

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

setFollowRedirects

public void setFollowRedirects(boolean tf)

getResponseCharSet

public java.lang.String getResponseCharSet()

getSession
```
public HTTPSession getSession()
```

isSessionLocal
```
public boolean isSessionLocal()
```

hasStreamOpen
```
public boolean hasStreamOpen()
```

isClosed
```
public boolean isClosed()
```

sessionCompatible
```
protected boolean sessionCompatible(java.lang.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(java.lang.String u1,
                                       java.lang.String u2)

Define URI compatibility.

debugRequest

public org.apache.http.HttpMessage debugRequest()

debugResponse

public org.apache.http.HttpResponse debugResponse()

Class HTTPMethod

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

session

localsession

legalurl

headers

content

methodclass

methodstream

closed

request

response

Constructor Detail

HTTPMethod

HTTPMethod

HTTPMethod

Method Detail

createRequest

setcontent

execute

configure

close

getStatusCode

getStatusLine

getRequestLine

getPath

canHoldContent

getResponseBodyAsStream

getResponseAsStream

getResponseAsBytes

getResponseAsBytes

getResponseAsString

getResponseAsString

setMethodHeaders

setRequestHeader

setRequestHeader

getRequestHeader

getRequestHeaders

getResponseHeader

getResponseHeaders

setRequestContent

getCharSet

getName

getURL

getProtocolVersion

getSoTimeout

getStatusText

getAllowedMethods

setFollowRedirects

getResponseCharSet

getSession

isSessionLocal

hasStreamOpen

isClosed

sessionCompatible

setAuthentication

compatibleURL

debugRequest

debugResponse