com.kii.cloud.storage
Class KiiObject

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

public final class KiiObject
extends KiiBaseObject
implements FileHolder

Provide arbitrary key-value Object CRUD operation on KiiCloud. KiiObject has following reserve keys which can not be used as the key of setter methods

Reserve keys

  • _kiireserved_uri

  • Field Summary
     
    Fields inherited from class com.kii.cloud.storage.KiiBaseObject
    mJSON, mJSONPatch, mReservedKeys
     
    Method Summary
     KiiACL acl()
              Get the ACL handle of this KiiObject.
    static KiiObject createByUri(Uri uri)
              Instantiate KiiObject from the Uri.
    After instantiate, call {link refresh()} to fetch properties.
     void delete()
              Delete KiiObject from KiiCloud.
     int delete(KiiObjectCallBack callBack)
              Asynchronous call for delete().
     void deleteBody()
              Delete the body of the KiiObject from KiiCloud.
     int deleteBody(KiiObjectCallBack callBack)
              Asynchronous call for deleteBody().
     KiiDownloader downloader(Context context, java.io.File dest)
              Instantiate KiiDownloader.
     long getCreatedTime()
              Get the created time on Server
     GeoPoint getGeoPoint(java.lang.String key)
              Get the GeoPoint of this object tied to the specified key.
     GeoPoint getGeoPoint(java.lang.String key, GeoPoint fallback)
              Get the GeoPoint of this object tied to the specified key.
    protected  java.lang.String getId()
               
     long getModifedTime()
              Get the modified time on Server
     void refresh()
              Get latest KiiObject form KiiCloud and refresh properties.
    Any update has not saved will be overwritten.
     int refresh(KiiObjectCallBack callBack)
              Asynchronous call for refresh().
    Background task will be initiated to execute the task.
     void save()
              Create or update the KiiObject on KiiCloud.
     void save(boolean overWrite)
              Create or update the KiiObject on KiiCloud.
     int save(KiiObjectCallBack callBack)
              Asynchronous call for save().
     int save(KiiObjectCallBack callback, boolean overWrite)
              Asynchronous call for save(boolean).
    Background task will be initiated to execute the task.
     void saveAllFields(boolean overWrite)
              Create or update the KiiObject on KiiCloud.
     int saveAllFields(KiiObjectCallBack callback, boolean overWrite)
              Asynchronous call for saveAllFields(boolean).
     void set(java.lang.String key, GeoPoint value)
              Set GeoPoint to this object with the specified key.
     void set(java.lang.String key, JSONObject value)
              Create/Update the key/value.
     JSONObject toJSON()
              Returns JSON representation of this KiiObject.
     java.lang.String toString()
              Returns String representation of JSONObject get from toJSON()
     Uri toUri()
              Retruns URI of this KiiObject.
    The format is
    Application scope object: kiicloud://buckets/{name of bucket}/objects/{id of the object} User scope object: kiicloud://users/{id of the user}/buckets/{name of bucket}/objects/{id of the object} Group scope object: kiicloud://groups/{id of the group}/buckets/{name of bucket}/objects/{id of the object}
     KiiUploader uploader(Context context, java.io.File source)
              Instantiate KiiUploader with local file.
     
    Methods inherited from class com.kii.cloud.storage.KiiBaseObject
    getBoolean, getBoolean, getByteArray, getDouble, getDouble, getInt, getInt, getJsonArray, getJSONArray, getJSONObject, getJSONOfArbitraryFields, getLong, getLong, getString, getString, getUri, has, keySet, remove
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
     

    Method Detail

    acl

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

    Returns:
    ACL of this KiiObject
    See Also:
    KiiACL

    createByUri

    public static KiiObject createByUri(Uri uri)
    Instantiate KiiObject from the Uri.
    After instantiate, call {link refresh()} to fetch properties.

    Parameters:
    uri - Uri of the KiiObject to instantiate.
    Returns:
    instance of KiiObject.
    Throws:
    java.lang.IllegalArgumentException - when passed uri is empty or null or invalid

    delete

    public void delete()
                throws java.io.IOException,
                       BadRequestException,
                       UnauthorizedException,
                       ForbiddenException,
                       ConflictException,
                       NotFoundException,
                       UndefinedException
    Delete KiiObject from KiiCloud.
    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 or KiiObject is not exists in the cloud.
    See Also:
    delete(KiiObjectCallBack)

    delete

    public int delete(KiiObjectCallBack 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 - notifies events
    Returns:
    id used for cancel this operation. see also Kii.cancelTask(int)
    Throws:
    WrongThreadException - Thrown if this method is not executed in UI thread.

    deleteBody

    public void deleteBody()
                    throws java.io.IOException,
                           BadRequestException,
                           UnauthorizedException,
                           ForbiddenException,
                           ConflictException,
                           NotFoundException,
                           UndefinedException
    Delete the body of the KiiObject from KiiCloud.
    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 or KiiObject is not exists in the cloud.
    See Also:
    deleteBody(KiiObjectCallBack)

    deleteBody

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

    Parameters:
    callBack - notifies events
    Returns:
    id used for cancel this operation. see also 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 -
    dest - destination file.
    Returns:
    KiiDownloader instance
    Throws:
    InvalidHolderException - thrown if this KiiObject 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.

    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()

    getGeoPoint

    public GeoPoint getGeoPoint(java.lang.String key)
    Get the GeoPoint of this object tied to the specified key.

    Parameters:
    key - name of the field.
    Returns:
    GeoPoint tied to the key.
    Throws:
    java.lang.IllegalArgumentException - when key is empty, null.
    IllegalKiiBaseObjectFormatException - specified key is not exists in the object.
    See Also:
    getGeoPoint(String, GeoPoint)

    getGeoPoint

    public GeoPoint getGeoPoint(java.lang.String key,
                                GeoPoint fallback)
    Get the GeoPoint of this object tied to the specified key. If specified key is not exists, fallback will be returned.

    Parameters:
    key - name of the field.
    fallback - return if geo point does not exist for the specified key.
    Returns:
    GeoPoint tied to the key.
    Throws:
    java.lang.IllegalArgumentException - when key is empty, null.
    See Also:
    getGeoPoint(String)

    getId

    protected java.lang.String getId()

    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()

    refresh

    public void refresh()
                 throws java.io.IOException,
                        BadRequestException,
                        UnauthorizedException,
                        ForbiddenException,
                        ConflictException,
                        NotFoundException,
                        UndefinedException
    Get latest KiiObject form KiiCloud and refresh properties.
    Any update has not saved will be overwritten. To store local updates on KiiCloud, use save()
    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. - KiiObject is not exists in the cloud.
    See Also:
    refresh(KiiObjectCallBack)

    refresh

    public int refresh(KiiObjectCallBack callBack)
    Asynchronous call for refresh().
    Background task will be initiated to execute the task.
    NOTE: This method should be executed in UI thread.

    Parameters:
    callBack - notifies events.
    Returns:
    id used for cancel this operation. see also Kii.cancelTask(int)
    Throws:
    WrongThreadException - Thrown if this method is not executed in UI thread.

    save

    public void save()
              throws java.io.IOException,
                     BadRequestException,
                     ConflictException,
                     ForbiddenException,
                     NotFoundException,
                     UnauthorizedException,
                     UndefinedException
    Create or update the KiiObject on KiiCloud. This call is same as KiiObject#save(true)
    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
    ForbiddenException
    ConflictException
    BadRequestException
    UnauthorizedException
    java.lang.IllegalStateException - When KiiClient is not initialized.
    See Also:
    save(boolean), save(KiiObjectCallBack)

    save

    public void save(boolean overWrite)
              throws java.io.IOException,
                     BadRequestException,
                     ConflictException,
                     ForbiddenException,
                     NotFoundException,
                     UnauthorizedException,
                     UndefinedException
    Create or update the KiiObject on KiiCloud. When call this method for the object that has not saved on cloud, will send all fields. Call this method for the object that has saved on cloud, Update only updated fields. Do not send fields that has not updated locally. To send all fields regardless of updates, call saveAllFields(boolean).
    NOTE: This api access to server. Should not be executed in UI/Main thread.

    Parameters:
    overWrite - If false, it will fail to update when there are updates on server object.
    If true, it will success regardless of updates on server object.
    Throws:
    java.io.IOException - When network related error has happened
    UndefinedException
    NotFoundException
    ForbiddenException
    ConflictException
    BadRequestException
    UnauthorizedException
    java.lang.IllegalStateException - Thrown when KiiObject has initiated from createByUri(Uri) and refresh() has not called, saving object with overwrite=false. Call refresh() before call this method.
    See Also:
    save(KiiObjectCallBack, boolean), saveAllFields(boolean)

    save

    public int save(KiiObjectCallBack callBack)
    Asynchronous call for save(). Background task will be initiated to execute the task.
    NOTE: This method should be executed in UI thread.

    Parameters:
    callBack - notifies events
    Returns:
    id used for cancel this operation. see also Kii.cancelTask(int)
    Throws:
    WrongThreadException - Thrown if this method is not executed in UI thread.

    save

    public int save(KiiObjectCallBack callback,
                    boolean overWrite)
    Asynchronous call for save(boolean).
    Background task will be initiated to execute the task.
    NOTE: This method should be executed in UI thread.

    Parameters:
    callBack - notifies events.
    Returns:
    id used for cancel this operation. see also Kii.cancelTask(int)
    Throws:
    WrongThreadException - Thrown if this method is not executed in UI thread.

    saveAllFields

    public void saveAllFields(boolean overWrite)
                       throws java.io.IOException,
                              BadRequestException,
                              ConflictException,
                              ForbiddenException,
                              NotFoundException,
                              UnauthorizedException,
                              UndefinedException
    Create or update the KiiObject on KiiCloud. When call this method for the object that has not saved on cloud, will send all fields. Call this method for the object that has saved on cloud, Update all field of this object.
    NOTE: This api access to server. Should not be executed in UI/Main thread.

    Parameters:
    overWrite - If false, it will fail to update when there are updates on server object.
    if true, it will success regardless of updates on server object.
    Throws:
    java.io.IOException - When network related error has happened
    UndefinedException
    NotFoundException
    ForbiddenException
    ConflictException
    BadRequestException
    UnauthorizedException
    java.lang.IllegalStateException - Thrown when KiiObject has initiated from createByUri(Uri) and refresh() has not called,
    saving object with overwrite=false. Call refresh() before call this method.
    See Also:
    save(boolean), saveAllFields(KiiObjectCallBack, boolean)

    saveAllFields

    public int saveAllFields(KiiObjectCallBack callback,
                             boolean overWrite)
    Asynchronous call for saveAllFields(boolean). Background task will be initiated to execute the task.
    NOTE: This method should be executed in UI thread.

    Parameters:
    callBack - notifies events.
    Returns:
    id used for cancel this operation. see also Kii.cancelTask(int)
    Throws:
    WrongThreadException - Thrown if this method is not executed in UI thread.

    set

    public void set(java.lang.String key,
                    GeoPoint value)
    Set GeoPoint to this object with the specified key.

    Overrides:
    set in class KiiBaseObject
    Parameters:
    key - name of the field.
    value - GeoPoint to be tied to the specified key
    Throws:
    java.lang.IllegalArgumentException - when key is empty, null, any reserve key or value is null.

    set

    public void set(java.lang.String key,
                    JSONObject value)
    Create/Update the key/value.

    Overrides:
    set in class KiiBaseObject
    Parameters:
    key - is Key string
    value - is JSONObject
    Throws:
    java.lang.IllegalArgumentException - when key or value is empty or null
    IllegalKiiBaseObjectFormatException - if value contains illegal syntax

    toJSON

    public JSONObject toJSON()
    Returns JSON representation of this KiiObject. The JSONObject contains key/value from local cache. To get the latest key/value from cloud, calling refresh() is necessary prior calling this method. On refresh, it replaces the local cache with the cloud one. The properties of KiiUser will not be changed by operating returned JSONObject. Value of getModifedTime() and getCreatedTime() will be mapped to key "_modified" and "_created" respectively and the value of toUri() will be mapped to the reserved key "_kiireserved_uri". If the object is not saved, value of "_kiireserved_uri" will be org.json.JSONObject#NULL. For the key/value that is set by KiiBaseObject.set(String, byte[]), JSONObject contains encoded(Base64) string of the value(byte[]).

    NOTE: These two keys("_modified" and "_created") always set by the cloud and can not be used in the setter methods of KiiObject.

    Returns:
    JSONObject JSONObject represents this KiiObject.

    toString

    public java.lang.String toString()
    Returns String representation of JSONObject get from toJSON()

    Overrides:
    toString in class java.lang.Object

    toUri

    public Uri toUri()
    Retruns URI of this KiiObject.
    The format is
  • Application scope object: kiicloud://buckets/{name of bucket}/objects/{id of the object}
  • User scope object: kiicloud://users/{id of the user}/buckets/{name of bucket}/objects/{id of the object}
  • Group scope object: kiicloud://groups/{id of the group}/buckets/{name of bucket}/objects/{id of the object}

  • Returns:
    URI of this KiiObject null if KiiObject has not saved on cloud.

    uploader

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

    Parameters:
    context - is the application environment
    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.