io.clarify.api
Class ClarifyClient

java.lang.Object
  us.monoid.web.Resty
      io.clarify.api.ClarifyClient

public class ClarifyClient
extends us.monoid.web.Resty

The starting point for the Clarify API Java SDK. The client offers two methods of interacting with the Clarify API: 1) A high-level API for performing common workflows, including high-level classes to wrap API resource responses 2) A low-level API for directly interacting with the Clarify REST API. This provides only a thin wrapper around the actual HTTP request, but will perform the necessary steps for constructing properly-formed HTTP requests and for sending credentials. The low-level API uses Resty, a lightweight wrapper for making HTTP API calls and processing the response payload using CSS-style JSON selectors. More details are available at the Resty Overview page

Nested Class Summary

Nested classes/interfaces inherited from class us.monoid.web.Resty

us.monoid.web.Resty.Option, us.monoid.web.Resty.Proxy, us.monoid.web.Resty.Timeout

Field Summary

static String	CLARIFY_BASE_URI
static String	DEFAULT_VERSION
static String	SDK_VERSION

Fields inherited from class us.monoid.web.Resty

DEFAULT_USER_AGENT, MOZILLA, userAgent

Constructor Summary

ClarifyClient(String appKey)

Method Summary

BundleTrack	addTrackToBundle(String bundleId, URI trackUri) Adds a new Track to the Bundle with the given media URI, then fetches the resulting resource (resulting in 2 API calls)
protected String	baseUri() Returns the base URI for the Clarify API
String	buildPathFromHref(String href) Helper to concatenate the base URI of the Clarify API with a given HREF
String	buildPathFromResourcePath(String resourcePath) Helper to concatenate the base URI of the Clarify API, the version, and a given resource path
Bundle	createBundle(String name, URI mediaURI) Creates a new Clarify Bundle using the Create Bundle REST API.
Bundle	createBundle(String name, URI mediaURI, Map<String,String> fields) Creates a new Clarify Bundle using the Create Bundle REST API using a name, initial media URL, and any number of additional fields (as defined by the Clarify Create Bundle API).
boolean	deleteBundle(String bundleId) Deletes this bundle by bundleId, all of its related Metadata and Tracks, along with media stored on Clarify systems.
boolean	deleteTrack(String bundleId, String trackId) Deletes a track from a specific media Bundle.
Bundle	findBundle(String bundleId) Uses the Retrieve Bundle API to return a specific Bundle by the specific bundleId
Bundle	findBundleByHref(String href) Uses the Retrieve Bundle API to return a specific Bundle by the specific relative href path
BundleMetadata	findMetadata(String bundleId) Returns a Bundle's Metadata class, with details on the bundle and any attached user data (if available)
BundleTrack	findTrackByHref(String href) Returns a specific Track by the HREF provided in a JSON response
BundleTrack	findTrackForBundle(String bundleId, String trackId) Returns a specific Track by track number for a media Bundle
BundleList	listBundles() Retrieves the first page from the List Bundles REST API.
BundleTrackList	listTracksForBundle(String bundleId) Returns the list of Tracks associated to this media Bundle
boolean	resetMetadata(String bundleId) Delete the metadata of a bundle and set data to {} (empty object.) This is functionally equivalent to an update metadata request with data set to {}.
BundleSearchResults	searchBundles(String query) Performs a wildcard search for the specific query string provided.
BundleSearchResults	searchBundles(String query, Map<String,String> params) Performs an advanced search for the specific query string provided using the additional search query parameters provided.
boolean	updateBundle(String bundleId, Map<String,String> fields) Updates an existing Bundle's properties, incrementing the Bundle version number on success.
BundleMetadata	updateMetadata(String bundleId, String json) Updates the user-defined data property of the Bundle's Metadata with the supplied JSON string, then return a refreshed copy (resulting in 2 API calls)
String	urlEncodeMap(Map<String,String> fields)
protected String	version() Returns the default API version

Methods inherited from class us.monoid.web.Resty

addAdditionalHeaders, addStandardHeaders, alwaysSend, authenticate, authenticate, authenticateForRealm, bytes, bytes, bytes, bytes, content, content, content, createBinaryResource, createJSONResource, createTextResource, createXMLResource, data, data, delete, doGET, dontSend, doPOSTOrPUT, enc, fillResourceFromURL, form, form, getAdditionalHeaders, identifyAsMozilla, identifyAsResty, ignoreAllCerts, json, json, json, json, openConnection, path, put, setOptions, setProxy, text, text, text, text, withHeader, xml, xml, xml, xml, xpath

