com.kii.cloud.storage
Class KiiFile

java.lang.Object
  extended by com.kii.cloud.storage.KiiFile
All Implemented Interfaces:
FileHolder

public final class KiiFile
extends java.lang.Object
implements FileHolder

KiiFile provides functionality of manage files and its meta data on the cloud.


Field Summary
static java.lang.String PROPERTY_MIMETYPE
           
static java.lang.String PROPERTY_OPTIONAL
           
static java.lang.String PROPERTY_PATH
           
static java.lang.String PROPERTY_SIZE
           
static java.lang.String PROPERTY_THUMBNAIL
           
static java.lang.String PROPERTY_TITLE
           
static java.lang.String PROPERTY_TRASHED
           
 
Method Summary
 KiiACL acl()
          Get the ACL handle of this KiiFile.
static KiiFile createByUri(Uri uri)
          Instantiate a KiiFile from URI.
Use refresh() to get file meta data from the cloud.
 void delete()
          Permanently deletes a working file or trash file
NOTE: This api access to server.
 int delete(KiiFileCallBack callback)
          Asynchronous call for delete().
 KiiDownloader downloader(Context context, java.io.File dest)
          Instantiate KiiDownloader.
 int downloadFileBody(KiiFileCallBack callback, java.lang.String targetFileName)
          Asynchronous call for downloadFileBody(String).
 void downloadFileBody(java.lang.String targetFileName)
          Download the file body
NOTE: This api access to server.
 long getCreatedTime()
          Get the created time on Server
 java.lang.String getCustomField()
          Get the value in the custom field
 long getFileSize()
          Get the file size
protected  java.lang.String getId()
          This Uuid is inserted by the cloud storage once it is uploaded to the cloud.
 java.lang.String getLocalPath()
          Get the path of the file in the device file system
 java.lang.String getMimeType()
          Get the file mime type.
 long getModifedTime()
          Get the modified time on Server
 byte[] getThumbnail()
          Get the thumbnail of the file.
 java.lang.String getTitle()
          Gets the name of the file By default, SDK will set the title automatically from the filename.
 boolean isInTrash()
          Returns if the file is in trash or not
 void moveToTrash()
          Moves the working file to the trash.
 int moveToTrash(KiiFileCallBack callback)
          Asynchronous call for moveToTrash().
 java.lang.String publish()
          Publish this file and return the URL for this file.
 int publish(KiiFileCallBack callback)
          Asynchronous call for publish().
 int publish(KiiFileCallBack callback, long expireTime)
          Asynchronous call for publish(long).
 java.lang.String publish(long expireTime)
          Publish this file and return the URL for this file.
 void refresh()
          Gets KiiFile which contain the metadata only.
 int refresh(KiiFileCallBack callback)
          Asynchronous call for refresh().
 void restoreFromTrash()
          Restores the working file from the trash
NOTE: This api access to server.
 int restoreFromTrash(KiiFileCallBack callback)
          Asynchronous call for restoreFromTrash().
 void save()
          Save KiiFile in KiiCloud.
 void save(java.io.File file)
          Save KiiFile with specified local file.Specified local file must be exists in the storage.
If you like to call the local file existence optional, use save() instead.
 void save(java.io.File file, java.lang.String mimeType)
          Save KiiFile with specified local file.
 int save(KiiFileCallBack callback)
          Asynchronous call for save().
 int save(KiiFileCallBack callback, java.io.File file)
          Asynchronous call for save(File).
 int save(KiiFileCallBack callback, java.io.File file, java.lang.String mimeType)
          Asynchronous call for save(File, String).
 void saveMetaData()
          Save KiiFile metadata only.
 int saveMetaData(KiiFileCallBack callback)
          Asynchronous call for saveMetaData().
 void setCustomeField(java.lang.String customValue)
          Set the value in custom field.
 void setThumbnail(byte[] thumb)
          Set the thumbnail of the file.
 void setTitle(java.lang.String title)
          Set the title of the file.
 Uri toUri()
          Returns URI of this KiiFile.
 KiiUploader uploader(Context context, java.io.File source)
          Instantiate KiiUploader with local file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROPERTY_MIMETYPE

public static final java.lang.String PROPERTY_MIMETYPE
See Also:
Constant Field Values

PROPERTY_OPTIONAL

public static final java.lang.String PROPERTY_OPTIONAL
See Also:
Constant Field Values

PROPERTY_PATH

public static final java.lang.String PROPERTY_PATH
See Also:
Constant Field Values

PROPERTY_SIZE

public static final java.lang.String PROPERTY_SIZE
See Also:
Constant Field Values

PROPERTY_THUMBNAIL

