Class Index | File Index

Classes


Class KiiObject

Represents a KiiObject object
Defined in: KiiSDK.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Method Summary
Method Attributes Method Name and Description
 
delete(callbacks)
Delete the object from the server
 
deleteBody(callbacks)
Delete the object body from the server.
 
downloadBody(callbacks)
Download body data of this object.
 
get(key)
Gets the value associated with the given key
 
Get the body content-type.
 
Get the server's creation date of this object
 
Gets the geo point associated with the given key.
 
Get Id of the object or null if the object ID hasn't been assigned.
 
Gets the array object that contains all keys of custom field.
 
Get the modified date of the given object, assigned by the server
 
Get the application-defined type name of the object
 
Get the UUID of the given object, assigned by the server
<static>  
KiiObject.isValidObjectID(objectID)
Check if given ID is valid for object ID.
 
moveBody(targetObjectUri, callbacks)
Move KiiObject body from an object to another object.
 
Get the ACL handle for this file

Any KiiACLEntry objects added or revoked from this ACL object will be appended to/removed from the server on ACL save.
 
Get a specifically formatted string referencing the object

The object must exist in the cloud (have a valid UUID).
<static>  
KiiObject.objectWithURI(uri)
Generate a new KiiObject based on a given URI
 
publishBody(callbacks)
Publish object body.
 
publishBodyExpiresAt(expiresAt, callbacks)
Publish object body with expiration date.
 
publishBodyExpiresIn(expiresIn, callbacks)
Publish object body with expiration duration.
 
refresh(callbacks)
Updates the local object's data with the user data on the server

The object must exist on the server.
 
remove(key)
Removes a pair of key/value from this object.
 
save(callbacks, overwrite)
Create or update the KiiObject on KiiCloud.
 
saveAllFields(callbacks, overwrite)
Create or update the KiiObject on KiiCloud.
 
set(key, value)
Sets a key/value pair to a KiiObject

If the key already exists, its value will be written over.
 
setGeoPoint(key, KiiGeoPoint)
Set Geo point to this object with the specified key.
 
