com.socrata.api

Class Soda2Producer

java.lang.Object

com.socrata.api.Soda2Base

com.socrata.api.Soda2Consumer

com.socrata.api.Soda2Producer

public class Soda2Producer
extends Soda2Consumer

API for sending requests to the SODA server for adding/removing/modifying objects in the datasets. This class does NOT deal with modifying dataset schema.

Field Summary

Fields inherited from class com.socrata.api.Soda2Consumer

HASH_RETURN_TYPE

Fields inherited from class com.socrata.api.Soda2Base

SODA_BASE_PATH, SODA_QUERY

Constructor Summary

Constructors

Constructor and Description
Soda2Producer(HttpLowLevel httpLowLevel) Constructor

Method Summary

Methods

Modifier and Type	Method and Description
<T> Meta	addObject(String resourceId, T object) Add an object using SODA2, the object will be added to the dataset with the specified resource ID.
<T> T	addObject(String resourceId, T object, Class<T> retType) Add an object using SODA2, the object will be added to the dataset with the specified resource ID.
void	delete(String resourceId, String id) Deletes a row from a dataset.
static Soda2Producer	newProducer(String url, String userName, String password, String token) Create a new Soda2Producer object, using the supplied credentials for authentication.
UpsertResult	replace(String resourceId, List objects) Replaces a dataset with a list of objects.
UpsertResult	replaceCsv(String resourceId, File csvFile) Replaces a dataset with the rows defined in the provided CSV.
UpsertResult	replaceStream(String resourceId, javax.ws.rs.core.MediaType mediaType, InputStream stream) Replaces a dataset with a the objects serialized in an input stream.
void	truncate(String resourceId) Truncates a dataset by deleting all rows in the dataset.
<T> Meta	update(String resourceId, Object id, T object) Updates an object in a dataset.
UpsertResult	upsert(String resourceId, List objects) "Upserts" a list of objects.
UpsertResult	upsertCsv(String resourceId, File csvFile) "Upserts" a list of objects.
UpsertResult	upsertStream(String resourceId, javax.ws.rs.core.MediaType mediaType, InputStream stream) "Upserts" a list of objects.

Methods inherited from class com.socrata.api.Soda2Consumer

getById, newConsumer, newConsumer, query, query

Methods inherited from class com.socrata.api.Soda2Base

doAdd, doAddObjects, doAddStream, doDelete, doReplaceObjects, doReplaceStream, doTruncate, doUpdate, getById, getHttpLowLevel, query, query

Methods inherited from class java.lang.Object

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

Constructor Detail

Soda2Producer

public Soda2Producer(HttpLowLevel httpLowLevel)

Constructor

Parameters:

httpLowLevel - HttpLowLevel object to use for connecting to the SODA2 service.

Method Detail

newProducer

public static final Soda2Producer newProducer(String url,
                        String userName,
                        String password,
                        String token)

Create a new Soda2Producer object, using the supplied credentials for authentication.

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:

fully configured Soda2Producer

truncate

public void truncate(String resourceId)
              throws SodaError,
                     InterruptedException

Truncates a dataset by deleting all rows in the dataset.

Parameters:

resourceId - id of the dataset to truncate

Throws:

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

InterruptedException - throws is the thread is interrupted.

delete

public void delete(String resourceId,
          String id)
            throws SodaError,
                   InterruptedException

Deletes a row from a dataset.

Parameters:

resourceId - resourceId id of the dataset to delete a record from

id - id of the record to delete. This should be the unique id of the record, which could be either the id the system sets, or the Row Identifier.

Throws:

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

InterruptedException - throws is the thread is interrupted.

addObject

public <T> Meta addObject(String resourceId,
                 T object)
               throws SodaError,
                      InterruptedException

Add an object using SODA2, the object will be added to the dataset with the specified resource ID.

Parameters:

resourceId - unique id or resource name of the dataset

object - object to add

Returns:

the metadata of the row added, including the system identifier

Throws:

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

InterruptedException - throws is the thread is interrupted.

addObject

public <T> T addObject(String resourceId,
              T object,
              Class<T> retType)
            throws SodaError,
                   InterruptedException

Add an object using SODA2, the object will be added to the dataset with the specified resource ID.

Parameters:

resourceId - unique id or resource name of the dataset

object - object to add

retType - the type of object to return

Returns:

the metadata of the row added, including the system identifier