public static final java.lang.String PROPERTY_THUMBNAIL
See Also:
Constant Field Values

PROPERTY_TITLE

public static final java.lang.String PROPERTY_TITLE
See Also:
Constant Field Values

PROPERTY_TRASHED

public static final java.lang.String PROPERTY_TRASHED
See Also:
Constant Field Values
Method Detail

acl

public KiiACL acl()
Get the ACL handle of this KiiFile.

Returns:
ACL of this KiiFile
See Also:
KiiACL

createByUri

public static KiiFile createByUri(Uri uri)
Instantiate a KiiFile from URI.
Use refresh() to get file meta data from the cloud.

Parameters:
uri - URI of KiiFile to instantiate.
Throws:
java.lang.IllegalArgumentException - When passed uri is empty or null or invalid.
See Also:
toUri()

delete

public void delete()
            throws java.io.IOException,
                   BadRequestException,
                   UnauthorizedException,
                   ForbiddenException,
                   ConflictException,
                   UndefinedException
Permanently deletes a working file or trash file
NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened
UndefinedException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
See Also:
delete(KiiFileCallBack)

delete

public int delete(KiiFileCallBack callback)
Asynchronous call for delete(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

downloader

public KiiDownloader downloader(Context context,
                                java.io.File dest)
                         throws InvalidHolderException
Instantiate KiiDownloader.

Parameters:
context - application context.
dest - destination file.
Returns:
KiiDownloader instance
Throws:
InvalidHolderException - Thrown if this KiiFile has not saved on Kii cloud or deleted.
java.lang.IllegalArgumentException - Thrown if context or dest file is null.
java.lang.IllegalStateException - Thrown if user is not logged in.

downloadFileBody

public int downloadFileBody(KiiFileCallBack callback,
                            java.lang.String targetFileName)
Asynchronous call for downloadFileBody(String). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

downloadFileBody

public void downloadFileBody(java.lang.String targetFileName)
                      throws java.io.IOException,
                             BadRequestException,
                             UnauthorizedException,
                             ForbiddenException,
                             ConflictException,
                             NotFoundException,
                             UndefinedException
Download the file body
NOTE: This api access to server. Should not be executed in UI/Main thread.

Parameters:
targetFileName - Selected filename and path where the file will be saved after downloading.
Throws:
java.io.IOException - When network related error or target file write error.
UndefinedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
java.lang.IllegalStateException - Thrown if
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
java.lang.IllegalArgumentException - Thrown if targetFileName is null or empty.
See Also:
downloadFileBody(String)

getCreatedTime

public long getCreatedTime()
Get the created time on Server

Returns:
A long represents creation date in milliseconds (Since January 1, 1970 00:00:00 UTC).
-1 when the object has not saved or has not fetch this property yet when this object has instantiate by createByUri(Uri)
See Also:
refresh()

getCustomField

public java.lang.String getCustomField()
Get the value in the custom field

Returns:
the value in string. null if no custom filed.

getFileSize

public long getFileSize()
Get the file size

Returns:
the file size in bytes

getId

protected java.lang.String getId()
This Uuid is inserted by the cloud storage once it is uploaded to the cloud. It is unique for all KiiFiles.

Returns:
ID to represent the KiiFile.

getLocalPath

public java.lang.String getLocalPath()
Get the path of the file in the device file system

Returns:
a String that contains the path value or null if not exists

getMimeType

public java.lang.String getMimeType()
Get the file mime type. By default, SDK will set the mime type automatically from the file extention When the KiiFile has initiated with local file.

Returns:
a String that represents the mime type

getModifedTime

public long getModifedTime()
Get the modified time on Server

Returns:
A long represents creation date in milliseconds (Since January 1, 1970 00:00:00 UTC).
-1 when the object has not saved or has not fetch this property yet when this object has instantiate by createByUri(Uri)
See Also:
refresh()

getThumbnail

public byte[] getThumbnail()
Get the thumbnail of the file. SDK will generate the thumbnail automatically in JPEG format When KiiFile has instantiated with local file which type is image or video.

Returns:
a byte array that represents the thumbnail and null if there are no thubmnail
See Also:
setThumbnail(byte[])

getTitle

public java.lang.String getTitle()
Gets the name of the file By default, SDK will set the title automatically from the filename. When the KiiFile has initiated with local file.

Returns:
a String with the name of the file or null if not exists

isInTrash

public boolean isInTrash()
Returns if the file is in trash or not

Returns:
boolean value of the trash status

moveToTrash

public void moveToTrash()
                 throws java.io.IOException,
                        BadRequestException,
                        UnauthorizedException,
                        ForbiddenException,
                        ConflictException,
                        NotFoundException,
                        UndefinedException
Moves the working file to the trash. To check if the file has been trashed, refer to isInTrash()
NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened.
UndefinedException
UnauthorizedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
See Also:
moveToTrash(KiiFileCallBack)

moveToTrash

public int moveToTrash(KiiFileCallBack callback)
Asynchronous call for moveToTrash(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

publish

public java.lang.String publish()
                         throws java.io.IOException,
                                BadRequestException,
                                UnauthorizedException,
                                ForbiddenException,
                                ConflictException,
                                NotFoundException,
                                UndefinedException
Publish this file and return the URL for this file. URL will not be expired.
NOTE: This api access to server. Should not be executed in UI/Main thread.

Returns:
the URL for this file.
Throws:
java.io.IOException - When network related error has happened
UndefinedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
See Also:
publish(KiiFileCallBack)

publish

public int publish(KiiFileCallBack callback)
Asynchronous call for publish(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

publish

public int publish(KiiFileCallBack callback,
                   long expireTime)
Asynchronous call for publish(long). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
expireTime - is expire time of publish URL in milliseconds (Since January 1, 1970 00:00:00 UTC).
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

publish

public java.lang.String publish(long expireTime)
                         throws java.io.IOException,
                                BadRequestException,
                                UnauthorizedException,
                                ForbiddenException,
                                ConflictException,
                                NotFoundException,
                                UndefinedException
Publish this file and return the URL for this file. URL will be expired on the specified expire time.
NOTE: This api access to server. Should not be executed in UI/Main thread.

Parameters:
expireTime - is a time of expired date in milliseconds (Since January 1, 1970 00:00:00 UTC).
Returns:
the URL for this file.
Throws:
java.io.IOException - When network related error has happened
UndefinedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
See Also:
publish(KiiFileCallBack, long)

refresh

public void refresh()
             throws java.io.IOException,
                    BadRequestException,
                    UnauthorizedException,
                    ForbiddenException,
                    ConflictException,
                    NotFoundException,
                    UndefinedException
Gets KiiFile which contain the metadata only. To get the File Body, use downloadFileBody(String)
NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened
UndefinedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
InvalidJsonException - When JSON error has happened.
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
See Also:
refresh(KiiFileCallBack)

refresh

public int refresh(KiiFileCallBack callback)
Asynchronous call for refresh(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

restoreFromTrash

public void restoreFromTrash()
                      throws java.io.IOException,
                             BadRequestException,
                             UnauthorizedException,
                             ForbiddenException,
                             ConflictException,
                             NotFoundException,
                             UndefinedException
Restores the working file from the trash
NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened.
UndefinedException
NotFoundException
ConflictException
ForbiddenException
BadRequestException
UnauthorizedException
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
- The KiiFile is not moved to trash.
IllegalKiiBaseObjectFormatException - Thrown if JSON error has happend.
See Also:
restoreFromTrash(KiiFileCallBack)

restoreFromTrash

public int restoreFromTrash(KiiFileCallBack callback)
Asynchronous call for restoreFromTrash(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

save

public void save()
          throws java.io.IOException,
                 UnauthorizedException,
                 ForbiddenException,
                 ConflictException,
                 NotFoundException,
                 UndefinedException,
                 BadRequestException
Save KiiFile in KiiCloud. If the file body does not exists,
it will only save the meta data to the cloud.
NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened
BadRequestException
UndefinedException
NotFoundException
ConflictException
ForbiddenException
UnauthorizedException
InvalidJsonException - When JSON error has happened.
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
See Also:
save(KiiFileCallBack)

save

public void save(java.io.File file)
          throws java.io.IOException,
                 UnauthorizedException,
                 ForbiddenException,
                 ConflictException,
                 NotFoundException,
                 UndefinedException,
                 BadRequestException
Save KiiFile with specified local file.Specified local file must be exists in the storage.
If you like to call the local file existence optional, use save() instead.
NOTE: This api access to server. Should not be executed in UI/Main thread.

Parameters:
file - to upload or update. When this operation applied to saved KiiFile, File body on cloud will be replaced with this file.
Throws:
java.io.IOException - When network related error has happened
BadRequestException
UndefinedException
NotFoundException
ConflictException
ForbiddenException
UnauthorizedException
InvalidJsonException - When JSON error has happened.
java.lang.IllegalArgumentException - If specified file is null or does not exists in the storage.
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
See Also:
save(KiiFileCallBack, File)

save

public void save(java.io.File file,
                 java.lang.String mimeType)
          throws java.io.IOException,
                 UnauthorizedException,
                 ForbiddenException,
                 ConflictException,
                 NotFoundException,
                 UndefinedException,
                 BadRequestException
Save KiiFile with specified local file. Specified local file must be exists in the storage.
If you like to call the local file existence optional, use save() instead.
NOTE: This api access to server. Should not be executed in UI/Main thread.

Parameters:
file - to upload or update. When this operation applied to saved KiiFile, File body on cloud will be replaced with this file.
mimeType - If you want to override mimetype determined by sdk, you can specify mime type.
Throws:
java.io.IOException - When network related error has happened
BadRequestException
UndefinedException
NotFoundException
ConflictException
ForbiddenException
UnauthorizedException
java.lang.IllegalArgumentException - If specified file is null or does not exists in the storage.
java.lang.IllegalStateException - Thrown if
- SDK is not initialized.
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
See Also:
save(KiiFileCallBack, File, String)

save

public int save(KiiFileCallBack callback)
Asynchronous call for save(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

save

public int save(KiiFileCallBack callback,
                java.io.File file)
Asynchronous call for save(File). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
file - to upload or update. When this operation applied to saved KiiFile, File body on cloud will be replaced with this file.
Returns:
task id of this operation. Can be used for cancel this operation by Kii#cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

save

public int save(KiiFileCallBack callback,
                java.io.File file,
                java.lang.String mimeType)
Asynchronous call for save(File, String). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - notifies events.
file - to upload or update. When this operation applied to saved KiiFile, File body on cloud will be replaced with this file.
mimeType - If you want to override mimetype determined by sdk, you can specify mime type.
Returns:
task id of this operation. Can be used for cancel this operation by Kii#cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

saveMetaData

public void saveMetaData()
                  throws java.io.IOException,
                         UnauthorizedException,
                         ForbiddenException,
                         ConflictException,
                         NotFoundException,
                         UndefinedException,
                         BadRequestException
Save KiiFile metadata only.
It don't update the body.
It don't check for changes in the local file.

NOTE: This api access to server. Should not be executed in UI/Main thread.

Throws:
java.io.IOException - When network related error has happened.
BadRequestException
UndefinedException
NotFoundException
ConflictException
ForbiddenException
UnauthorizedException
InvalidJsonException - When JSON error has happened.
java.lang.IllegalStateException - Thrown if
- KiiFile is not exists in the cloud.
- The KiiFile is moved to trash.
See Also:
saveMetaData(KiiFileCallBack)

saveMetaData

public int saveMetaData(KiiFileCallBack callback)
Asynchronous call for saveMetaData(). A background task will be initiated to execute the task.
NOTE: This method should be executed in UI thread.

Parameters:
callback - is the implementation for the CallBack
Returns:
unique ID which is used to identify this Async Task. This task can be canceled by Kii.cancelTask(int)
Throws:
WrongThreadException - Thrown if this method is not executed in UI thread.

setCustomeField

public void setCustomeField(java.lang.String customValue)
Set the value in custom field. The maximum length is up to 512 bytes.(UTF-8 encoded)

Parameters:
customValue - to set.
Throws:
java.lang.IllegalArgumentException - When customValue is null or larger than 512bytes(UTF-8 encoded).
IllegalKiiBaseObjectFormatException - if the value is invalid string. String validation is same as JSON spec.

setThumbnail

public void setThumbnail(byte[] thumb)
Set the thumbnail of the file. By default, SDK will generate thumbnail When the KiiFile has instantiated with local file that is image and video. You can overwirte or set thumbnail for other types of file.

Parameters:
thumb - a byte array that represents the thumbnail
Throws:
java.lang.IllegalArgumentException - Thrown if provided byte[] is null.

setTitle

public void setTitle(java.lang.String title)
Set the title of the file. By default, SDK set title automatically from the filename When KiiFile has instantiated from local file. You can overwrite the title by this method.

Parameters:
title - a String with the name of the file
Throws:
java.lang.IllegalArgumentException - when title is null
IllegalKiiBaseObjectFormatException - title is not valid string. String validation is same as JSON spec.

toUri

public Uri toUri()
Returns URI of this KiiFile. The format is
  • files not in trash: kiicloud://users/{id of the user}/buckets/sync:{name of bucket}/objects/{id of the file}
  • files in trash: kiicloud://users/{id of the user}/buckets/sync.trash:{name of bucket}/objects/{id of the file}
  • Returns:
    URI of this KiiFile, null if KiiFile has not saved on cloud.

    uploader

    public KiiUploader uploader(Context context,
                                java.io.File source)
    Instantiate KiiUploader with local file.

    Parameters:
    context - application context.
    source - file to be uploaded.
    Returns:
    KiiUploader instance
    Throws:
    java.lang.IllegalArgumentException - Thrown if context or file is null.
    java.lang.IllegalStateException - Thrown if user is not logged in.