Getting a Key-value Pair

In order to get a key-value pair from a KiiObject, call the get() method of the KiiObject class.

Specify the key for the value to get as the argument of the get() method. The value of the key at the first level of the JSON document hierarchy will be obtained. The data type of the obtained value is the same as that used in the JSON document.

The following is a sample JSON document and code to get values from the JSON document. The comments in the code show values to be obtained. For sample code that includes a step to get a KiiObject, see Getting a value of a basic data type below.

{
  "score": 987,
  "premiumUser": false,
  "mode": "easy"
}
var score = object.get("score"); // score=987
var mode = object.get("mode"); // mode="easy"
var premiumUser = object.get("premiumUser"); // premiumUser=false

In order to get a value of a key at the second or subsequent level, get a value of the uppermost parent key at the first level as a JSON object.

Supported data types

The table below lists the supported data types. The "Obtained value" column contains the values that are obtained by getting the key-value pairs in the "Key-value pair in the JSON format" column with the method calls in the "Method call" column.

The single get() method can handle all the data types except for a geolocation (KiiGeoPoint) because the data type of a value in JavaScript is determined at runtime. Use the dedicated getGeoPoint() method to get a geolocation. If the get() method is used for a geolocation, the internal data is obtained as an object.

Data type Key-value pair in the JSON format Method call Obtained value
string "data":"123" get("data"); "123"
number "data":123 get("data"); 123
boolean "data":true get("data"); 123L
KiiGeoPoint "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}
getGeoPoint("data"); getGeoPoint("data", geoPoint);
array "data":[1,2,3] get("data"); [1,2,3]
object "data":{"a":"b"} get("data"); {"a":"b"}

Unlike the Android SDK, the JavaScript SDK does not provide a feature to convert a byte array to BASE64. If you need this feature, get the string and then perform the BASE64 decoding in your application.

Getting a value of a basic data type

To get key-value pairs from a KiiObject, use the get() method. To learn more, see the JSDoc.

The following sample code illustrates how to get a KiiObject and its key-value pairs.

  • // Instantiate a KiiObject.
    var object = KiiObject.objectWithURI("Set the URI of an existing KiiObject here");
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh().then(
      function(theObject) {
        // Get key-value pairs.
        var stringData = object.get("stringValue");
        var intData = object.get("intValue");
        var longData = object.get("longValue");
        var doubleData = object.get("doubleValue");
        var booleanData = object.get("booleanValue");
      }
    ).catch(
      function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    );
  • // Instantiate a KiiObject.
    var object = KiiObject.objectWithURI("Set the URI of an existing KiiObject here");
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh({
      success: function(theObject) {
        // Get key-value pairs.
        var stringData = object.get("stringValue");
        var intData = object.get("intValue");
        var longData = object.get("longValue");
        var doubleData = object.get("doubleValue");
        var booleanData = object.get("booleanValue");
      },
      failure: function(theObject, errorString) {
        // Handle the error.
      }
    });

Make sure to call the refresh() method after instantiating a KiiObject, or your local KiiObject will not be updated with the latest key-value pairs.

Getting a list of keys

To get a list of all keys set on a KiiObject, use the getKeys() method as shown in the following example:

  • // Instantiate a KiiObject.
    var object = KiiObject.objectWithURI("Set the URI of an existing KiiObject here");
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh().then(
      function(theObject) {
        // Get a list of keys.
        var keys = object.getKeys();
    
        // Do something with the list.
        for (var i = 0; i < keys.length; i++) {
          console.log(keys[i] + "=" + object.get(keys[i]));
          // Do something with each key.
        }
      }
    ).catch(
      function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    );
  • // Instantiate a KiiObject.
    var object = KiiObject.objectWithURI("Set the URI of an existing KiiObject here");
    
    // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
    object.refresh({
      success: function(theObject) {
        // Get a list of keys.
        var keys = object.getKeys();
    
        // Do something with the list.
        for (var i = 0; i < keys.length; i++) {
          console.log(keys[i] + "=" + object.get(keys[i]));
          // Do something with each key.
        }
      },
      failure: function(theObject, errorString) {
        // Handle the error.
      }
    });

The getKeys() method returns custom keys that are set by your application. It does not return predefined keys such as _version and _id. For more information about the predefined keys, see Predefined Keys.

Getting an empty field

You will get a different value when a specified key does not exist and when a specified key has a null value.

Suppose that you are trying to get key-value pairs from the JSON document below.

{
  "key1": null,
  "key2": ""
}

Here are the results you will get:

  • Executing object.get("key1") will return a null.
  • Executing object.get("key2") will return an empty string.
  • Executing object.get("key3") will return a value of undefined.

For more information about the data type conversion, see Data Conversion in the SDK.

Getting the created and modified time

Kii Cloud automatically sets the created and modified time of a KiiObject. You can get them by executing the KiiObject's getCreated() and getModified() methods, respectively.

The times are in UNIX time (msec, UTC).

Getting a geolocation

To get a geolocation from a KiiObject, call the getGeoPoint() method to get a KiiGeoPoint object. Then, call the getLatitude() and getLongitude() methods to get the latitude and longitude, respectively.

// Get GeoPoints from the "location1" and "location2" keys.
var objLoc1 = object.getGeoPoint("location1");
var objLoc2 = object.getGeoPoint("location2");

// Get the latitude and longitude data.
var lat1 = objLoc1.getLatitude();
var lon1 = objLoc1.getLongitude();
var lat2 = objLoc2.getLatitude();
var lon2 = objLoc2.getLongitude();

Getting complex data

In JavaScript, you can get a JSON object and an array of JSON objects from a KiiObject without worrying about the data type.

Here is the sample code for getting the data that are set by the sample code presented in Setting complex data.

// Get a value of a JSON object.
var jsonObject = object.get("myObject");
console.log(JSON.stringify(jsonObject));

// Get a value of a JSON array.
var jsonArray = object.get("myArray");
console.log(JSON.stringify(jsonArray));