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()
andgetInt()
). 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 get123
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 valueab==
and decodes it to69
. 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
}
Method | value1 | value2 | value3 | value4 | value5 |
---|---|---|---|---|---|
"abc" | "123" | "123x456" | {"a":"b"} | null | |
getBoolean() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
getByteArray() | 69, b7 | d7,6d | d7,6d,f1,e3,9e | 69 | 93,e9,65 |
getDouble() | Throws an exception | 123.0 | Throws an exception | Throws an exception | Throws an exception |
getInt() | Throws an exception | 123 | Throws an exception | Throws an exception | Throws an exception |
getJsonArray() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
getJSONObject() | Throws an exception | Throws an exception | Throws an exception | {"a":"b"} | Throws an exception |
getLong() | Throws an exception | 123 | Throws an exception | Throws an exception | Throws an exception |
getString() | abc | 123 | 123x456 | {"a":"b"} | null |
getUri() | abc | 123 | 123x456 | {"a":"b"} | null |
getGeoPoint() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
(continue)
Method | value6 | value7 | value8 | value9 | value10 |
---|---|---|---|---|---|
[1,2,3] | 123 | 8589934592 | 456.789 | true | |
getBoolean() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | true |
getByteArray() | d7,6d | d7,6d | f3,9f,3d,f7,7e,39,f7 | e3,9e,bb,f3 | b6,bb,9e |
getDouble() | Throws an exception | 123.0 | 8.589934592E9 | 456.789 | Throws an exception |
getInt() | Throws an exception | 123 | 0 | 456 | Throws an exception |
getJsonArray() | [1,2,3] | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
getJSONObject() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
getLong() | Throws an exception | 123 | 8589934592 | 456 | Throws an exception |
getString() | [1,2,3] | 123 | 8589934592 | 456.789 | true |
getUri() | [1,2,3] | 123 | 8589934592 | 456.789 | true |
getGeoPoint() | Throws an exception | Throws an exception | Throws an exception | Throws an exception | Throws an exception |
The values in the yellow cells are obtained with no conversion.