com.dropbox.client2

Class RESTUtility

java.lang.Object

com.dropbox.client2.RESTUtility

public class RESTUtility
extends java.lang.Object

This class is mostly used internally by DropboxAPI for creating and executing REST requests to the Dropbox API, and parsing responses. You probably won't have a use for it other than parseDate(String) for parsing modified times returned in metadata, or (in very rare circumstances) writing your own API calls.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RESTUtility.RequestMethod

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.String	buildURL(java.lang.String host, int apiVersion, java.lang.String target, java.lang.String[] params) Creates a URL for a request to the Dropbox API.
static org.apache.http.HttpResponse	execute(Session session, org.apache.http.client.methods.HttpUriRequest req) Executes an HttpUriRequest with the given Session and returns an HttpResponse.
static org.apache.http.HttpResponse	execute(Session session, org.apache.http.client.methods.HttpUriRequest req, int socketTimeoutOverrideMs) Executes an HttpUriRequest with the given Session and returns an HttpResponse.
static java.lang.Object	parseAsJSON(org.apache.http.HttpResponse response) Reads in content from an HttpResponse and parses it as JSON.
static java.util.Map<java.lang.String,java.lang.String>	parseAsQueryString(org.apache.http.HttpResponse response) Reads in content from an HttpResponse and parses it as a query string.
static java.util.Date	parseDate(java.lang.String date) Parses a date/time returned by the Dropbox API.
static java.lang.Object	request(RESTUtility.RequestMethod method, java.lang.String host, java.lang.String path, int apiVersion, java.lang.String[] params, Session session) Creates and sends a request to the Dropbox API, parses the response as JSON, and returns the result.
static DropboxAPI.RequestAndResponse	streamRequest(RESTUtility.RequestMethod method, java.lang.String host, java.lang.String path, int apiVersion, java.lang.String[] params, Session session) Creates and sends a request to the Dropbox API, and returns a DropboxAPI.RequestAndResponse containing the HttpUriRequest and HttpResponse.

Methods inherited from class java.lang.Object

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

Method Detail

request

public static java.lang.Object request(RESTUtility.RequestMethod method,
                       java.lang.String host,
                       java.lang.String path,
                       int apiVersion,
                       java.lang.String[] params,
                       Session session)
                                throws DropboxException

Creates and sends a request to the Dropbox API, parses the response as JSON, and returns the result.

Parameters:

method - GET or POST.

host - the hostname to use. Should be either api server, content server, or web server.

path - the URL path, starting with a '/'.

apiVersion - the API version to use. This should almost always be set to DropboxAPI.VERSION.

params - the URL params in an array, with the even numbered elements the parameter names and odd numbered elements the values, e.g. new String[] {"path", "/Public", "locale", "en"}.

session - the Session to use for this request.

Returns:

a parsed JSON object, typically a Map or a JSONArray.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxUnlinkedException - if the user has revoked access.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

streamRequest

public static DropboxAPI.RequestAndResponse streamRequest(RESTUtility.RequestMethod method,
                                          java.lang.String host,
                                          java.lang.String path,
                                          int apiVersion,
                                          java.lang.String[] params,
                                          Session session)
                                                   throws DropboxException

Creates and sends a request to the Dropbox API, and returns a DropboxAPI.RequestAndResponse containing the HttpUriRequest and HttpResponse.

Parameters:

method - GET or POST.

host - the hostname to use. Should be either api server, content server, or web server.

path - the URL path, starting with a '/'.

apiVersion - the API version to use. This should almost always be set to DropboxAPI.VERSION.

params - the URL params in an array, with the even numbered elements the parameter names and odd numbered elements the values, e.g. new String[] {"path", "/Public", "locale", "en"}.

session - the Session to use for this request.

Returns:

a parsed JSON object, typically a Map or a JSONArray.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxUnlinkedException - if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

parseAsJSON

public static java.lang.Object parseAsJSON(org.apache.http.HttpResponse response)
                                    throws DropboxException

Reads in content from an HttpResponse and parses it as JSON.

Parameters:

response - the HttpResponse.

Returns:

a parsed JSON object, typically a Map or a JSONArray.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs while reading in content from the HttpResponse.

DropboxUnlinkedException - if the user has revoked access.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

parseAsQueryString

public static java.util.Map<java.lang.String,java.lang.String> parseAsQueryString(org.apache.http.HttpResponse response)
                                                                           throws DropboxException

Reads in content from an HttpResponse and parses it as a query string.

Parameters:

response - the HttpResponse.

Returns:

a map of parameter names to values from the query string.

Throws:

DropboxIOException - if any network-related error occurs while reading in content from the HttpResponse.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

execute

public static org.apache.http.HttpResponse execute(Session session,
                                   org.apache.http.client.methods.HttpUriRequest req)
                                            throws DropboxException

Executes an HttpUriRequest with the given Session and returns an HttpResponse.

Parameters:

session - the session to use.

req - the request to execute.

Returns:

an HttpResponse.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxUnlinkedException - if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

execute

public static org.apache.http.HttpResponse execute(Session session,
                                   org.apache.http.client.methods.HttpUriRequest req,
                                   int socketTimeoutOverrideMs)
                                            throws DropboxException

Executes an HttpUriRequest with the given Session and returns an HttpResponse.

Parameters:

session - the session to use.

req - the request to execute.

socketTimeoutOverrideMs - if >= 0, the socket timeout to set on this request. Does nothing if set to a negative number.

Returns:

an HttpResponse.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code.

DropboxIOException - if any network-related error occurs.

DropboxUnlinkedException - if the user has revoked access.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

buildURL

public static java.lang.String buildURL(java.lang.String host,
                        int apiVersion,
                        java.lang.String target,
                        java.lang.String[] params)

Creates a URL for a request to the Dropbox API.

Parameters:

host - the Dropbox host (i.e., api server, content server, or web server).

apiVersion - the API version to use. You should almost always use DropboxAPI.VERSION for this.

target - the target path, staring with a '/'.

params - any URL params in an array, with the even numbered elements the parameter names and odd numbered elements the values, e.g. new String[] {"path", "/Public", "locale", "en"}.

Returns:

a full URL for making a request.

parseDate

public static java.util.Date parseDate(java.lang.String date)

Parses a date/time returned by the Dropbox API. Returns null if it cannot be parsed.

Parameters:

date - a date returned by the API.

Returns:

a Date.