com.hds.hcpaw.fss.api

Class AnywhereFileAPI

java.lang.Object

com.hds.hcpaw.fss.api.AnywhereFileAPI

public class AnywhereFileAPI
extends java.lang.Object

API for performing file actions such as download, upload, and update. These methods are implemented using the HCP Anywhere FSS API /fss/public/file URIs.

See the method AnywhereAPI.getFileAPI() to obtain an instance of the AnywhereFileAPI.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AnywhereFileAPI(AnywhereConnector connector)

Method Summary

Modifier and Type	Method and Description
ConflictListing	listConflicts(AuthToken authToken) List conflicts for a user
LinkAccessListing	listLinkReadHistory(AuthToken authToken, java.lang.String path, java.lang.Boolean showPrivate, java.lang.String pageToken, java.lang.Integer pageSize, PageAction pageAction) List link read history of a file
ReadAccessListing	listReadHistory(AuthToken authToken, java.lang.String path, java.lang.Boolean showPrivate, java.lang.String pageToken, java.lang.Integer pageSize, PageAction pageAction) List read history of a file
FileVersionListing	listVersions(AuthToken authToken, java.lang.String path, java.lang.Boolean showPrivate, java.lang.String pageToken, java.lang.Integer pageSize, PageAction pageAction) List all versions of a file
Entry	promoteVersion(AuthToken authToken, java.lang.String path, java.lang.String etag) Promote a version of a file to current
InputStreamResult<Entry>	read(AuthToken authToken, java.lang.String path, java.lang.String etag) Deprecated.
Entry	read(AuthToken authToken, java.lang.String path, java.lang.String etag, java.lang.Boolean forceDownload, java.io.OutputStream out) Downloads the contents of the specified file and writes the contents of the file to the specified OutputStream.
Entry	read(AuthToken authToken, java.lang.String path, java.lang.String etag, java.io.OutputStream out) Downloads the contents of the specified file and writes the contents of the file to the specified OutputStream.
Entry	restore(AuthToken authToken, java.lang.String path) Restore a file that has been deleted
Entry	update(AuthToken authToken, java.lang.String path, java.lang.Long size, java.lang.String hash, java.lang.String etag, java.io.InputStream contentIn) Updates an existing file at the specified path.
Entry	upload(AuthToken authToken, java.lang.String path, java.lang.Long size, java.lang.String hash, boolean createParents, java.io.InputStream contentIn) Uploads a new file to the specified path.

Methods inherited from class java.lang.Object

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

Constructor Detail

AnywhereFileAPI

protected AnywhereFileAPI(AnywhereConnector connector)

Method Detail

read

public Entry read(AuthToken authToken,
                  java.lang.String path,
                  java.lang.String etag,
                  java.io.OutputStream out)
           throws AwUnsupportedApiVersionException,
                  java.io.IOException,
                  AnywhereException

Downloads the contents of the specified file and writes the contents of the file to the specified OutputStream. If etag is provided and matches the etag on the server, then the file will not be downloaded (as it is unchanged), and null is returned.

Parameters:

authToken - authentication token for the user performing the request

path - path (including file name) to the file you want to download

etag - the etag of the file to be read. If provided, and the latest version of the file on the server matches this etag, then the file will not be downloaded. If null, or if it does not match the etag on the server, then the file will be downloaded and the current Entry will be returned.

out - OutputStream where the contents of the file are written

Returns:

If data was downloaded (because etag was null or did not match), then the Entry downloaded is returned. (However, calling Entry.getParent() on the returned Entry will return null.) If no data was downloaded (because the etag matched), then null is returned.

Throws:

AwUnsupportedApiVersionException - if this method is not supported by the server due to the server's supported API versions

AwNotFoundException - if path does not exist

AwConflictException - if path is a folder, not a file

java.io.IOException

AnywhereException

read

public Entry read(AuthToken authToken,
                  java.lang.String path,
                  java.lang.String etag,
                  java.lang.Boolean forceDownload,
                  java.io.OutputStream out)
           throws AwUnsupportedApiVersionException,
                  java.io.IOException,
                  AnywhereException

