BoxAPIRequest (Box Java SDK)

Object
- BoxAPIRequest

Direct Known Subclasses:

BoxJSONRequest, BoxMultipartRequest
```
public class BoxAPIRequest
extends Object
```
Used to make HTTP requests to the Box API.
All requests to the REST API are sent using this class or one of its subclasses. This class wraps HttpURLConnection in order to provide a simpler interface that can automatically handle various conditions specific to Box's API. Requests will be authenticated using a BoxAPIConnection (if one is provided), so it isn't necessary to add authorization headers. Requests can also be sent more than once, unlike with HttpURLConnection. If an error occurs while sending a request, it will be automatically retried (with a back off delay) up to the maximum number of times set in the BoxAPIConnection.

Specifying a body for a BoxAPIRequest is done differently than it is with HttpURLConnection. Instead of writing to an OutputStream, the request is provided an InputStream which will be read when the send() method is called. This makes it easy to retry requests since the stream can automatically reset and reread with each attempt. If the stream cannot be reset, then a new stream will need to be provided before each call to send. There is also a convenience method for specifying the body as a String, which simply wraps the String with an InputStream.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class BoxAPIRequest.RequestHeader
Class for mapping a request header and value.

Nested Classes
Modifier and Type	Class and Description
`static class`	`BoxAPIRequest.RequestHeader` Class for mapping a request header and value.

Constructor Summary

Constructors
Modifier	Constructor and Description
	`BoxAPIRequest(BoxAPIConnection api, URL url, HttpMethod method)` Constructs an authenticated BoxAPIRequest using a provided BoxAPIConnection.
	`BoxAPIRequest(BoxAPIConnection api, URL url, String method)` Constructs an authenticated BoxAPIRequest using a provided BoxAPIConnection.
`protected`	`BoxAPIRequest(BoxAPIConnection api, URL url, String method, String mediaType)`
	`BoxAPIRequest(URL url, HttpMethod method)` Constructs an request, using URL and HttpMethod.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addHeader(String key, String value)` Adds an HTTP header to this request.
`protected String`	`bodyToString()` Returns a String representation of this request's body used in `toString()`.
`InputStream`	`getBody()` Gets the stream containing contents of this request's body.
`int`	`getConnectTimeout()` Gets the connect timeout for the request.
`String`	`getMethod()` Gets the http method from the request.
`int`	`getReadTimeout()` Gets the read timeout for the request.
`URL`	`getUrl()` Gets the URL from the request.
`static boolean`	`isRequestRetryable(BoxAPIException apiException)`
`static boolean`	`isResponseRetryable(int responseCode, BoxAPIException apiException)`
`protected MediaType`	`mediaType()`
`protected void`	`resetBody()` Resets the InputStream containing this request's body.
`BoxAPIResponse`	`send()` Sends this request and returns a BoxAPIResponse containing the server's response.
`BoxAPIResponse`	`send(ProgressListener listener)` Sends this request while monitoring its progress and returns a BoxAPIResponse containing the server's response.
`BoxAPIResponse`	`sendWithoutRetry()` Sends this request and returns a BoxAPIResponse containing the server's response.
`void`	`setBody(InputStream stream)` Sets the request body to the contents of an InputStream.
`void`	`setBody(InputStream stream, long length)` Sets the request body to the contents of an InputStream.
`void`	`setBody(String body)` Sets the request body to the contents of a String.
`void`	`setConnectTimeout(int timeout)` Sets a Connect timeout for this request in milliseconds.
`void`	`setFollowRedirects(boolean followRedirects)` Sets whether or not to follow redirects (i.e.
`void`	`setReadTimeout(int timeout)` Sets a read timeout for this request in milliseconds.
`void`	`setUrl(URL url)` Sets the URL to the request.
`void`	`shouldAuthenticate(boolean shouldAuthenticate)` Disables adding authentication header to request.
`String`	`toString()` Returns a String containing the URL, HTTP method, headers and body of this request.
`protected void`	`writeMethodWithBody(Request.Builder requestBuilder, ProgressListener listener)`

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - BoxAPIRequest
```
public BoxAPIRequest(BoxAPIConnection api,
                     URL url,
                     String method)