Throws:

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

InterruptedException - throws is the thread is interrupted.

upsert

public UpsertResult upsert(String resourceId,
                  List objects)
                    throws SodaError,
                           InterruptedException

"Upserts" a list of objects. What this means is that it will:

1. Add the objects in the list.
2. If an object already exists with this value, it will update it.
3. If the object has a :deleted=true value, the object will be deleted.

In order to delete objects using the Upsert function, use the DeleteRecord object to map ":deleted" to an :id.

Parameters:

resourceId - unique id or resource name of the dataset

objects - list of objects to upsert

Returns:

result of objects added, removed and modified.

Throws:

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

InterruptedException - throws is the thread is interrupted.

replace

public UpsertResult replace(String resourceId,
                   List objects)
                     throws SodaError,
                            InterruptedException

Replaces a dataset with a list of objects. This is the same as doing a truncate, followed by an upsert, except that it will happen atomically (so you cannot have a failure that puts the dataset in a half state)

Parameters:

resourceId - unique id or resource name of the dataset

objects - list of objects to replace the contents of the dataset with

Returns:

Upsert result describing number of objects added/removed as well as errors.

Throws:

SodaError

InterruptedException

upsertStream

public UpsertResult upsertStream(String resourceId,
                        javax.ws.rs.core.MediaType mediaType,
                        InputStream stream)
                          throws SodaError,
                                 InterruptedException

"Upserts" a list of objects. What this means is that it will:

1. Add the objects in the list.
2. If an object already exists with this value, it will update it.
3. If the object has a :deleted=true value, the object will be deleted.

In order to delete objects using the Upsert function, use the DeleteRecord object to map ":deleted" to an :id.

Parameters:

resourceId - unique id or resource name of the dataset

mediaType - what the format of the stream is. Normally, HttpLowLevel.JSON_TYPE or HttpLowLevel.CSV_TYPE

stream - JSON stream of objects to update

Returns:

result of objects added, removed and modified.

Throws:

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

InterruptedException - throws is the thread is interrupted.

replaceStream

public UpsertResult replaceStream(String resourceId,
                         javax.ws.rs.core.MediaType mediaType,
                         InputStream stream)
                           throws SodaError,
                                  InterruptedException

Replaces a dataset with a the objects serialized in an input stream. This is the same as doing a truncate, followed by an upsert, except that it will happen atomically (so you cannot have a failure that puts the dataset in a half state)

Parameters:

resourceId - unique id or resource name of the dataset

mediaType - what the format of the stream is. Normally, HttpLowLevel.JSON_TYPE or HttpLowLevel.CSV_TYPE

stream - JSON stream of objects to replace the existing dataset with.

Returns:

Upsert result describing number of objects added/removed as well as errors.

Throws:

SodaError

InterruptedException

upsertCsv

public UpsertResult upsertCsv(String resourceId,
                     File csvFile)
                       throws SodaError,
                              InterruptedException

"Upserts" a list of objects. What this means is that it will:

1. Add the objects in the list.
2. If an object already exists with this value, it will update it.
3. If the object has a :deleted=true value, the object will be deleted.

In order to delete objects using the Upsert function, use the DeleteRecord object to map ":deleted" to an :id.

Parameters:

resourceId - unique id or resource name of the dataset

csvFile - File that contains a CSV to upload

Returns:

result of objects added, removed and modified.

Throws:

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

InterruptedException - throws is the thread is interrupted.

replaceCsv

public UpsertResult replaceCsv(String resourceId,
                      File csvFile)
                        throws SodaError,
                               InterruptedException

Replaces a dataset with the rows defined in the provided CSV. This is logically the same thing as doing a truncate followed by an upsertCsv, with the advantage of being atomic (so failures can't cause a half-state)

Parameters:

resourceId - unique id or resource name of the dataset

csvFile - File that contains a CSV to replace the dataset with

Returns:

Upsert result describing number of objects added/removed as well as errors.

Throws:

SodaError

InterruptedException

update

public <T> Meta update(String resourceId,
              Object id,
              T object)
            throws SodaError,
                   InterruptedException

Updates an object in a dataset.

Parameters:

resourceId - unique id or resource name of the dataset

id - Id based on a dataset specific unique column, or the system ID created for each row.

object - object to update the result with

Returns:

Throws:

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

InterruptedException - throws is the thread is interrupted.