Package org.syncany.plugins.transfer

Interface TransferManager

All Known Subinterfaces:

FeatureTransferManager

All Known Implementing Classes:

AbstractTransferManager, LocalTransferManager, PathAwareFeatureTransferManager, ReadAfterWriteConsistentFeatureTransferManager, RetriableFeatureTransferManager, TransactionAwareFeatureTransferManager

public interface TransferManager

The transfer manager synchronously connects to the remote storage. It is responsible for file upload, download and deletion.

All its operations are strictly synchronous and throw a StorageException if they fail. The implementations have to make sure that

• the repository is not corrupted, e.g. duplicate files or corrupt files
• files matching the specified file format are complete, i.e. fully uploaded
• methods that need an established connections re-connect if necessary

A transfer manager may organize files according to their type or name as it is optimal for the given storage. RemoteFiles can be classified by their sub-type. For network-transfer optimization reasons, it might be useful to place MultichunkRemoteFiles and DatabaseRemoteFiles in a separate sub-folder on the remote storage.

Method Summary

Modifier and Type	Method	Description
void	connect()	Establish a connection with the remote storage.
boolean	delete(RemoteFile remoteFile)	Deletes an existing file from the remote storage permanently.
void	disconnect()	Disconnect from the remote storage.
void	download(RemoteFile remoteFile, java.io.File localFile)	Download an existing remote file to the local disk.
java.lang.String	getRemoteFilePath(java.lang.Class<? extends RemoteFile> remoteFileClass)	Return the path for a concrete RemoteFile implementation as it is stored on the remote side *
void	init(boolean createIfRequired)	Initialize remote storage.
<T extends RemoteFile> java.util.Map<java.lang.String,T>	list(java.lang.Class<T> remoteFileClass)	Retrieves a list of all files in the remote repository, filtered by the type of the desired file, i.e.
void	move(RemoteFile sourceFile, RemoteFile targetFile)	Moves an existing file in the online storage.
StorageTestResult	test(boolean testCreateTarget)	Tests whether the repository parameters are valid.
boolean	testRepoFileExists()	Tests whether the repository file exists (see SyncanyRemoteFile).
boolean	testTargetCanCreate()	Tests whether the target path/folder can be created (if it does not exist already).
boolean	testTargetCanWrite()	Tests whether the target path/folder is writable by the application.
boolean	testTargetExists()	Tests whether the target path/folder exists.
void	upload(java.io.File localFile, RemoteFile remoteFile)	Update an existing local file to the online storage.

Method Detail

connect

void connect()
      throws StorageException

Establish a connection with the remote storage.

This method does not validate the correctness of the repository and it does not create any folders. The former is done by test(boolean), the latter is done by init(boolean).

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc.

disconnect

void disconnect()
         throws StorageException

Disconnect from the remote storage.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc.

init

void init(boolean createIfRequired)
   throws StorageException

Initialize remote storage. This method is called to set up a new repository.

Parameters:

createIfRequired - true if the method should handle repo creation

Throws:

StorageException - If the connection drops, or any other exception occurs.

download

void download(RemoteFile remoteFile,
              java.io.File localFile)
       throws StorageException

Download an existing remote file to the local disk.

The file is either downloaded completely or nothing at all. In the latter case, a StorageException is thrown.

Implementations must make sure that if a file matches the specified name schema, it must be complete and consistent.

If remoteFile does not exist, a StorageFileNotFoundException is thrown.

Parameters:

remoteFile - Existing source file on the remote storage. The only required property of the remote file is the name.

localFile - Not existing local file to which the remote file is going to be downloaded.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc.

upload

void upload(java.io.File localFile,
            RemoteFile remoteFile)
     throws StorageException

Update an existing local file to the online storage.

The file is either uploaded completely or nothing at all. In the latter case, a StorageException is thrown.

Implementations must make sure that if a file matches the specified name schema, it must be complete and consistent.

Implementations must NOT upload a file if it already exists and has the same file size as the local file.

Parameters:

localFile - Existing local file that is going to be uploaded.

remoteFile - Not existing destination file on the remote storage. The only required property of the remote file is the name.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc.

move

void move(RemoteFile sourceFile,
          RemoteFile targetFile)
   throws StorageException