```
    Constructs an authenticated BoxAPIRequest using a provided BoxAPIConnection.
    
    Parameters:
    
    api - an API connection for authenticating the request.
    
    url - the URL of the request.
    
    method - the HTTP method of the request.
  - BoxAPIRequest
```
protected BoxAPIRequest(BoxAPIConnection api,
                        URL url,
                        String method,
                        String mediaType)
```
  - BoxAPIRequest
```
public BoxAPIRequest(BoxAPIConnection api,
                     URL url,
                     HttpMethod method)
```
    Constructs an authenticated BoxAPIRequest using a provided BoxAPIConnection.
    
    Parameters:
    
    api - an API connection for authenticating the request.
    
    url - the URL of the request.
    
    method - the HTTP method of the request.
  - BoxAPIRequest
```
public BoxAPIRequest(URL url,
                     HttpMethod method)
```
    Constructs an request, using URL and HttpMethod.
    
    Parameters:
    
    url - the URL of the request.
    
    method - the HTTP method of the request.
- Method Detail
  - isRequestRetryable
```
public static boolean isRequestRetryable(BoxAPIException apiException)
```
    Parameters:
    
    apiException - BoxAPIException thrown
    
    Returns:
    
    true if the request is one that should be retried, otherwise false
  - isResponseRetryable
```
public static boolean isResponseRetryable(int responseCode,
                                          BoxAPIException apiException)
```
    Parameters:
    
    responseCode - HTTP error code of the response
    
    apiException - BoxAPIException thrown
    
    Returns:
    
    true if the response is one that should be retried, otherwise false
  - addHeader
```
public void addHeader(String key,
                      String value)
```
    Adds an HTTP header to this request.
    
    Parameters:
    
    key - the header key.
    
    value - the header value.
  - getConnectTimeout
```
public int getConnectTimeout()
```
    Gets the connect timeout for the request.
    
    Returns:
    
    the request connection timeout.
  - setConnectTimeout
```
public void setConnectTimeout(int timeout)
```
    Sets a Connect timeout for this request in milliseconds.
    
    Parameters:
    
    timeout - the timeout in milliseconds.
  - getReadTimeout
```
public int getReadTimeout()
```
    Gets the read timeout for the request.
    
    Returns:
    
    the request's read timeout.
  - setReadTimeout
```
public void setReadTimeout(int timeout)
```
    Sets a read timeout for this request in milliseconds.
    
    Parameters:
    
    timeout - the timeout in milliseconds.
  - setFollowRedirects
```
public void setFollowRedirects(boolean followRedirects)
```
    Sets whether or not to follow redirects (i.e. Location header)
    
    Parameters:
    
    followRedirects - true to follow, false to not follow
  - getBody
```
public InputStream getBody()
```
    Gets the stream containing contents of this request's body.
    Note that any bytes that read from the returned stream won't be sent unless the stream is reset back to its initial position.
    
    Returns:
    
    an InputStream containing the contents of this request's body.
  - setBody
```
public void setBody(InputStream stream)
```
    Sets the request body to the contents of an InputStream.
    The stream must support the InputStream.reset() method if auto-retry is used or if the request needs to be resent. Otherwise, the body must be manually set before each call to send().
    
    Parameters:
    
    stream - an InputStream containing the contents of the body.
  - setBody
```
public void setBody(String body)
```
    Sets the request body to the contents of a String.
    If the contents of the body are large, then it may be more efficient to use an InputStream instead of a String. Using a String requires that the entire body be in memory before sending the request.
    
    Parameters:
    
    body - a String containing the contents of the body.
  - setBody
```
public void setBody(InputStream stream,
                    long length)
