Data Conversion in the SDK

This topic describes how the data formats used with key-value pairs are converted when the Kii Cloud SDK reads key-value pairs.

You can skip this topic if you are using only one platform (e.g. your application is only released for Android) and if your application does not have any data format casting (e.g. all values written as "int" are read as "int").

The follwoing rules apply when the getter methods get a value from a JSON document:

  • The SDK provides a getter method for each data type (e.g. getString() and getInt()). If the SDK fails to convert a value in a JSON document to a desired data type, the SDK throws an exception.

  • If no default value is set, when the SDK fails to convert a value in a JSON document to a desired data type or a specified key does not exist, the SDK throws an exception.

  • If a null value is set in a JSON document, you can get it by specifying a data type that supports a null value (e.g. String). Otherwise (e.g. int), the SDK throws an exception.

  • The SDK supports conversion of a value in a JSON document to certain data types so that you can get the value without any additional steps. For example, you can get a String value such as "20" in {"data":"20"} as an int value and a JSON object as a String value. However, you cannot get a portion of a String value as an int value (e.g. You cannot get 123 from "123x456").

  • If an overflow occurs while attempting to get a value, a zero value is returned.

  • The SDK can convert a String value in a JSON document to a byte array but it converts only a portion of a value that can be interpreted as a BASE64 value. For example, the SDK interprets {"a":"b"} as a BASE64 value ab== and decodes it to 69. This behavior depends on a library inside the SDK and you should not rely on it.

Example of data conversion

Suppose the following JSON document is stored in a KiiObject. The next table shows how each getter method processes the key-value pairs.

{
  "value1": "abc",
  "value2": "123",
  "value3": "123x456",
  "value4": {"a":"b"},
  "value5": null,
  "value6": [1, 2, 3],
  "value7": 123,
  "value8": 8589934592,
  "value9": 456.789,
  "value10": true
}
Methodvalue1value2value3value4value5
"abc""123""123x456"{"a":"b"}null
getBoolean()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptionThrows an exception
getByteArray()69, b7d7,6dd7,6d,f1,e3,9e6993,e9,65
getDouble()Throws an exception123.0Throws an exceptionThrows an exceptionThrows an exception
getInt()Throws an exception123Throws an exceptionThrows an exceptionThrows an exception
getJsonArray()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptionThrows an exception
getJSONObject()Throws an exceptionThrows an exceptionThrows an exception{"a":"b"}Throws an exception
getLong()Throws an exception123Throws an exceptionThrows an exceptionThrows an exception
getString()abc123123x456{"a":"b"}null
getUri()abc123123x456{"a":"b"}null
getGeoPoint()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptionThrows an exception

(continue)

Methodvalue6value7value8value9value10
[1,2,3]1238589934592456.789true
getBoolean()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptiontrue
getByteArray()d7,6dd7,6df3,9f,3d,f7,7e,39,f7e3,9e,bb,f3b6,bb,9e
getDouble()Throws an exception123.08.589934592E9456.789Throws an exception
getInt()Throws an exception1230456Throws an exception
getJsonArray()[1,2,3]Throws an exceptionThrows an exceptionThrows an exceptionThrows an exception
getJSONObject()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptionThrows an exception
getLong()Throws an exception1238589934592456Throws an exception
getString()[1,2,3]1238589934592456.789true
getUri()[1,2,3]1238589934592456.789true
getGeoPoint()Throws an exceptionThrows an exceptionThrows an exceptionThrows an exceptionThrows an exception

The values in the yellow cells are obtained with no conversion.