Downloads the contents of the specified file and writes the contents of the file to the specified OutputStream. 1. If forceDownload is set to true and an etag is included, then the version associated with that etag will be downloaded. 2. If forceDownload is set to false and an etag is included, then the most recent version of the file will be downloaded if the etag does not match the most recent version's. 3. In any case where an etag is not included, the most recent version of the file will be downloaded.

Parameters:

authToken - authentication token for the user performing the request

path - path (including file name) to the file you want to download

etag - the etag of the file to be read.

forceDownload. - if true, the version associated with an included etag will always be downloaded, regardless of whether it matches the latest version of the file on the server.

out - OutputStream where the contents of the file are written

Returns:

If data was downloaded (because etag was null or did not match), then the Entry downloaded is returned. (However, calling Entry.getParent() on the returned Entry will return null.) If no data was downloaded (because the etag matched), then null is returned.

Throws:

AwUnsupportedApiVersionException - if this method is not supported by the server due to the server's supported API versions

AwNotFoundException - if path does not exist

AwConflictException - if path is a folder, not a file

java.io.IOException

AnywhereException

read

@Deprecated
public InputStreamResult<Entry> read(AuthToken authToken,
                                                 java.lang.String path,
                                                 java.lang.String etag)
                                          throws AwUnsupportedApiVersionException,
                                                 java.io.IOException,
                                                 AnywhereException

Deprecated.

Returns an InputStreamResult containing the Entry that is being read and an InputStream that contains the contents of the file to read. If etag is provided and matches the etag on the server, then the file will not be downloaded (as it is unchanged), and null is returned.

Note that care must be taken by callers of this method to close the InputStream returned.

This method is deprecated, as the preferable means of downloading a file is via read(com.hds.hcpaw.fss.api.model.AuthToken, String, String, java.io.OutputStream).

Parameters:

authToken - authentication token for the user performing the request

path - path (including file name) to the file you want to download

etag - the etag of the file to be read. If provided, and the latest version of the file on the server matches this etag, then the file will not be downloaded. If null, or if it does not match the etag on the server, then the file will be downloaded and the current Entry will be returned.

Returns:

If data was downloaded (because etag was null or did not match), then an InputStreamResult containing the Entry downloaded is returned. (However, calling Entry.getParent() on the returned Entry will return null.) If no data was downloaded (because the etag matched), then null is returned.

Throws:

AwUnsupportedApiVersionException - if this method is not supported by the server due to the server's supported API versions

AwNotFoundException - if path does not exist

AwConflictException - if path is a folder, not a file

java.io.IOException

AnywhereException

upload

public Entry upload(AuthToken authToken,
                    java.lang.String path,
                    java.lang.Long size,
                    java.lang.String hash,
                    boolean createParents,
                    java.io.InputStream contentIn)
             throws AwUnsupportedApiVersionException,
                    java.io.IOException,
                    AnywhereException

Uploads a new file to the specified path. If the specified path already exists (that is, if there is currently a file or folder at path), then the operation will fail.

Parameters:

authToken - authentication token for the user performing the request

path - path (including file name) where the file is uploaded

size - size (in bytes) of the file being uploaded.

hash - the SHA-384 hash, represented as a hex string, of the file being uploaded. This argument is optional

createParents - if true, then any parent folders of path that do not already exist will be created. if false, then the operation will fail if any parent folders of path do not exist

contentIn - InputStream containing the new file contents.

Returns:

the newly created Entry

Throws:

AwUnsupportedApiVersionException - if this method is not supported by the server due to the server's supported API versions

AwNotFoundException - if the parent of path does not exist and createParents is false

AwInvalidRequestException - if the request is invalid; for example, because the size or hash does not match the contents sent.

AwConflictException - if a folder currently exists at path, or if a file currently exists at path with a different size and hash

java.io.IOException

AnywhereException

update

public Entry update(AuthToken authToken,
                    java.lang.String path,
                    java.lang.Long size,
                    java.lang.String hash,
                    java.lang.String etag,
                    java.io.InputStream contentIn)
             throws AwUnsupportedApiVersionException,
                    java.io.IOException,
                    AnywhereException

Updates an existing file at the specified path. The operation fails if there is not a file with the specified etag at the given path.

Parameters:

authToken - authentication token for the user performing the request

path - path (including file name) where the file is being updated

size - size (in bytes) of the file being uploaded.

hash - the SHA-384 hash, represented as a hex string, of the file being uploaded. This argument is optional

etag - the etag of the file you are updating. The operation fails if there is not a file with this etag at the given path

contentIn - InputStream containing the new file contents

Returns:

the updated Entry

Throws:

AwUnsupportedApiVersionException - if this method is not supported by the server due to the server's supported API versions

AwNotFoundException - if the parent of path does not exist and createParents is false

AwInvalidRequestException - if the request is invalid; for example, because the size or hash does not match the contents sent.

AwConflictException - if the etag does not match the current etag on the server, or if path refers to a folder instead of a file

java.io.IOException

AnywhereException

listVersions

public FileVersionListing listVersions(AuthToken authToken,
                                       java.lang.String path,
                                       java.lang.Boolean showPrivate,
                                       java.lang.String pageToken,
                                       java.lang.Integer pageSize,
                                       PageAction pageAction)
                                throws AwUnsupportedApiVersionException,
                                       java.io.IOException,
                                       AnywhereException

List all versions of a file

Parameters:

authToken - authentication token for the user performing the request

path - Path to the file

showPrivate - if true, show private history, else shared history

pageToken - Token string

pageSize - Number of entries to return

pageAction - Which versions to return

Returns:

A SharedFolderListing

Throws:

AwUnsupportedApiVersionException

java.io.IOException

AnywhereException

listReadHistory

public ReadAccessListing listReadHistory(AuthToken authToken,
                                         java.lang.String path,
                                         java.lang.Boolean showPrivate,
                                         java.lang.String pageToken,
                                         java.lang.Integer pageSize,
                                         PageAction pageAction)
                                  throws AwUnsupportedApiVersionException,
                                         java.io.IOException,
                                         AnywhereException

List read history of a file

Parameters:

authToken - authentication token for the user performing the request

path - Path to the file

showPrivate - if true, show private history, else shared history

pageToken - Token string

pageSize - Number of entries to return

pageAction - Which history to return

Returns:

A SharedFolderListing

Throws:

AwUnsupportedApiVersionException

java.io.IOException

AnywhereException

listLinkReadHistory

public LinkAccessListing listLinkReadHistory(AuthToken authToken,
                                             java.lang.String path,
                                             java.lang.Boolean showPrivate,
                                             java.lang.String pageToken,
                                             java.lang.Integer pageSize,
                                             PageAction pageAction)
                                      throws AwUnsupportedApiVersionException,
                                             java.io.IOException,
                                             AnywhereException

List link read history of a file

Parameters:

authToken - authentication token for the user performing the request

path - Path to the file

showPrivate - if true, show private history, else shared history

pageToken - Token string

pageSize - Number of entries to return

pageAction - Which history to return

Returns:

A SharedFolderListing

Throws:

AwUnsupportedApiVersionException

java.io.IOException

AnywhereException

promoteVersion

public Entry promoteVersion(AuthToken authToken,
                            java.lang.String path,
                            java.lang.String etag)
                     throws AwUnsupportedApiVersionException,
                            java.io.IOException,
                            AnywhereException

Promote a version of a file to current

Parameters:

authToken - authentication token for the user performing the request

path - Path to the file

etag - etag associated with the version of file to promote to current

Returns:

The promoted Entry

Throws:

AwUnsupportedApiVersionException

java.io.IOException

AnywhereException

restore

public Entry restore(AuthToken authToken,
                     java.lang.String path)
              throws AwUnsupportedApiVersionException,
                     java.io.IOException,
                     AnywhereException

Restore a file that has been deleted

Parameters:

authToken - authentication token for the user performing the request

path - Path to the file

Throws:

AwUnsupportedApiVersionException

java.io.IOException

AnywhereException

listConflicts

public ConflictListing listConflicts(AuthToken authToken)
                              throws AwUnsupportedApiVersionException,
                                     java.io.IOException,
                                     AnywhereException

List conflicts for a user

Parameters:

authToken - authentication token for the user performing the request

Throws:

AnywhereException

java.io.IOException

AwUnsupportedApiVersionException