Methods inherited from class java.lang.Object

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

Field Detail

CLARIFY_BASE_URI

public static String CLARIFY_BASE_URI

DEFAULT_VERSION

public static String DEFAULT_VERSION

SDK_VERSION

public static String SDK_VERSION

Constructor Detail

ClarifyClient

public ClarifyClient(String appKey)

Method Detail

createBundle

public Bundle createBundle(String name,
                           URI mediaURI)
                    throws IOException

Creates a new Clarify Bundle using the Create Bundle REST API. This is a simple wrapper around the API for common bundle create needs and therefore only offers a limited number of the possible API parameters

Parameters:

name - a string containing the name of the API bundle

mediaURI - a URI containing a valid URL where the media for this Bundle resides

Returns:

Throws:

IOException - if the bundle fails creation

createBundle

public Bundle createBundle(String name,
                           URI mediaURI,
                           Map<String,String> fields)
                    throws IOException

Creates a new Clarify Bundle using the Create Bundle REST API using a name, initial media URL, and any number of additional fields (as defined by the Clarify Create Bundle API).

Parameters:

name - a string containing the name of the API bundle

mediaURI - a URI containing a valid URL where the media for this Bundle resides

fields - a Map of key-value String pairs with any additional parameter values. This value may be null or empty if no additional parameters are desired

Returns:

the newly created Bundle instance

Throws:

IOException - on a non-success HTTP response containing the JSON payload with the message and any error details

listBundles

public BundleList listBundles()
                       throws IOException

Retrieves the first page from the List Bundles REST API. The returned BundleList can then be used to paginate through the results. Note that each call to bundleList.nextPage() will result in another API call over the network.

Returns:

a BundleList instance containing the first page of results

Throws:

IOException - on a non-success HTTP response containing the JSON payload with the message and any error details

searchBundles

public BundleSearchResults searchBundles(String query)
                                  throws IOException

Performs a wildcard search for the specific query string provided. The result can be used to examine the matched terms, locations within the media file where the terms reside, and paginate through the results.

Parameters:

query - a raw string (automatically URL encoded) containing the query string to search for within the bundles

Returns:

a BundleSearchResults instance for examining the results and paginating through the search results

Throws:

IOException - on a non-success HTTP response containing the JSON payload with the message and any error details

searchBundles

public BundleSearchResults searchBundles(String query,
                                         Map<String,String> params)
                                  throws IOException

Performs an advanced search for the specific query string provided using the additional search query parameters provided. See the Search Bundles API documentation for the various fields, filters, and other parameters available. The result can be used to examine the matched terms, locations within the media file where the terms reside, and paginate through the results.

Parameters:

query - a raw string (automatically URL encoded) containing the query string to search for within the bundles

params - a Map of key-value String pairs to pass to the search API. May be nill or empty if no additional parameters are to be provided

Returns:

a BundleSearchResults instance for examining the results and paginating through the search results

Throws:

IOException - on a non-success HTTP response containing the JSON payload with the message and any error details

findBundleByHref

public Bundle findBundleByHref(String href)
                        throws IOException

Uses the Retrieve Bundle API to return a specific Bundle by the specific relative href path

Parameters:

href - a String containing the relative href path of the Bundle to attempt to retrieve, as returned by the Clarify API

Returns:

the Bundle retrieved by bundleId

Throws:

IOException - if a HTTP 400 error is returned due to a malformed GUID, or if a HTTP 404 not found is returned. The response will contain a JSON payload with a message and error details

findBundle

public Bundle findBundle(String bundleId)
                  throws IOException

Uses the Retrieve Bundle API to return a specific Bundle by the specific bundleId

Parameters:

bundleId - a String containing the GUID of the Bundle to attempt to retrieve

Returns:

the Bundle retrieved by bundleId

Throws:

IOException - if a HTTP 400 error is returned due to a malformed GUID, or if a HTTP 404 not found is returned. The response will contain a JSON payload with a message and error details

updateBundle

public boolean updateBundle(String bundleId,
                            Map<String,String> fields)
                     throws IOException

Updates an existing Bundle's properties, incrementing the Bundle version number on success.

Parameters:

bundleId - a String containing the GUID of the Bundle to attempt to update