Moves an existing file in the online storage.

If the sourceFile does not exists, a StorageMoveException is thrown.

Parameters:

sourceFile - Existing remote file that is to be moved.

targetFile - Destination for the remote file.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc.

delete

boolean delete(RemoteFile remoteFile)
        throws StorageException

Deletes an existing file from the remote storage permanently.

In case the remote file does not exist, it returns immediately without any notice. If the file cannot be deleted or the connection breaks, a StorageException is thrown.

Parameters:

remoteFile - Existing remote file to be deleted. The only required property of the remote file is the name.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc

list

<T extends RemoteFile> java.util.Map<java.lang.String,T> list(java.lang.Class<T> remoteFileClass)
                                                             throws StorageException

Retrieves a list of all files in the remote repository, filtered by the type of the desired file, i.e. by a sub-class of RemoteFile.

Parameters:

remoteFileClass - Filter class: RemoteFile or a sub-type thereof

Returns:

Returns a list of remote files. In the map, the key is the file name, the value the entire RemoteFile object.

Throws:

StorageException - If the connection fails due to no Internet connection, authentication errors, etc

test

StorageTestResult test(boolean testCreateTarget)

Tests whether the repository parameters are valid. In particular, the method tests whether a target (folder, bucket, etc.) exists or, if not, whether it can be created. It furthermore tests whether a repository at the target already exists by checking if the SyncanyRemoteFile exists.

The relevant result is determined by the following methods:

• testTargetExists(): Tests whether the target exists.
• testTargetCanWrite(): Tests whether the target is writable.
• testTargetCanCreate(): Tests whether the target can be created if it does not exist already. This is only called if testCreateTarget is set.
• testRepoFileExists(): Tests whether the repo file exists.

Parameters:

testCreateTarget - If true, the test will test if the target can be created in case it does not exist. If false, this test will be skipped.

Returns:

Returns the result of testing the repository.

See Also:

StorageTestResult

testTargetExists

boolean testTargetExists()
                  throws StorageException

Tests whether the target path/folder exists. This might be done by listing the parent path/folder or by retrieving metadata about the target. The method returns true if the target exists, false otherwise.

This method is called by the test(boolean) method (only during repository initialization or initial connection).

Returns:

Returns true if the target exists, false otherwise

Throws:

StorageException - If the test cannot be performed, e.g. due to a connection failure

testTargetCanWrite

boolean testTargetCanWrite()
                    throws StorageException

Tests whether the target path/folder is writable by the application. This method may either check the write permissions of the target or actually write a test file to check write access. If the target does not exist, false is returned. If the target exists and is writable, true is returned.

This method is called by the test(boolean) method (only during repository initialization or initial connection).

Returns:

Returns true if the target can be written to, false otherwise

Throws:

StorageException - If the test cannot be performed, e.g. due to a connection failure

testTargetCanCreate

boolean testTargetCanCreate()
                     throws StorageException

Tests whether the target path/folder can be created (if it does not exist already). This method may either check the permissions of the parent path/folder or actually create and delete the target to determine create permissions.

If the target already exists, the method returns true. If it does not, but it can be created (according to tests of this method), it also returns true. In all other cases, false is returned.

This method is called by the test(boolean) method, but only if the testCreateTarget flag is set to true!

Returns:

Returns true if the target can be created or already exists, false otherwise

Throws:

StorageException - If the test cannot be performed, e.g. due to a connection failure

testRepoFileExists

boolean testRepoFileExists()
                    throws StorageException

Tests whether the repository file exists (see SyncanyRemoteFile). This method is called by the test(boolean) method (only during repository initialization (or initial connection).

This method is called by the test(boolean) method (only during repository initialization or initial connection).

Returns:

Returns true if the repository is valid, false otherwise

Throws:

StorageException - If the test cannot be performed, e.g. due to a connection failure

getRemoteFilePath

java.lang.String getRemoteFilePath(java.lang.Class<? extends RemoteFile> remoteFileClass)

Return the path for a concrete RemoteFile implementation as it is stored on the remote side *

Parameters:

remoteFileClass - The class to provide the path for

Returns:

A string pointing to the folder where a file is stored