uploadBody(srcDataBlob, callbacks)
Upload body data of this object.
Class Detail
KiiObject()
Method Detail
{Promise} delete(callbacks)
Delete the object from the server
  // example to use callbacks directly
  var obj = . . .; // a KiiObject
  obj.delete({
      success: function(theDeletedObject) {
          // do something
      },
  
      failure: function(theObject, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var obj = . . .; // a KiiObject
  obj.delete().then(
      function(theDeletedObject) {
          // do something
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful delete request
{Method} callbacks.failure
The callback method to call on a failed delete request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theDeletedObject). theDeletedObject is KiiObject instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} deleteBody(callbacks)
Delete the object body from the server.
If the KiiObject has not saved on the cloud or deleted or exist but does not have body object, request will be failed.
If succeeded, The object body content type will be nullified.
  // example to use callbacks directly
  var obj = . . .; // a KiiObject
  obj.deleteBody({
      success: function(theDeletedObject) {
          // do something
      },
  
      failure: function(obj, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var obj = . . .; // a KiiObject
  obj.deleteBody().then(
      function(theDeletedObject) {
          // do something
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful delete request
{Method} callbacks.failure
The callback method to call on a failed delete request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theDeletedObject). theDeletedObject is the KiiObject instance which this method was called on.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} downloadBody(callbacks)
Download body data of this object.
If the KiiObject has not saved on the cloud or deleted or exist but does not have body object, request will be failed.
NOTE: this requires XMLHttpRequest Level 2, FileReader and Blob supports. Do not use it in server code.
  // example to use callbacks directly
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  myObject.downloadBody({
      progress: function (oEvent) {
        if (oEvent.lengthComputable) {
          var percentComplete = oEvent.loaded / oEvent.total;
          //getting download progress. You can update progress bar on this function.
  
        }
      },
      success: function(obj, bodyBlob) {
          // Obtaind body contents as bodyBlob.
          // content-type managed in Kii Cloud can be obtained from type attr.
          // It is same as obj.getBodyContentType();
          var contentType = bodyBlob.type;
      },
      failure: function(obj, anErrorString) {
          // Handle error.
      }
  });
  
  // example to use Promise
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  myObject.downloadBody({
      progress: function (oEvent) {
        if (oEvent.lengthComputable) {
          var percentComplete = oEvent.loaded / oEvent.total;
          //getting download progress. You can update progress bar on this function.
  
        }
      }
  ).then(
      function(params) {
          // Obtaind body contents as bodyBlob.
          // content-type managed in Kii Cloud can be obtained from type attr.
          // It is same as obj.getBodyContentType();
          var obj = params[0];
          var bodyBlob = params[1];
          var contentType = bodyBlob.type;
      },
      function(error) {
          // Handle error.
      }
  );
Parameters:
{Object} callbacks Optional
progress: function called on XMLHttpRequest 'progress' event listener.
sucess: function called when download succeeded.
failure: function called when download failed.
Returns:
{Promise} return promise object.
NOTE: Promise will not handle progress event. Please pass callbacks with progress function to handle progress.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is a KiiObject instance which this method was called on.
    • params[1] is the returned body blob object.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Object} get(key)
Gets the value associated with the given key
  var obj = . . .; // a KiiObject
  var score = obj.get("score");
Parameters:
{String} key
The key to retrieve
Returns:
{Object} The object associated with the key. null or undefined if none exists

{String} getBodyContentType()
Get the body content-type. It will be updated after the success of KiiObject#uploadBody and KiiObject#downloadBody returns null or undefined when this object doesn't have body content-type information.
Returns:
{String} content-type of object body

{String} getCreated()
Get the server's creation date of this object
Returns:
{String}

{KiiGeoPoint} getGeoPoint(key)
Gets the geo point associated with the given key.
Parameters:
{String} key
The key of the geo point to retrieve.
Returns:
{KiiGeoPoint} KiiGeoPoint tied to the key. null if null exists.

{String} getID()
Get Id of the object or null if the object ID hasn't been assigned.
Returns:
{String}

{Array} getKeys()
Gets the array object that contains all keys of custom field. The array of keys from local cache will be returned. To get the latest array of keys from cloud, calling refresh() is necessary prior calling this method. The returned array object does not include reserved keys such as _created, _modified, etc.
  var obj = . . .; // a KiiObject
  for(var key of obj.keys()) {
  }
Returns:
{Array} keys An array of all keys of custom field.

{String} getModified()
Get the modified date of the given object, assigned by the server
Returns:
{String}

{String} getObjectType()
Get the application-defined type name of the object
Returns:
{String} type of this object. null or undefined if none exists

{String} getUUID()
Get the UUID of the given object, assigned by the server
Returns:
{String}

<static> KiiObject.isValidObjectID(objectID)
Check if given ID is valid for object ID. Valid pattern: ^[a-zA-Z0-9-_\\.]{2,100}$
Parameters:
{String} objectID
to be checked.
Returns:
true if given ID is valid, false otherwise.

{Promise} moveBody(targetObjectUri, callbacks)
Move KiiObject body from an object to another object.
This moving can be allowed under same application, across different scopes and source/target KiiObject have a read and write permission (READ_EXISTING_OBJECT and WRITE_EXISTING_OBJECT).

If target KiiObject has a body, it will be overwritten.
  // example to use callbacks directly
  var sourceObject = ...; // Source KiiObject
  var targetObject = ...; // Target KiiObject
  var targetObjectUri = targetObject.objectURI();
  sourceObject.moveBody(targetObjectUri, {
      success: function(theSrcObject, theTgtObjectUri) {
          // Do something with the objects
      },
  
      failure: function(theSrcObject, theTgtObjectUri, anErrorString) {
          // Do something with the error response
      }
  });
  
  // example to use Promise
  var sourceObject = ...; // Source KiiObject
  var targetObject = ...; // Target KiiObject
  var targetObjectUri = targetObject.objectURI();
  sourceObject.moveBody(targetObjectUri).then(
      function(params) {
          var theSrcObject = params[0];
          var theTgtObjectUri = params[1];
          // Do something with the objects
      },
      function(error) {
          // Do something with the error response
      }
  );
Parameters:
{String} targetObjectUri
A KiiObject URI which KiiObject body is moved to.
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful move request
{Method} callbacks.failure
The callback method to call on a failed move request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is the source KiiObject instance which this method was called on.
    • params[1] is the target targetObjectUri String.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the source KiiObject instance which this method was called on.
    • error.targetObjectUri is the targetObjectUri String.
    • error.message

{KiiACL} objectACL()
Get the ACL handle for this file

Any KiiACLEntry objects added or revoked from this ACL object will be appended to/removed from the server on ACL save.
  	var obj = . . .; // a KiiObject
  	var acl = obj.objectACL();
Returns:
{KiiACL} A KiiACL object associated with this KiiObject

{String} objectURI()
Get a specifically formatted string referencing the object

The object must exist in the cloud (have a valid UUID).
  var obj = . . .; // a KiiObject
  var uri = obj.objectURI();
Returns:
{String} A URI string based on the current object. null if a URI couldn't be generated.

<static> {KiiObject} KiiObject.objectWithURI(uri)
Generate a new KiiObject based on a given URI
  var group = new KiiObject.objectWithURI("kiicloud://myuri");
Parameters:
{String} uri
The URI of the object to be represented
Throws:
{InvalidURIException}
If the URI is not in the proper format
Returns:
{KiiObject} A new KiiObject with its parameters filled in from the URI

{Promise} publishBody(callbacks)
Publish object body.
Publish object body and obtain public URL links to the body.
It doesn't expires.
If the KiiObject has not saved on the cloud or deleted or exist but does not have body object, request will be failed.
  // example to use callbacks directly
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  myObject.publishBody({
      success: function(obj, publishedUrl) {
          // ex.) You can show publishedUrl in the view.
      },
      failure: function(obj, anErrorString) {
          // Handle error.
      }
  });
  
  // example to use Promise
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  myObject.publishBody().then(
      function(params) {
          // ex.) You can show publishedUrl in the view.
          var obj = params[0];
          var publishedUrl = params[1];
      },
      function(error) {
          // Handle error.
      }
  );
Parameters:
{Object} callbacks Optional
sucess: function called when publish succeeded.
failure: function called when publish failed.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is the KiiObject instance which this method was called on.
    • params[1] is the published url string.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} publishBodyExpiresAt(expiresAt, callbacks)
Publish object body with expiration date.
Publish object body and obtain public URL links to the body.
Expires at specified date
If the KiiObject has not saved on the cloud or deleted or exist but does not have body object, request will be failed.
  // example to use callbacks directly
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  var expiresAt = new Date(2014, 11, 24);
  myObject.publishBodyExpiresAt(expiresAt, {
      success: function(obj, publishedUrl) {
          // ex.) You can show publishedUrl in the view.
      },
      failure: function(obj, anErrorString) {
          // Handle error.
      }
  });
  
  // example to use Promise
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  var expiresAt = new Date(2014, 11, 24);
  myObject.publishBodyExpiresAt(expiresAt).then(
      function(params) {
          // ex.) You can show publishedUrl in the view.
          var obj = params[0];
          var publishedUrl = params[1];
      },
      function(error) {
          // Handle error.
      }
  );
Parameters:
{Date} expiresAt
expiration date. should specify future date.
{Object} callbacks Optional
sucess: function called when publish succeeded.
failure: function called when publish failed.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is the KiiObject instance which this method was called on.
    • params[1] is the published url string.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} publishBodyExpiresIn(expiresIn, callbacks)
Publish object body with expiration duration.
Publish object body and obtain public URL links to the body.
Expires in specified duration
If the KiiObject has not saved on the cloud or deleted or exist but does not have body object, request will be failed.
  // example to use callbacks directly
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  var expiresIn = 60 * 60; // Expires in 1 hour.
  myObject.publishBodyExpiresIn(expiresIn, {
      success: function(obj, publishedUrl) {
          // ex.) You can show publishedUrl in the view.
      },
      failure: function(obj, anErrorString) {
          // Handle error.
      }
  });
  
  // example to use Promise
  var myObject = KiiObject.objectWithURI('put existing object uri here');
  var expiresIn = 60 * 60; // Expires in 1 hour.
  myObject.publishBodyExpiresIn(expiresIn).then(
      function(params) {
          // ex.) You can show publishedUrl in the view.
          var obj = params[0];
          var publishedUrl = params[1];
      },
      function(error) {
          // Handle error.
      }
  );
Parameters:
{Number} expiresIn
duration in seconds. greater than 0.
{Object} callbacks Optional
sucess: function called when publish succeeded.
failure: function called when publish failed.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(params). params is Array instance.
    • params[0] is the KiiObject instance which this method was called on.
    • params[1] is the published url string.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} refresh(callbacks)
Updates the local object's data with the user data on the server

The object must exist on the server. Local data will be overwritten.
  // example to use callbacks directly
  var obj = . . .; // a KiiObject
  obj.refresh({
      success: function(theRefreshedObject) {
          // do something with the refreshed object
      },
  
      failure: function(theObject, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var obj = . . .; // a KiiObject
  obj.refresh().then(
      function(theRefreshedObject) {
          // do something with the refreshed object
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined
{Method} callbacks.success
The callback method to call on a successful refresh request
{Method} callbacks.failure
The callback method to call on a failed refresh request
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theRefreshedObject). theRefreshedObject is KiiObject instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

remove(key)
Removes a pair of key/value from this object. This pair is also removed from server when saveAllFields() is succeeded.
  var obj = . . .; // a KiiObject
  obj.remove("score");
Parameters:
{String} key
The key to be removed

{Promise} save(callbacks, overwrite)
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 KiiObject#saveAllFields.
  // example to use callbacks directly
  var obj = . . .; // a KiiObject
  obj.save({
      success: function(theSavedObject) {
          // do something with the saved object
      },
  
      failure: function(theObject, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var obj = . . .; // a KiiObject
  obj.save().then(
      function(theSavedObject) {
          // do something with the saved object
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined sucess: function called when save succeeded.
failure: function called when save failed.
overwrite
optional, true by default.
  • If overwrite is true:
    • If a KiiObject with the same ID exists in cloud, the local copy will overwrite the remote copy, even if the remote copy is newer.
  • Otherwise:
    • If a KiiObject with the same ID exists in cloud and the remote copy is newer, save will fail.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theSavedObject). theSavedObject is KiiObject instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

{Promise} saveAllFields(callbacks, overwrite)
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.
  // example to use callbacks directly
  var obj = . . .; // a KiiObject
  obj.saveAllFields({
      success: function(theSavedObject) {
          // do something with the saved object
      },
  
      failure: function(theObject, anErrorString) {
          // do something with the error response
      }
  });
  
  // example to use Promise
  var obj = . . .; // a KiiObject
  obj.saveAllFields().then(
      function(theSavedObject) {
          // do something with the saved object
      },
      function(error) {
          // do something with the error response
      }
  );
Parameters:
{Object} callbacks Optional
An object with callback methods defined sucess: function called when save succeeded.
failure: function called when save failed.
overwrite
optional, true by default.
  • If overwrite is true:
    • If a KiiObject with the same ID exists in cloud, the local copy will overwrite the remote copy, even if the remote copy is newer.
  • Otherwise:
    • If a KiiObject with the same ID exists in cloud and the remote copy is newer, save will fail.
Returns:
{Promise} return promise object.
  • fulfill callback function: function(theSavedObject). theSavedObject is KiiObject instance.
  • reject callback function: function(error). error is an Error instance.
    • error.target is the KiiObject instance which this method was called on.
    • error.message

set(key, value)
Sets a key/value pair to a KiiObject

If the key already exists, its value will be written over.
NOTE: Before involving floating point value, please consider using integer instead. For example, use percentage, permil, ppm, etc.
The reason is:
  • Will dramatically improve the performance of bucket query.
  • Bucket query does not support the mixed result of integer and floating point. ex.) If you use same key for integer and floating point and inquire object with the integer value, objects which has floating point value with the key would not be evaluated in the query. (and vice versa)
  •   var obj = . . .; // a KiiObject
      obj.set("score", 4298);
    Parameters:
    {String} key
    The key to set. if null, empty string or string prefixed with '_' is specified, silently ignored and have no effect. We don't check if actual type is String or not. If non-string type is specified, it will be encoded as key by JSON.stringify()
    {Object} value
    The value to be set. Object must be JSON-encodable type (dictionary, array, string, number, boolean) We don't check actual type of the value. It will be encoded as value by JSON.stringify()

    setGeoPoint(key, KiiGeoPoint)
    Set Geo point to this object with the specified key.
    Parameters:
    {String} key
    The key to set.
    {KiiGeoPoint} KiiGeoPoint
    to be tied to the specified key.
    Throws:
    {String}
    Specified kiiGeoPint is not an instance of KiiGeoPoint.

    {Promise} uploadBody(srcDataBlob, callbacks)
    Upload body data of this object.
    If the KiiObject has not saved on the cloud or deleted, request will be failed.
    NOTE: this requires XMLHttpRequest Level 2, FileReader and Blob supports. Do not use it in server code.
      // example to use callbacks directly
      var myObject = Kii.bucketWithName('myBucket').createObject();
      myObject.save({
          success: function(obj) {
              var srcData = new Blob(['Hello Blob'], {type: 'text/plain'});
              obj.uploadBody(srcData, {
                  progress: function (oEvent) {
                    if (oEvent.lengthComputable) {
                      var percentComplete = oEvent.loaded / oEvent.total;
                      //getting upload progress. You can update progress bar on this function.
                    }
                  },
                  success: function(obj) {
                      // Upload succeeded.
                  },
                  failure: function(obj, anErrorString) {
                      // Handle error.
                  }
              });
          },
          failure: function(obj, error) {
              // Handle error.
          }
      });
      
      // example to use Promise
      var myObject = Kii.bucketWithName('myBucket').createObject();
      myObject.save().then(
          function(obj) {
              var srcData = new Blob(['Hello Blob'], {type: 'text/plain'});
              obj.uploadBody(srcData, {
                  progress: function (oEvent) {
                    if (oEvent.lengthComputable) {
                      var percentComplete = oEvent.loaded / oEvent.total;
                      //getting upload progress. You can update progress bar on this function.
                    }
                  }
              }).then(
                  function(obj) { // fullfill callback function
                      // Upload succeeded.
                  },
                  function(error) { // reject callback function
                      // Handle error.
                  }
              );
          },
          function(error) {
              // Handle error.
          }
      );
    Parameters:
    {Blob} srcDataBlob
    data to be uploaded. type is used to determin content-type managed in Kii Cloud. If type was not specified in the Blob, 'application/octet-stream' will be used.
    {Object} callbacks Optional
    progress: function called on XMLHttpRequest 'progress' event listener.
    sucess: function called when upload succeeded.
    failure: function called when upload failed.
    Returns:
    {Promise} return promise object.
    NOTE: Promise will not handle progress event. Please pass callbacks with progress function to handle progress.
    • fulfill callback function: function(theObject). theObject is a KiiObject instance which this method was called on.
    • reject callback function: function(error). error is an Error instance.
      • error.target is the KiiObject instance which this method was called on.
      • error.message

    Documentation generated by JsDoc Toolkit 2.4.0 on Wed Sep 15 2021 05:31:33 GMT-0000 (UTC)