```
    Sets the request body to the contents of an InputStream.
    Providing the length of the InputStream allows for the progress of the request to be monitored when calling send(ProgressListener).
    
    See setBody(InputStream) for more information on setting the body of the request.
    
    Parameters:
    
    stream - an InputStream containing the contents of the body.
    
    length - the expected length of the stream.
  - getUrl
```
public URL getUrl()
```
    Gets the URL from the request.
    
    Returns:
    
    a URL containing the URL of the request.
  - setUrl
```
public void setUrl(URL url)
```
    Sets the URL to the request.
  - getMethod
```
public String getMethod()
```
    Gets the http method from the request.
    
    Returns:
    
    http method
  - sendWithoutRetry
```
public BoxAPIResponse sendWithoutRetry()
```
    Sends this request and returns a BoxAPIResponse containing the server's response.
    The type of the returned BoxAPIResponse will be based on the content type returned by the server, allowing it to be cast to a more specific type. For example, if it's known that the API call will return a JSON response, then it can be cast to a BoxJSONResponse like so:
```
BoxJSONResponse response = (BoxJSONResponse) request.sendWithoutRetry();
```
    Returns:
    
    a BoxAPIResponse containing the server's response.
    
    Throws:
    
    BoxAPIException - if the server returns an error code or if a network error occurs.
  - send
```
public BoxAPIResponse send()
```
    Sends this request and returns a BoxAPIResponse containing the server's response.
    The type of the returned BoxAPIResponse will be based on the content type returned by the server, allowing it to be cast to a more specific type. For example, if it's known that the API call will return a JSON response, then it can be cast to a BoxJSONResponse like so:
```
BoxJSONResponse response = (BoxJSONResponse) request.send();
```
    If the server returns an error code or if a network error occurs, then the request will be automatically retried. If the maximum number of retries is reached and an error still occurs, then a BoxAPIException will be thrown.
    
    See send() for more information on sending requests.
    Returns:
    
    a BoxAPIResponse containing the server's response.
    
    Throws:
    
    BoxAPIException - if the server returns an error code or if a network error occurs.
  - send
```
public BoxAPIResponse send(ProgressListener listener)
```
    Sends this request while monitoring its progress and returns a BoxAPIResponse containing the server's response.
    The type of the returned BoxAPIResponse will be based on the content type returned by the server, allowing it to be cast to a more specific type. For example, if it's known that the API call will return a JSON response, then it can be cast to a BoxJSONResponse like so:
    
    If the server returns an error code or if a network error occurs, then the request will be automatically retried. If the maximum number of retries is reached and an error still occurs, then a BoxAPIException will be thrown.
    
    A ProgressListener is generally only useful when the size of the request is known beforehand. If the size is unknown, then the ProgressListener will be updated for each byte sent, but the total number of bytes will be reported as 0.
    
    See send() for more information on sending requests.
    
    Parameters:
    
    listener - a listener for monitoring the progress of the request.
    
    Returns:
    
    a BoxAPIResponse containing the server's response.
    
    Throws:
    
    BoxAPIException - if the server returns an error code or if a network error occurs.
  - shouldAuthenticate
```
public void shouldAuthenticate(boolean shouldAuthenticate)
```
    Disables adding authentication header to request. Useful when you want to add your own authentication method. Default value is `true` and SKD will add authenticaton header to request.
    
    Parameters:
    
    shouldAuthenticate - use `false` to disable authentication.
  - toString
```
public String toString()
```
    Returns a String containing the URL, HTTP method, headers and body of this request.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a String containing information about this request.
  - bodyToString
```
protected String bodyToString()
```
    Returns a String representation of this request's body used in toString(). This method returns null by default.
    A subclass may want override this method if the body can be converted to a String for logging or debugging purposes.
    
    Returns:
    
    a String representation of this request's body.
  - resetBody
```
protected void resetBody()
                  throws IOException
```
    Resets the InputStream containing this request's body.
    This method will be called before each attempt to resend the request, giving subclasses an opportunity to reset any streams that need to be read when sending the body.
    
    Throws:
    
    IOException - if the stream cannot be reset.
  - writeMethodWithBody
```
protected void writeMethodWithBody(Request.Builder requestBuilder,
                                   ProgressListener listener)
```
  - mediaType
```
protected MediaType mediaType()
```

Class BoxAPIRequest

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

BoxAPIRequest

BoxAPIRequest

BoxAPIRequest

BoxAPIRequest

Method Detail

isRequestRetryable

isResponseRetryable

addHeader

getConnectTimeout

setConnectTimeout

getReadTimeout

setReadTimeout

setFollowRedirects

getBody

setBody

setBody

setBody

getUrl

setUrl

getMethod

sendWithoutRetry

send

send

shouldAuthenticate

toString

bodyToString

resetBody

writeMethodWithBody

mediaType