CloudClient

Version 1.1 - Updated on 6/16/2016

public class CloudClient

The main Java SDK Personal Cloud Storage interface class. For server-side applications, you will typically have one instance of this class for each end user, each constructed with a different instance of CloudClientContext.

Contents

addListener

public void addListener(OAuthTokenListener listener)

  • Adds a listener for token-generation events.
  • Allows client code to persist newly-generated access tokens.

    • Parameters: listener

Authentication and Authorization

class CloudAuthClient

public class CloudAuthClient

Encapsulates methods related to the OAuth 2.0 authorization flow. Use these methods to obtain an OAuth 2.0 access tokens to access an end-user’s Personal Cloud Storage content.

To initiate the flow, call authorizeURI (for SPC users) to obtain a URI. When you send end-users to the indicated URI, they are prompted to log in using their Verizon credentials and grant your app access to their Cloud Storage Content.

If access is granted, a callback is made to the indicated URI with an authorization code. To complete the authorization flow, pass the code in a call to getAccessToken.

If access is denied, a callback is made to the indicated URI that includes the query parameter ‘error’.

getAccessToken() responses contain an OAuth 2.0 access token and a refresh token. The access token is used internally in all CloudClient API calls involving the end-user’s Cloud Storage Content. If the access token has expired, an attempt is automatically made to obtain a new access token using the refresh token. If that attempt fails, (perhaps due to an expired refresh token), a CloudAuthException is thrown, and the third-party application needs to initiate the OAuth 2.0 authorization flow again.

The third party application is responsible for persisting access tokens, as needed. We suggest that third-party applications register a callback to receive a notification when access tokens are refreshed.

authorizeURI

public URI authorizeURI(String state)

Obtains a URI used to start the OAuth 2.0 authorization flow. The URI will prompt the users to login and grant access to their Personal Cloud Storage content.

  • Parameters: state — Optional string of arbitrary data. If provided, this string is included in the callback.

getAccessToken

public OAuthToken getAccessToken(String authorizationCode) throws IOException, CloudHttpException

The second part of the standard OAuth 2.0 authorization flow. Uses an authorization code obtained through authorizeURI to obtain an access token and refresh token, used for accessing an end-user’s Cloud Storage content.

Exceptions listed below usually indicate that the OAuth 2.0 authorization flow will need to be re-run.

  • Exceptions:
    • IOException — HTTP request failure
    • CloudAuthException — Failure to obtain a new access token

refreshOauthToken

public OAuthToken refreshOauthToken(OAuthToken token) throws IOException, CloudHttpException

Called when an OAuth 2.0 access token expires. Attempts to obtain a new access token, using an end-user’s refresh token will fail if the refresh token is expired.

In general, this method will only to be called internally, when an expired access token is detected.

  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getAuthClient

public CloudAuthClient getAuthClient()

Used to make OAuth 2.0 authorization flow calls.

Account Information

getAccount

public Account getAccount() throws IOException, CloudHttpException

Obtains an end-user’s account metadata.

  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

Contacts

getContacts

public Contacts getContacts() throws IOException, CloudHttpException

Retrieves the list of contacts.

  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

File and Folder Operations

copy

public FopsMetadata copy(String src, String target, Boolean safe, ConflictSolveType conflictSolve, OverrideType override) throws IOException, CloudHttpException

Copies a file or folder.

  • Parameters:
    • src — Current file’s or folder’s path and name
    • target — New file’s or folder’s path and name
    • safe — If false, overwrites any existing file or folder in the target location. If true, uses conflictSolve param to resolve target conflicts. Default is false.
    • conflictSolve — If null, operation fails if the target file or folder already exists. If set to ConflictSolveType.copy, a non-conflicting target name is generated.
    • override — Specifies what happens when a folder of the same name already exists at the specified path:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
      .
  • Returns: Metadata of the newly-copied file or folder
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

NOTE:
You cannot perform the copy operation on a virutal folder.

createFolder

public FolderMetadata createFolder(String name, String path, OverrideType override) throws IOException, CloudHttpException

Creates a new folder.

  • Parameters:
    • name — Name of the new folder
    • path — Parent folder of the new folder
    • override — Specifies what happens when a folder of the same name already exists at the specified path:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
  • Returns: Metadata of the new folder
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

NOTE:
You cannot perform the createFolder operation on a virutal folder.

delete

public void delete(String path, Boolean purge) throws IOException, CloudHttpException

Deletes a file or folder.

  • Parameters:
    • path — Full path of the file or folder to be deleted
    • purge — If true, permanently deletes the file or folder. Defaults to false.
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