fields - A Map of key-value String pairs with the fields to update (see the API docs for field names allowed to be updated)

Returns:

true if the update succeeded, otherwise an IOException will be thrown with the error received

Throws:

IOException - if a HTTP 400 error is returned due to a malformed GUID, or if a HTTP 404 not found is returned. The response will contain a JSON payload with a message and error details

deleteBundle

public boolean deleteBundle(String bundleId)
                     throws IOException

Deletes this bundle by bundleId, all of its related Metadata and Tracks, along with media stored on Clarify systems. Does not delete any media stored on remote systems. USE CAUTION AS THIS CALL CANNOT BE UNDONE

Parameters:

bundleId -

Returns:

true

Throws:

IOException - if an error occurred during the delete bundle API call

listTracksForBundle

public BundleTrackList listTracksForBundle(String bundleId)
                                    throws IOException

Returns the list of Tracks associated to this media Bundle

Parameters:

bundleId - the GUID of the Bundle to retrieve the Tracks for

Returns:

a BundleTrackList with the list of tracks and related details

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

addTrackToBundle

public BundleTrack addTrackToBundle(String bundleId,
                                    URI trackUri)
                             throws IOException

Adds a new Track to the Bundle with the given media URI, then fetches the resulting resource (resulting in 2 API calls)

Parameters:

bundleId - the GUID of the Bundle to add the Track to

trackUri - the URI of the remote media file to add to the Bundle

Returns:

a new Track instance containing the details about the new Track

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

RuntimeException - if there is a failure calling the Find Track API

findTrackForBundle

public BundleTrack findTrackForBundle(String bundleId,
                                      String trackId)
                               throws IOException

Returns a specific Track by track number for a media Bundle

Parameters:

bundleId - the GUID of the Bundle to retrieve the Track for

trackId - the GUID of the Track

Returns:

the requested Track (throws an IOException if a 404 NOT FOUND is returned)

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

findTrackByHref

public BundleTrack findTrackByHref(String href)
                            throws IOException

Returns a specific Track by the HREF provided in a JSON response

Parameters:

href - the relative URL to the resource

Returns:

the requested Track (throws an IOException if a 404 NOT FOUND is returned)

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

deleteTrack

public boolean deleteTrack(String bundleId,
                           String trackId)
                    throws IOException

Deletes a track from a specific media Bundle. This will only delete media stored on Clarify systems and not delete the source media on remote systems. USE CAUTION AS THIS CALL CANNOT BE UNDONE

Parameters:

bundleId - the GUID of the Bundle to delete the specific trackNum for

trackId - the GUID of the Track to delete

Returns:

true

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

findMetadata

public BundleMetadata findMetadata(String bundleId)
                            throws IOException

Returns a Bundle's Metadata class, with details on the bundle and any attached user data (if available)

Parameters:

bundleId - the GUID of the Bundle to retrieve the Metadata for

Returns:

a Metadata instance for the media bundle

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

updateMetadata

public BundleMetadata updateMetadata(String bundleId,
                                     String json)
                              throws IOException

Updates the user-defined data property of the Bundle's Metadata with the supplied JSON string, then return a refreshed copy (resulting in 2 API calls)

Parameters:

bundleId - the GUID of the Bundle for updating the Metadata

json - a String containing valid JSON, or null. If null is passed, then the data is reset to a JSON equiv of {}

Returns:

a refreshed Metadata instance for the media bundle

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

resetMetadata

public boolean resetMetadata(String bundleId)
                      throws IOException

Delete the metadata of a bundle and set data to {} (empty object.) This is functionally equivalent to an update metadata request with data set to {}.

Returns:

true if the operation succeeded

Throws:

IOException - if a failure occurred during the API, typically a 4xx HTTP error code + JSON payload with the error message and details

buildPathFromHref

public String buildPathFromHref(String href)

Helper to concatenate the base URI of the Clarify API with a given HREF

Parameters:

href - the full path to the resource

Returns:

string of the full request URL

buildPathFromResourcePath

public String buildPathFromResourcePath(String resourcePath)

Helper to concatenate the base URI of the Clarify API, the version, and a given resource path

Parameters:

resourcePath - the full path to the resource

Returns:

string of the full request url

urlEncodeMap

public String urlEncodeMap(Map<String,String> fields)

baseUri

protected String baseUri()

Returns the base URI for the Clarify API

Returns:

the root of the API

version

protected String version()

Returns the default API version

Returns:

version of the API