Getting a Key-value Pair

In order to get a key-value pair from a KiiObject, call a method of the KiiObject class such as the getInt() method and the getString() method. The Kii Cloud SDK for Android provides a getter method for each of the data types supported by the SDK.

Specify the key for the value to get as the argument of the getter method. The value of the key at the first level of the JSON document hierarchy will be obtained.

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"
}

int score = object.getInt("score"); // score=987
String mode = object.getString("mode"); // mode="easy"
boolean premiumUser = object.getBoolean("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.

Specifying a default value

Certain getter methods are overloaded so that you can get a default value when a specified key does not exist or such a getter method fails to get a value because it cannot convert the value to a specified data type. Note that you cannot specify a default value for several data types.

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.

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

int data1 = object.getInt("highscore", 123); // data1=123
int data2 = object.getInt("score", 123); // data2=987
boolean data3 = object.getBoolean("mode", true); // data3=true
String data4 = object.getString("mode", "true"); // data4="easy"

data1: The default value specified as the second argument is used because the JSON document does not contain the specified key "highscore".
data2: The value in the JSON document is used because the value of the specified key "score" can be obtained as an int value. The default value is ignored.
data3: The default value specified as the second argument is used because the value of the specified key "mode" cannot be obtained as a boolean value.
data4: The value in the JSON document is used because the value of the specified key "mode" can be obtained as a String value. The default value is ignored.

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 or the "Method call with a default value" column.

The "Obtained value" column does not include examples of default values being returned. However, as explained earlier, when a specified key does not exist or a getter method fails to get a value, a default value specified as an argument is obtained.

Data type	Key-value pair in the JSON format	Method call	Method call with a default value	Obtained value
String	`"data":"123"`	`getString("data");`	`getString("data", "abc");`	"123"
int	`"data":123`	`getInt("data");`	`getInt("data", 987);`	123
long	`"data":123`	`getLong("data");`	`getLong("data", 987L);`	123L
double	`"data":123.456`	`getDouble("data");`	`getDouble("data", 987.654);`	123.456
Boolean	`"data":true`	`getBoolean("data");`	`getBoolean("data", false);`	true
GeoPoint	`"data":{` `"_type": "point",` `"lat": 35.658603,` `"lon": 139.745433` `}`	`getGeoPoint("data");`	`getGeoPoint("data", geoPoint);`	GeoPoint (35.658603, 139.745433)
JSONArray	`"data":[1,2,3]`	`getJSONArray("data");`	`getJSONArray("data", array);`	[1,2,3]
JSONObject	`"data":{"a":"b"}`	`getJSONObject("data");`	A default value cannot be specified	{"a":"b"}
Uri	`"data":"http://kii.com/"`	`getUri("data");`	A default value cannot be specified	"http://kii.com/"
byte[]	`"data":"YWFhYQ==\n"`	`getByteArray("data");`	A default value cannot be specified	{61, 61, 61, 61} decoded from the BASE64 encoded string

Getting a value of a basic data type

To get key-value pairs from a KiiObject, use a getter method that supports the target data type. To learn more, see the Javadoc.

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

// Instantiate a KiiObject.
Uri objUri = Uri.parse("Set the URI of an existing KiiObject here");
KiiObject object = KiiObject.createByUri(objUri);

try {
  // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
  object.refresh();

  // Get key-value pairs.
  String stringData = object.getString("stringValue");
  int intData = object.getInt("intValue");
  long longData = object.getLong("longValue");
  double doubleData = object.getDouble("doubleValue");
  boolean booleanData = object.getBoolean("booleanValue");
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}

// Instantiate a KiiObject.
Uri objUri = Uri.parse("Set the URI of an existing KiiObject here");
KiiObject object = KiiObject.createByUri(objUri);

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
object.refresh(new KiiObjectCallBack() {
  @Override
  public void onRefreshCompleted(int token, KiiObject object, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
    // Get key-value pairs.
    String stringData = object.getString("stringValue");
    int intData = object.getInt("intValue");
    long longData = object.getLong("longValue");
    double doubleData = object.getDouble("doubleValue");
    boolean booleanData = object.getBoolean("booleanValue");
  }
});

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 keySet() method as shown in the following example:

// Instantiate a KiiObject.
Uri objUri = Uri.parse("Set the URI of an existing KiiObject here");
KiiObject object = KiiObject.createByUri(objUri);
try {
  // Refresh the KiiObject to retrieve the latest data from Kii Cloud.
  object.refresh();

  // Get a list of keys.
  HashSet<String> keyset = object.keySet();
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}

// Instantiate a KiiObject.
Uri objUri = Uri.parse("Set the URI of an existing KiiObject here");
KiiObject object = KiiObject.createByUri(objUri);

// Refresh the KiiObject to retrieve the latest data from Kii Cloud.
object.refresh(new KiiObjectCallBack() {
  @Override
  public void onRefreshCompleted(int token, KiiObject object, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
    // Get a list of keys.
    HashSet<String> keyset = object.keySet();
  }
});

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

When you attempt to get a key-value pair, if a specified key does not exist, the SDK throws an exception. You can avoid the exception by executing a getter method with a default 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 json.getString("key1") will return a null.
Executing json.getString("key2") will return an empty string.
Executing json.getString("key3") will throw an exception.
Executing json.getString("key3", null) will return a null.

We recommend you to use the same data type for writing and reading a key-value pair in a KiiObject. See Data Conversion in the SDK for more discussion.

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 getCreatedTime() and getModifiedTime() 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 GeoPoint object. Then, call the getLatitude() and getLongitude() methods to get the latitude and longitude, respectively.

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

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

Getting complex data

To get a byte array, a JSON object, and an array of JSON objects from a KiiObject, use the corresponding getter method.

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 byte array.
byte[] byteArray = object.getByteArray("myByteArray");

// Get a value of a JSON object.
JSONObject jsonObject = object.getJSONObject("myObject");
String jsonString = jsonObject.toString();

// Get a value of a JSON array.
JSONArray jsonArray = object.getJsonArray("myArray");
try {
  String arrayElement1 = jsonArray.get(0).toString();
  String arrayElement2 = jsonArray.get(1).toString();
} catch (JSONException e) {
  // Handle the error.
}