com.socrata.api

Class HttpLowLevel

java.lang.Object

com.socrata.api.HttpLowLevel

public final class HttpLowLevel
extends Object

Class to handle all the low level HTTP operations. This class provides the core data access methods for GET, PUT, POST, DELETE and wraps the appropriate authentications set-up for the connection. This library is based off the Jersey JAX-RS implementation. Most of this is hidden from the caller, but the Client object is available in case custom filters are required.

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTH_REQUIRED_CODE
static javax.ws.rs.core.MediaType	CSV_TYPE
protected static int	DEFAULT_MAX_RETRIES
static long	DEFAULT_RETRY_TIME
static javax.ws.rs.core.MediaType	JSON_TYPE
static com.sun.jersey.api.client.GenericType<List<Object>>	MAP_OBJECT_TYPE
static String	SOCRATA_TOKEN_HEADER
static String	SODA_VERSION
static String	UNEXPECTED_ERROR
static Map<String,String>	UTF_PARAMS
static javax.ws.rs.core.MediaType	UTF8_TEXT_TYPE

Constructor Summary

Constructors

Constructor and Description
HttpLowLevel(com.sun.jersey.api.client.Client client, String url) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
com.sun.jersey.api.client.ClientResponse	deleteRaw(URI uri) Raw version of the API for issuing a delete, doing common error processing and returning the ClientResponse.
com.sun.jersey.api.client.ClientResponse	follow202(URI uri, javax.ws.rs.core.MediaType mediaType, long retryTime, SodaRequest request2Rerun) Follows a 202 response that comes back for long running queries.
<T> T	getAsyncResults(URI uri, long waitTime, long numRetries, Class<T> cls, SodaRequest request2Rerun) Method to check the async callbacks for new responses.
<T> T	getAsyncResults(URI uri, javax.ws.rs.core.MediaType mediaType, long waitTime, long numRetries, com.sun.jersey.api.client.GenericType<T> cls, SodaRequest request2Rerun) Method to check the async callbacks for new responses.
com.sun.jersey.api.client.ClientResponse	getAsyncResults(URI uri, javax.ws.rs.core.MediaType mediaType, long waitTime, long numRetries, SodaRequest request2Rerun) Method to check the async callbacks for new responses.
com.sun.jersey.api.client.Client	getClient() Returns the Jersey Client object this connection will use.
long	getMaxRetries() Gets the max number of times to follow a 202 before failing
long	getRetryTime() Gets the number of milliseconds to wait before following a 202
static HttpLowLevel	instantiate(String url) Create an anonymous connection to a SODA2 domain rooted at url
static HttpLowLevel	instantiateBasic(String url, String userName, String password, String token) Create an HttpLowLevel object that is set-up with the appropriate authentication credentials.
com.sun.jersey.api.client.ClientResponse	postFileRaw(URI uri, javax.ws.rs.core.MediaType mediaType, File file)
com.sun.jersey.api.client.ClientResponse	postFileRaw(URI uri, javax.ws.rs.core.MediaType mediaType, javax.ws.rs.core.MediaType acceptType, File file)
com.sun.jersey.api.client.ClientResponse	postRaw(URI uri, javax.ws.rs.core.MediaType mediaType, Object object) Issues a raw POST to a URI.
com.sun.jersey.api.client.ClientResponse	putFileRaw(URI uri, javax.ws.rs.core.MediaType mediaType, File file)
com.sun.jersey.api.client.ClientResponse	putFileRaw(URI uri, javax.ws.rs.core.MediaType mediaType, javax.ws.rs.core.MediaType acceptType, File file)
<T> com.sun.jersey.api.client.ClientResponse	putRaw(URI uri, javax.ws.rs.core.MediaType mediaType, Object object) Issues a raw PUT to a URI.
com.sun.jersey.api.client.ClientResponse	queryRaw(URI uri, javax.ws.rs.core.MediaType acceptType) Issues a raw GET to a URI.
void	setMaxRetries(long maxRetries) Sets the max number of times to follow a 202 before failing
void	setRetryTime(long retryTime) Sets the number of milliseconds to wait before following a 202
javax.ws.rs.core.UriBuilder	uriBuilder()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_RETRIES

protected static final int DEFAULT_MAX_RETRIES

See Also:

Constant Field Values

DEFAULT_RETRY_TIME

public static final long DEFAULT_RETRY_TIME

See Also:

Constant Field Values

SODA_VERSION

public static final String SODA_VERSION

See Also:

Constant Field Values

SOCRATA_TOKEN_HEADER

public static final String SOCRATA_TOKEN_HEADER

See Also:

Constant Field Values

AUTH_REQUIRED_CODE

public static final String AUTH_REQUIRED_CODE

See Also:

Constant Field Values

UNEXPECTED_ERROR

public static final String UNEXPECTED_ERROR

See Also:

Constant Field Values

UTF_PARAMS

public static final Map<String,String> UTF_PARAMS

JSON_TYPE

public static final javax.ws.rs.core.MediaType JSON_TYPE

CSV_TYPE

public static final javax.ws.rs.core.MediaType CSV_TYPE

UTF8_TEXT_TYPE

public static final javax.ws.rs.core.MediaType UTF8_TEXT_TYPE

MAP_OBJECT_TYPE

public static final com.sun.jersey.api.client.GenericType<List<Object>> MAP_OBJECT_TYPE

Constructor Detail

HttpLowLevel

public HttpLowLevel(com.sun.jersey.api.client.Client client,
            String url)

Constructor

Parameters:

client - the Jersey Client class that will be used for actually issuing requests

url - the base URL for the SODA2 domain to access.

Method Detail

instantiate

public static final HttpLowLevel instantiate(@Nonnull
                       String url)

Create an anonymous connection to a SODA2 domain rooted at url

Parameters:

url - the base URL for the SODA2 domain to access.

Returns:

HttpLowLevel object that is completely configured to use.

instantiateBasic

public static final HttpLowLevel instantiateBasic(@Nonnull
                            String url,
                            @Nonnull
                            String userName,
                            @Nonnull
                            String password,
                            @Nullable
                            String token)

Create an HttpLowLevel object that is set-up with the appropriate authentication credentials.

Parameters:

url - the base URL for the SODA2 domain to access.

userName - user name to log in as

password - password to log in with

token - the App Token to use for authorization and usage tracking. If this is null, no value will be sent.

Returns:

HttpLowLevel object that is completely configured to use.

getClient

public com.sun.jersey.api.client.Client getClient()

Returns the Jersey Client object this connection will use.

Returns:

Jersey Client object this connection will use.

getRetryTime

public long getRetryTime()

Gets the number of milliseconds to wait before following a 202

Returns:

number of milliseconds to wait before following a 202

setRetryTime

public void setRetryTime(long retryTime)

Sets the number of milliseconds to wait before following a 202

Parameters:

retryTime - number of milliseconds to wait before following a 202

getMaxRetries

public long getMaxRetries()

Gets the max number of times to follow a 202 before failing

Returns:

max number of times to follow a 202 before failing

setMaxRetries

public void setMaxRetries(long maxRetries)

Sets the max number of times to follow a 202 before failing

Parameters:

maxRetries - max number of times to follow a 202 before failing

uriBuilder

public javax.ws.rs.core.UriBuilder uriBuilder()

follow202

public com.sun.jersey.api.client.ClientResponse follow202(URI uri,
                                                 javax.ws.rs.core.MediaType mediaType,
                                                 long retryTime,
                                                 SodaRequest request2Rerun)
                                                   throws InterruptedException,
                                                          LongRunningQueryException,
                                                          SodaError

Follows a 202 response that comes back for long running queries.

Parameters:

uri - the URI to go back to

retryTime - the amount of time to wait for a retry

Returns:

the ClientResponse from this operation

Throws:

InterruptedException - if this thread is interrupted

LongRunningQueryException - thrown if this query is long running and a 202 is returned. In this case, the caller likely wants to call follow202.

SodaError - thrown if there is an error. Investigate the structure for more information.

getAsyncResults

public final <T> T getAsyncResults(URI uri,
                    long waitTime,
                    long numRetries,
                    Class<T> cls,
                    SodaRequest request2Rerun)
                        throws SodaError,
                               InterruptedException

Method to check the async callbacks for new responses.

Parameters:

uri - the URI to go to for responses.

waitTime - the time to wait until the first response

numRetries - the total number of times to retry before failing.

cls - the class of the object to return.

Returns:

the object returned for a successful response.

Throws:

SodaError - thrown if there is an error. Investigate the structure for more information.

InterruptedException - throws is the thread is interrupted.

getAsyncResults

public final <T> T getAsyncResults(URI uri,
                    javax.ws.rs.core.MediaType mediaType,
                    long waitTime,
                    long numRetries,
                    com.sun.jersey.api.client.GenericType<T> cls,
                    SodaRequest request2Rerun)
                        throws SodaError,
                               InterruptedException

Method to check the async callbacks for new responses.

Parameters:

uri - the URI to go to for responses.

waitTime - the time to wait until the first response

numRetries - the total number of times to retry before failing.

cls - the GenericType describing the class of the object to return.

Returns:

the object returned for a successful response.

Throws:

SodaError - thrown if there is an error. Investigate the structure for more information.

InterruptedException - throws is the thread is interrupted.

getAsyncResults

public final com.sun.jersey.api.client.ClientResponse getAsyncResults(URI uri,
                                                       javax.ws.rs.core.MediaType mediaType,
                                                       long waitTime,
                                                       long numRetries,
                                                       SodaRequest request2Rerun)
                                                               throws SodaError,
                                                                      InterruptedException