NOTE:
You cannot perform the delete operation on a virutal folder.

getFile

public HttpResponse getFile(String path) throws IOException, CloudHttpException

Retrieves a file or folder using its name.

  • Parameters:
    • path — Full path to the desired file
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getFullview

public Fullview getFullview(String etag) throws IOException, CloudHttpException

Obtains an end-user’s fullview data. Includes metadata for an end-user’s files and folders.

Return value contains a property ‘etag’, which can be supplied as an argument to subsequent getFullview() calls, in which case only metadata changes (adds, updates, and deletes) since the previous call are returned.

  • Parameters:
    • etag — The ‘etag’ value obtained from a previous call to getFullview().  If supplied, only subsequent adds, changes, and deletes are included in the response.
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getFullviewStreaming

public FullviewStreaming getFullviewStreaming(String etag) throws IOException, CloudHttpException

Obtains the current user’s fullview data. Streams the response to reduce memory consumption.

  • Parameters: etag
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getMetadata

public Metadata getMetadata(String path, Boolean includeDeleted, SortTemplate sort, Integer start, Integer count, FilterType filter) throws IOException, CloudHttpException

Retrieves metadata for a single item, a file or a folder. For folders, the response includes the folder’s children’s metadata (files and/or subfolders).

  • Parameters:
    • path — Fully-qualified path name of the required item
    • includeDeleted — For folders, if true, deleted children are included in the response.
    • sort — For folders, a SortTemplate object indicating the sort order for the folder’s children
    • start — For folders, the starting page to return in a paginated response. Defaults to 1.
    • count — For folders, the maximum items to return. Defaults to 20, maximum value is 100.
    • filter — For folders, indicates if only file or folder children will be included in the response. Valid values are folder and file.
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getMetadata

public Metadata getMetadata(String path, Boolean includeDeleted, String sort, Integer start, Integer count, FilterType filter) throws IOException, CloudHttpException

Retrieves metadata for a single item, such as a file or a folder. For folders, the response includes the folder’s children’s metadata (files and/or subfolders).

  • Parameters:
    • path — Fully-qualified path name of the required item
    • includeDeleted — For folders, if true, deleted children are included in the response.
    • sort — Sort order for folder response. Syntax is: {field}+{asc or desc}. Valid values are: name, type, versionCreated, size, extension, album, artist, captureDate, compilation, contentType, creationDate, favorite, genre, height, modificationDate, priority, source, tags, title, timelineDate.
    • start — For folders, the starting page to return in a paginated response. Defaults to 1.
    • count — For folders, the maximum items to return. Defaults to 20, maximum value is 100.
    • filter — For folders, indicates if only file or folder children will be included in the response. Valid values are folder and file.
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getSearch

public Search getSearch(SearchTemplate query, SortTemplate sort, Integer start, Integer count) throws IOException, CloudHttpException

Finds the set of the current user’s files and folders that match the search criteria.

  • Parameters:
    • querySearchTemplate object representing the query criteria
    • sortSortTemplate object representing the sort order to use
    • start — The starting page to return in a paginated response. Defaults to 1.
    • count — The maximum items to return. Defaults to 20, maximum value is 100.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getSearch

public Search getSearch(String query, String sort, Integer start, Integer count) throws IOException, CloudHttpException

Finds the set of the current user’s files and folders that match a search criteria.

  • Parameters:
    • query — Lucene-compatible query string
    • sort — Sort order for folder response. Syntax is: {field}+{asc or desc}. Valid values are: name, type, versionCreated, size, extension, album, artist, captureDate, compilation, contentType, creationDate, favorite, genre, height, modificationDate, priority, source, tags, title, timelineDate.
    • start — The starting page to return in a paginated response. Defaults to 1.
    • count — The maximum items to return. Defaults to 20, maximum value is 100.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getThumbnail

public InputStream getThumbnail(String contentToken, ThumbnailSize size, Integer th, Integer tw) throws IOException, CloudHttpException

Retrieves a thumbnail, in jpg format, for one of the current user’s image files.

  • Parameters:
    • contentToken — Content token for the desired image
    • size — Size of the requested thumbnail. We recommend to specify size rather than th and tw.
    • th — Requested thumbnail height. If size isn’t specified, th and tw are required.
    • tw — Requested thumbnail width. If size isn’t specified, th and tw are required.
  • Returns: InputStream containing the thumbnail binary content in jpg format.”
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

move

public FopsMetadata move(String src, String target, Boolean safe, ConflictSolveType conflictSolve) throws IOException, CloudHttpException

