Creating a KiiObject

This topic explains how to create a KiiObject. For setting a JSON document in a KiiObject, see Setting a Key-value Pair.

Creating a KiiObject

In order to create a KiiObject, create a KiiObject on the client by calling the object() method of the destination bucket and then the save() method. Kii Cloud automatically assigns the ID of the created KiiObject.

// Create a KiiObject.
KiiObject object = KiiUser.getCurrentUser().bucket("MyBucket").object();

// Set key-value pairs.
object.set("score", 987);
object.set("mode", "easy");
object.set("premiumUser", false);

try {
  // Save the KiiObject.
  object.save();
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}

// Create a KiiObject.
KiiObject object = KiiUser.getCurrentUser().bucket("MyBucket").object();

// Set key-value pairs.
object.set("score", 987);
object.set("mode", "easy");
object.set("premiumUser", false);

// Save the KiiObject.
object.save(new KiiObjectCallBack() {
  @Override
  public void onSaveCompleted(int token, KiiObject object, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
});

Make sure to call the save() method. The key-value pairs set in the KiiObject are not saved on Kii Cloud until the method is called.

The code above creates a KiiObject in the specified bucket, MyBucket in the user scope in this sample, on Kii Cloud.

In the code above, the set() method is called to set values in three fields before the save() method. For procedures for setting values, see Setting a Key-value Pair.

Creating a KiiObject with an ID

Kii Cloud automatically assigns an ID to a newly created KiiObject. You can also choose to have your mobile app to assign an ID to a KiiObject.

The following code creates a KiiObject with the same parameters as those in the previous example except that the ID is explicitly specified.

String id = "score_userX";

// Check whether the KiiObject ID is valid.
if (!KiiObject.isValidObjectID(id)) {
  // The KiiObject ID is invalid.
}

// Create a KiiObject with the specific ID.
KiiObject object = KiiUser.getCurrentUser().bucket("MyBucket").object(id);

// Set key-value pairs.
object.set("score", 987);
object.set("mode", "easy");
object.set("premiumUser", false);

try {
  // Save the KiiObject.
  object.saveAllFields(true);
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}

String id = "score_userX";

// Check whether the KiiObject ID is valid.
if(!KiiObject.isValidObjectID(id)) {
  // The KiiObject ID is invalid.
}

// Create a KiiObject with the specific ID.
KiiObject object = KiiUser.getCurrentUser().bucket("MyBucket").object(id);

// Set key-value pairs.
object.set("score", 987);
object.set("mode", "easy");
object.set("premiumUser", false);

// Save the KiiObject.
object.saveAllFields(new KiiObjectCallBack() {
  @Override
  public void onSaveCompleted(int token, KiiObject object, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
}, true);

You specify an ID when executing the object() method. You can check the validity of the ID with the isValidObjectID() method (For the valid ID pattern, see the Javadoc).

Call the saveAllFields() method to create a new KiiObject with the specified ID on Kii Cloud. You cannot use the save() method when you create a KiiObject with a specific ID.

If the KiiObject with the ID "score_userX" already exists on the server, the above sample code will overwrite the existing KiiObject. You can prevent this overwriting by setting the overWrite argument of the saveAllFields() method to false. See the Javadoc for more details.

Tips for accessing KiiObjects

Cannot write in a bucket in the application scope

All users, including anonymous users who have not logged in yet, can read the application scope. Writing in the application scope, however, requires the users to log in. If you want to avoid forcing your application users to log in, we recommend you to leverage the "pseudo user" feature (and not to change the ACL of the application scope). See Pseudo Users for more discussion.

You need to be careful about the security when you are using the application scope. See Security for more details.

Cannot read a KiiObject that has been written in a bucket

Double check if the scope of the bucket is correct.

Remember that buckets in different scopes are separate even if they have the same name. The same applies when you use the data browser in the developer portal.

For example, KiiObjects created in the application scope with Kii.bucket("myBucket") are not readable with Kii.user().bucket("myBucket") because this method looks for the bucket in the user scope.