Method to check the async callbacks for new responses.

Parameters:

uri - the URI to go to for responses.

waitTime - the time to wait until the first response

numRetries - the total number of times to retry before failing.

request2Rerun - the object to use to re-run the request.

Returns:

the ClientReponse for a successful response.

Throws:

SodaError - thrown if there is an error. Investigate the structure for more information.

InterruptedException - throws is the thread is interrupted.

deleteRaw

public com.sun.jersey.api.client.ClientResponse deleteRaw(URI uri)
                                                   throws LongRunningQueryException,
                                                          SodaError

Raw version of the API for issuing a delete, doing common error processing and returning the ClientResponse.

Parameters:

uri - URI to issue a request to. Any id information should have already been added.

Returns:

the raw ClientReponse to the request. Any errors will have already been processed, and have thrown and exception.

Throws:

LongRunningQueryException - thrown if this query is long running and a 202 is returned. In this case, the caller likely wants to call follow202.

SodaError - thrown if there is an error. Investigate the structure for more information.

queryRaw

public com.sun.jersey.api.client.ClientResponse queryRaw(URI uri,
                                                javax.ws.rs.core.MediaType acceptType)
                                                  throws LongRunningQueryException,
                                                         SodaError

Issues a raw GET to a URI. The URI should be properly formed, and the response will process the errors and throw if there are any.

Parameters:

uri - URI to issue a request to. Any id information should have already been added.

acceptType - the MIME Type accepted by this client

Returns:

the raw ClientReponse to the request. Any errors will have already been processed, and have thrown and exception.

Throws:

LongRunningQueryException - thrown if this query is long running and a 202 is returned. In this case, the caller likely wants to call follow202.

SodaError - thrown if there is an error. Investigate the structure for more information.

postRaw

public com.sun.jersey.api.client.ClientResponse postRaw(URI uri,
                                               javax.ws.rs.core.MediaType mediaType,
                                               Object object)
                                                 throws LongRunningQueryException,
                                                        SodaError

Issues a raw POST to a URI. The URI should be properly formed, and the response will process the errors and throw if there are any.

Parameters:

uri - URI to issue a request to. Any id information should have already been added.

mediaType - the MIME type the object is to be sent to the server as.

object - the object to send down to the server. This can be a Jackson serializable object or a raw InputStream.

Returns:

the raw ClientReponse to the request. Any errors will have already been processed, and have thrown and exception.

Throws:

LongRunningQueryException - thrown if this query is long running and a 202 is returned. In this case, the caller likely wants to call follow202.

SodaError - thrown if there is an error. Investigate the structure for more information.

postFileRaw

public com.sun.jersey.api.client.ClientResponse postFileRaw(URI uri,
                                                   javax.ws.rs.core.MediaType mediaType,
                                                   File file)
                                                     throws LongRunningQueryException,
                                                            SodaError

Throws:

LongRunningQueryException

SodaError

postFileRaw

public com.sun.jersey.api.client.ClientResponse postFileRaw(URI uri,
                                                   javax.ws.rs.core.MediaType mediaType,
                                                   javax.ws.rs.core.MediaType acceptType,
                                                   File file)
                                                     throws LongRunningQueryException,
                                                            SodaError

Throws:

LongRunningQueryException

SodaError

putRaw

public <T> com.sun.jersey.api.client.ClientResponse putRaw(URI uri,
                                                  javax.ws.rs.core.MediaType mediaType,
                                                  Object object)
                                                throws LongRunningQueryException,
                                                       SodaError

Issues a raw PUT to a URI. The URI should be properly formed, and the response will process the errors and throw if there are any.

Parameters:

uri - URI to issue a request to. Any id information should have already been added.

mediaType - the MIME type the object is to be sent to the server as.

object - the object to send down to the server. This can be a Jackson serializable object or a raw InputStream.

Returns:

the raw ClientReponse to the request. Any errors will have already been processed, and have thrown and exception.

Throws:

LongRunningQueryException - thrown if this query is long running and a 202 is returned. In this case, the caller likely wants to call follow202.

SodaError - thrown if there is an error. Investigate the structure for more information.

putFileRaw

public com.sun.jersey.api.client.ClientResponse putFileRaw(URI uri,
                                                  javax.ws.rs.core.MediaType mediaType,
                                                  File file)
                                                    throws LongRunningQueryException,
                                                           SodaError

Throws:

LongRunningQueryException

SodaError

putFileRaw

public com.sun.jersey.api.client.ClientResponse putFileRaw(URI uri,
                                                  javax.ws.rs.core.MediaType mediaType,
                                                  javax.ws.rs.core.MediaType acceptType,
                                                  File file)
                                                    throws LongRunningQueryException,
                                                           SodaError

Throws:

LongRunningQueryException

SodaError