Moves a file or folder.

  • Parameters:
    • src — Current file’s or folder’s path and name
    • target — New file’s or folder’s path and name
    • safe — If false, overwrites any existing file or folder in the target location. If true, uses conflictSolve to resolve target conflicts. Default is false.
    • conflictSolve — If null, operation will fail if the target file or folder already exists. If set to ConflictSolveType.copy, a non-conflicting target name will be generated.
  • Returns:
    • Metadata of the newly-moved file or folder
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

NOTE:
You cannot perform the move operation on a virutal folder.

rename

public FopsMetadata rename(String src, String target, Boolean safe, ConflictSolveType conflictSolve) throws IOException, CloudHttpException

Renames a file or folder.

  • Parameters:
    • src — Current file’s or folder’s path and name
    • target — New file’s or folder’s path and name
    • safe — If false, overwrites any existing file or folder in the target location. If true, uses conflictSolve to resolve target conflicts. Default is false.
    • conflictSolve — If null, operation will fail if the target file or folder already exists. If set to ConflictSolveType.copy, a non-conflicting target name will be generated.
  • Returns:
    • Metadata of the newly-renamed file or folder
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

NOTE:
You cannot perform the rename operation on a virutal folder.

File Upload

NOTE:
You cannot perform the file upload operation on a virutal folder.

getFileuploadIntent

public FileUploadIntent getFileuploadIntent(String path, String name, Integer size, String checksum, boolean chunk) throws IOException, CloudHttpException

First step to uploading a file. Includes support for both chunked and unchunked uploads.

Response includes the URLs to use for uploading file content, and in the case of chunked uploads, committing the upload once the content is sent.

  • Parameters:
    • path — Path (folder) where the new file is to be uploaded
    • name — Name of the new file
    • size — File size
    • checksum — SHA-256 checksum for the file’s binary content.
    • chunktrue indicates chunked upload.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postCommit

public HttpResponse postCommit(String commitUrl) throws IOException, CloudHttpException

  • Parameters: commitUrl — The URL to use for commits. Obtained via a call to CloudClient.getFileuploadIntent.

  • Returns:

  • Exceptions:

    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postFileChunk

public HttpResponse postFileChunk(String uploadUrl, InputStream content, String contentType, int chunk, long chunkSize) throws IOException, CloudHttpException

  • Parameters:
    • uploadUrl — The URL to upload to.
    • content — Binary content to be uploaded.
    • contentType — The file’s media type, to be sent as Content-Type header during upload.
    • chunk — Number of chunks being uploaded, 1-based.
    • chunkSize — The size of the chunk being uploaded.
    • Returns:
    • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postFileUpload

public HttpResponse postFileUpload(String uploadUrl, InputStream content, String contentType, long contentLength, String checksum) throws IOException, CloudHttpException

Upload a file’s binary content.

  • Parameters:
    • uploadUrl — The URL to upload to. Obtained via a call to CloudClient.getFileuploadIntent(String, String, Integer, String, boolean)
    • content — Binary content to be uploaded.
    • contentType — The file’s media type, to be sent as Content-Type header during upload.
    • contentLength — The length of the file being uploaded.
    • checksum — SHA-256 checksum value of the file’s binary content
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

Playlists

deletePlaylist

public HttpResponse deletePlaylist(String playlistUid) throws IOException, CloudHttpException

Deletes a playlist.

  • Parameters: playlistUid — UID pf the playlist to be deleted
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

deletePlaylistItem

public HttpResponse deletePlaylistItem(String playlistUid, String itemUid) throws IOException, CloudHttpException

Removes an item from a playlist.

  • Parameters:
    • playlistUid — UID of the playlist
    • itemUid — UID of the item to be removed
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getPlaylist

public PlaylistDefinition getPlaylist(String uid) throws IOException, CloudHttpException

Retrieves a specific playlist.

  • Parameters:
    • uid — UID of the playlist to be retrieved
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getPlaylists

public PlaylistDefinitions getPlaylists(String type, Integer start, Integer count, String sort) throws IOException, CloudHttpException

Retrieves all playlists for the current user.

  • Parameters:
    • type — Playlist type. Valid values are music, image, video, and image-video. Set to Null for all types.
    • start — The starting page to return in a paginated response. Defaults to 1.
    • count — The maximum items to return. Defaults to 20, maximum value is 100.
    • sort — Sort order for folder response. Syntax is: {field}+{asc or desc}. Valid values are: name, type, versionCreated, size, extension, album, artist, captureDate, compilation, contentType, creationDate, favorite, genre, height, modificationDate, priority, source, tags, title, timelineDate.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getPlaylistItem

