Setting a Key-value Pair

In order to set a key-value pair in a KiiObject, call the set() method of the KiiObject class. The set() method has an overloaded version for each data type.

Specify a key-value pair as arguments of the set() method. The specified key-value pair will be saved at the first level of the JSON document hierarchy.

The following sample code illustrates how to set key-value pairs. For sample code that includes a step to save a KiiObject, see Creating a KiiObject or Setting a value of a basic data type below. See also Updating a KiiObject for setting key-value pairs.

KiiObject object = bucket.object();
object.set("score", 987);
object.set("mode", "easy");
object.set("premiumUser", false);

Data in the JSON format will be created as below after executing the above code and saving the KiiObject (Predefined fields are omitted).

{
  "score": 987,
  "premiumUser": false,
  "mode": "easy"
}

In order to set a key-value pair at the second or subsequent level, prepare a JSON object that has the key-value pair at the desired level and set the JSON object at the first level.

The maximum size of a KiiObject is 65534 characters (the total size of key-value pairs in the JSON format, including some internal fields used by Kii Cloud).

Supported data types

You can use any of the following data types for setting a value with the set() method.

Kii Cloud does not have any limitation to the ranges of stored values and can store the maximum values for the supported data types.

Use the values in the "Stored key-value pair in the JSON format" column in the following table as reference when checking data in the data browser in the developer portal and referencing data from another platform. You do not need to pay attention to the JSON format if you to use the same data type for writing and reading a key-value pair.

Data type Method call Stored key-value pair in the JSON format Notes
String set("data", "123"); "data":"123"
int set("data", 123); "data":123
long set("data", 123L); "data":123
double set("data", 123.456); "data":123.456
Boolean set("data", true); "data":true
GeoPoint set("data", geoPoint); "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}		 geoPoint is (35.658603, 139.745433)
JSONArray set("data", array); "data":[1,2,3] array is [1,2,3]
JSONObject set("data", json); "data":{"a":"b"} json is {"a":"b"}
Uri set("data", uri); "data":"http://kii.com/" uri is "http://kii.com/"
byte[] set("data", value); "data":"YWFhYQ==\n" value is {61, 61, 61, 61}
The value in the JSON format is BASE64 encoded
  • You cannot set a null value. An attempt to set a null value will be ignored or cause an error.
  • You can easily handle a date value (java.util.Date) by storing the number of milliseconds since 00:00:00 UTC, Thursday, 1 January 1970. To do so, use the getTime() method to convert the date value to a long value.

Setting a value of a basic data type

The following sample code illustrates how to set String, int, long, double, and Boolean values when a KiiObject is created.

This is based on the sample code in Creating a KiiObject. The code block for setting values is different.

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

// Set key-value pairs.
object.set("stringValue", "my value");
object.set("intValue", 123);
object.set("longValue", new Date().getTime());
object.set("doubleValue", 987.654);
object.set("booleanValue", true);

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("stringValue", "my value");
object.set("intValue", 123);
object.set("longValue", new Date().getTime());
object.set("doubleValue", 987.654);
object.set("booleanValue", true);

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

The above sample code creates a KiiObject with the following JSON format data (Predefined fields are omitted).

{
  "stringValue": "my value",
  "booleanValue": true,
  "longValue": 1495677489018,
  "doubleValue": 987.654,
  "intValue": 123
}

Setting a geolocation

This section explains how to set a geolocation (GeoPint) in a KiiObject.

First, create a GeoPoint object by passing a latitude and a longitude. Then, set a key-value pair that has the created GeoPoint object as its value in the KiiObject.

The following sample code illustrates how to create a KiiObject in "MyBucket", a bucket in the currently logged-in user's scope, and set two geolocations in the KiiObject.

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

// Create GeoPoint objects.
GeoPoint point1 = new GeoPoint(35.658603, 139.745433);
GeoPoint point2 = new GeoPoint(35.658625, 139.745415);

// Set the GeoPoints to the KiiObject.
object.set("location1", point1);
object.set("location2", point2);

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

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

// Create GeoPoint objects.
GeoPoint point1 = new GeoPoint(35.658603, 139.745433);
GeoPoint point2 = new GeoPoint(35.658625, 139.745415);

// Set the GeoPoints to the KiiObject.
object.set("location1", point1);
object.set("location2", point2);

// 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.

Setting complex data

In addition to the basic data types, the SDK supports a byte array, a JSON object, and an array of JSON objects.

The following sample code illustrates how to set values of these data types.

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

// Set a value of a byte array.
byte[] byteArray = {
  0x68, 0x74, 0x74, 0x70, 0x73, 0x3a, 0x2f, 0x2f
};
object.set("myByteArray", byteArray);

try {
  // Set a value of a JSON object.
  JSONObject jsonObject = new JSONObject("{\"score\": 987, \"mode\": \"easy\"}");
  object.set("myObject", jsonObject);

  // Set a value of a JSON array.
  JSONArray jsonArray = new JSONArray();
  JSONObject arrayElement1 = new JSONObject("{\"Name\": \"Alice\", \"age\": 30}");
  jsonArray.put(arrayElement1);
  JSONObject arrayElement2 = new JSONObject("{\"Name\": \"Bob\", \"age\": 28}");
  jsonArray.put(arrayElement2);
  object.set("myArray", jsonArray);
} catch (JSONException e) {
  // Handle the error.
}

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 a value of a byte array.
byte[] byteArray = {
  0x68, 0x74, 0x74, 0x70, 0x73, 0x3a, 0x2f, 0x2f
};
object.set("myByteArray", byteArray);

try {
  // Set a value of a JSON object.
  JSONObject jsonObject = new JSONObject("{\"score\": 987, \"mode\": \"easy\"}");
  object.set("myObject", jsonObject);

  // Set a value of a JSON array.
  JSONArray jsonArray = new JSONArray();
  JSONObject arrayElement1 = new JSONObject("{\"Name\": \"Alice\", \"age\": 30}");
  jsonArray.put(arrayElement1);
  JSONObject arrayElement2 = new JSONObject("{\"Name\": \"Bob\", \"age\": 28}");
  jsonArray.put(arrayElement2);
  object.set("myArray", jsonArray);
} catch (JSONException e) {
  // Handle the error.
}

// 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 above sample code creates a KiiObject with the following JSON format data (Predefined fields are omitted).

{
  "myArray": [
    {
      "Name": "Alice",
      "age": 30
    },
    {
      "Name": "Bob",
      "age": 28
    }
  ],
  "myByteArray": "aHR0cHM6Ly8=\n",
  "myObject": {
    "score": 987,
    "mode": "easy"
  }
}