public HttpResponse getPlaylistItem(String playlistUid, String itemUid) throws IOException, CloudHttpException

Retrieves the binary content of a specific item from a playlist.

  • Parameters:
    • playlistUid — UID of the playlist
    • itemUid — UID of the item in the playlist ot retrieve
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

getPlaylistItems

public PlaylistItems getPlaylistItems(String playlistUid, Integer start, Integer count, String sort) throws IOException, CloudHttpException

Retrieves detailed metadata for all the items in a playlist such as: name, versionCreated, size, extension, album, artist, captureDate, contentType, creationDate, genre, height, priority, title, timelineDate.

  • Parameters:
    • playlistUid — UID of the playlist to retrieve
    • start — The starting page to return in a paginated response. Defaults to 1.
    • count — The maximum items to return. Defaults to 20, maximum value is 100.
    • sort — Sort order for folder response. Syntax is: {field}+{asc or desc}. Valid values are: name, type, versionCreated, size, extension, album, artist, captureDate, compilation, contentType, creationDate, favorite, genre, height, modificationDate, priority, source, tags, title, timelineDate.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postPlaylist

public HttpResponse postPlaylist(String name, List<String> paths, PlaylistTypeType type) throws IOException, CloudHttpException

Creates a playlist. Playlist items are optional and may be added later.

  • Parameters:
    • name — Readable name for the playlist. Does not need to be unique.
    • paths — List of paths to items to include in the playlist
    • type — Playlist type. Valid values are music, image, video, and image-video.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postPlaylist

public HttpResponse postPlaylist(String name, List<String> paths, String type) throws IOException, CloudHttpException

Creates a playlist. Playlist items are optional and may be added later.

  • Parameters:
    • name — Readable name for the playlist. Does not need to be unique.
    • paths — List of paths to items to include in the playlist.
    • type — Playlist type. Valid values are music, image, video, and image-video.
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

postPlaylistItems

public List<PlaylistDefinitionPath> postPlaylistItems(String playlistUid, List<String> paths) throws IOException, CloudHttpException

Adds items to a playlist.

  • Parameters:
    • playlistUid — UID of the playlist
    • paths — List of paths to items to be added
  • Returns: A list of PlaylistDefinitionPaths for the new items. Includes paths and UIDs.
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

putPlaylist

public PlaylistDefinitionResponse putPlaylist(String playlistUid, String name, PlaylistTypeType type) throws IOException, CloudHttpException

Updates a playlist’s name, without affecting its content.

  • Parameters:
    • playlistUid — UID of the playlist (required)
    • name — New playlist’s name (required)
    • type — Playlist type. Valid values are music, image, video, and image-video. Required value. (Required)
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

putPlaylist

public PlaylistDefinitionResponse putPlaylist(String playlistUid, String name, String type) throws IOException, CloudHttpException

Updates a playlist’s name, without affecting its content.

  • Parameters:
    • playlistUid — UID of the playlist (required)
    • name — New playlist’s name (required)
    • type — Playlist type. Valid values are music, image, video, and image-video. Must reflect the playlist’s current type. (Required)
  • Returns:
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

putPlaylistItems

public PlaylistDefinitionResponse putPlaylistItems(String playlistUid, String name, List<String> paths, PlaylistTypeType type) throws IOException, CloudHttpException

Updates (replaces) the list of items in a playlist. If desired, this API can also be used to update playlist name and/or type.

  • Parameters:
    • playlistUid — UID of the playlist (required)
    • name — Required. You can use it to update the name of the playlist.
    • paths — A list of paths for the items in the playlist. Replaces the playlist’s current list of items. If null, all items will be removed from the playlist.
    • type — Playlist type. Valid values are music, image, video, and image-video. (Required)
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

putPlaylistItems

public PlaylistDefinitionResponse putPlaylistItems(String playlistUid, String name, List<String> paths, String type) throws IOException, CloudHttpException

Updates (replaces) the list of items in a playlist. If desired, this API can also be used to update playlist name or type.

  • Parameters:
    • playlistUid — UID of the playlist (required)
    • name — Required. You can use it to update the name of the playlist.
    • paths — A list of paths for the items in the playlist. Replaces the playlist’s current list of items. If null, all items will be removed from the playlist.
    • type — Playlist type. Valid values are music, image, video, and image-video. (Required)
  • Exceptions:
    • IOException — HTTP request failure
    • CloudHttpException — Unsuccessful HTTP response

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.