Type-safe JSON object and array classes for exchanging data between JavaScript and native Android code, providing convenient methods for data manipulation and type conversion.
Enhanced JSON object wrapper that extends JSONObject with convenient methods for data exchange between web and native layers, eliminating the need for exception handling in common operations.
/**
* JSON object wrapper for data exchange between web and native layers
* Extends JSONObject with convenient, exception-free methods
*/
public class JSObject extends JSONObject {
/**
* Create empty JSObject
*/
public JSObject();
/**
* Create JSObject from JSON string
* @param json - JSON string to parse
* @throws JSONException if string is invalid JSON
*/
public JSObject(String json) throws JSONException;
/**
* Create JSObject from existing JSONObject with specific keys
* @param obj - Source JSONObject
* @param names - Array of key names to copy
* @throws JSONException if copy fails
*/
public JSObject(JSONObject obj, String[] names) throws JSONException;
/**
* Convert a JSONObject to JSObject
* @param obj - JSONObject to convert
* @returns JSObject with all keys copied
* @throws JSONException if conversion fails
*/
public static JSObject fromJSONObject(JSONObject obj) throws JSONException;
/**
* Put key-value pair without throwing exceptions
* @param key - Key string
* @param value - Value object (supports all JSON types)
* @returns This JSObject for method chaining
*/
public JSObject put(String key, Object value);
/**
* Put boolean value
* @param key - Key string
* @param value - Boolean value
* @returns This JSObject for method chaining
*/
public JSObject put(String key, boolean value);
/**
* Put integer value
* @param key - Key string
* @param value - Integer value
* @returns This JSObject for method chaining
*/
public JSObject put(String key, int value);
/**
* Put double value
* @param key - Key string
* @param value - Double value
* @returns This JSObject for method chaining
*/
public JSObject put(String key, double value);
/**
* Put long value
* @param key - Key string
* @param value - Long value
* @returns This JSObject for method chaining
*/
public JSObject put(String key, long value);
/**
* Get string value safely with null fallback
* @param key - Key string
* @returns String value or null if not present
*/
@Override
@Nullable
public String getString(String key);
/**
* Get string value with default fallback
* @param key - Key string
* @param defaultValue - Default value if key not present
* @returns String value or default
*/
@Nullable
public String getString(String key, @Nullable String defaultValue);
/**
* Get integer value safely
* @param key - Key string
* @returns Integer value or null if not present or not a number
*/
@Nullable
public Integer getInteger(String key);
/**
* Get integer value with default fallback
* @param key - Key string
* @param defaultValue - Default value if key not present
* @returns Integer value or default
*/
@Nullable
public Integer getInteger(String key, @Nullable Integer defaultValue);
/**
* Get boolean value with default fallback
* @param key - Key string
* @param defaultValue - Default value if key not present
* @returns Boolean value or default
*/
@Nullable
public Boolean getBoolean(String key, @Nullable Boolean defaultValue);
/**
* Get boolean value safely (alias for getBoolean(key, null))
* @param key - Key string
* @returns Boolean value or null if not present
*/
@Nullable
public Boolean getBool(String key);
/**
* Get double value safely
* @param key - Key string
* @returns Double value or null if not present or not a number
*/
@Nullable
public Double getDouble(String key);
/**
* Get JSObject value
* @param key - Key string
* @returns JSObject value or null if not present
*/
@Nullable
public JSObject getJSObject(String key);
/**
* Get JSArray value
* @param key - Key string
* @returns JSArray value or null if not present
*/
@Nullable
public JSArray getJSArray(String key);
/**
* Check if key exists in this object
* @param key - Key string to check
* @returns Boolean indicating if key exists
*/
public boolean has(String key);
/**
* Remove a key from this object
* @param key - Key string to remove
* @returns This JSObject for method chaining
*/
public JSObject remove(String key);
}Usage Examples:
@PluginMethod
public void processUserData(PluginCall call) {
// Create response object
JSObject result = new JSObject();
// Add various data types
result.put("success", true);
result.put("timestamp", System.currentTimeMillis());
result.put("message", "Processing completed");
result.put("score", 95.5);
// Add nested objects
JSObject metadata = new JSObject();
metadata.put("version", "1.0");
metadata.put("source", "android");
result.put("metadata", metadata);
call.resolve(result);
}
@PluginMethod
public void handleConfigUpdate(PluginCall call) {
JSObject config = call.getObject("config");
if (config == null) {
call.reject("Config object required");
return;
}
// Safely extract values with defaults
String mode = config.getString("mode", "default");
Integer timeout = config.getInteger("timeout", 5000);
Boolean enableLogging = config.getBoolean("enableLogging", false);
// Check for optional settings
if (config.has("advanced")) {
JSObject advanced = config.getJSObject("advanced");
// Process advanced settings
}
// Apply configuration
applyConfig(mode, timeout, enableLogging);
call.resolve();
}Enhanced JSON array wrapper that extends JSONArray with convenient methods for array manipulation and type-safe element access.
/**
* JSON array wrapper for data exchange between web and native layers
* Extends JSONArray with convenient, type-safe methods
*/
public class JSArray extends JSONArray {
/**
* Create empty JSArray
*/
public JSArray();
/**
* Create JSArray from existing JSONArray
* @param array - JSONArray to copy
* @throws JSONException if copy fails
*/
public JSArray(JSONArray array) throws JSONException;
/**
* Create JSArray from Collection
* @param collection - Collection to convert to array
*/
public JSArray(Collection<?> collection);
/**
* Create JSArray from array of objects
* @param array - Object array to convert
*/
public JSArray(Object[] array);
/**
* Get JSObject at index safely
* @param index - Array index
* @returns JSObject at index or null if not present or not an object
* @throws JSONException if index is invalid
*/
public JSObject getJSObject(int index) throws JSONException;
/**
* Get string at index safely
* @param index - Array index
* @returns String value or null if not present
*/
@Nullable
public String getString(int index);
/**
* Get integer at index safely
* @param index - Array index
* @returns Integer value or null if not present or not a number
*/
@Nullable
public Integer getInteger(int index);
/**
* Get boolean at index safely
* @param index - Array index
* @returns Boolean value or null if not present
*/
@Nullable
public Boolean getBoolean(int index);
/**
* Get double at index safely
* @param index - Array index
* @returns Double value or null if not present or not a number
*/
@Nullable
public Double getDouble(int index);
/**
* Add value to array
* @param value - Value to add (supports all JSON types)
* @returns This JSArray for method chaining
*/
public JSArray put(Object value);
/**
* Add value at specific index
* @param index - Index to insert at
* @param value - Value to add
* @returns This JSArray for method chaining
* @throws JSONException if index is invalid
*/
public JSArray put(int index, Object value) throws JSONException;
/**
* Get length of array
* @returns Integer length of array
*/
public int length();
/**
* Convert to regular List
* @returns List containing array elements
*/
public List<Object> toList();
}Usage Examples:
@PluginMethod
public void getItems(PluginCall call) {
JSArray items = new JSArray();
// Add various types to array
items.put("item1");
items.put(42);
items.put(true);
// Add nested objects
JSObject item = new JSObject();
item.put("name", "Complex Item");
item.put("value", 100);
items.put(item);
JSObject result = new JSObject();
result.put("items", items);
result.put("count", items.length());
call.resolve(result);
}
@PluginMethod
public void processItems(PluginCall call) {
JSArray inputItems = call.getArray("items");
if (inputItems == null) {
call.reject("Items array required");
return;
}
JSArray processedItems = new JSArray();
// Process each item
for (int i = 0; i < inputItems.length(); i++) {
try {
JSObject item = inputItems.getJSObject(i);
if (item != null) {
// Process object item
JSObject processed = processObjectItem(item);
processedItems.put(processed);
} else {
// Handle primitive item
String stringItem = inputItems.getString(i);
if (stringItem != null) {
processedItems.put(stringItem.toUpperCase());
}
}
} catch (JSONException ex) {
// Handle invalid item
continue;
}
}
JSObject result = new JSObject();
result.put("processedItems", processedItems);
call.resolve(result);
}Utility methods and classes for converting between different data types in the context of web-native data exchange.
/**
* Utility class for data type conversions (static methods)
*/
public class JSValue {
/**
* Convert object to JSObject if possible
* @param obj - Object to convert
* @returns JSObject or null if conversion not possible
*/
public static JSObject toJSObject(Object obj);
/**
* Convert object to JSArray if possible
* @param obj - Object to convert
* @returns JSArray or null if conversion not possible
*/
public static JSArray toJSArray(Object obj);
/**
* Check if object is JSON-serializable
* @param obj - Object to check
* @returns Boolean indicating if object can be serialized to JSON
*/
public static boolean isSerializable(Object obj);
/**
* Convert object to JSON-safe type
* @param obj - Object to convert
* @returns Object that can be safely added to JSON
*/
public static Object toJsonSafe(Object obj);
}
/**
* Exception thrown when JSON export fails
*/
public class JSExportException extends Exception {
/**
* Create JSON export exception
* @param message - Error message
* @param cause - Underlying cause
*/
public JSExportException(String message, Throwable cause);
}Usage Examples:
@PluginMethod
public void convertData(PluginCall call) {
Object rawData = call.getData().get("data");
// Try to convert to JSObject
JSObject objData = JSValue.toJSObject(rawData);
if (objData != null) {
// Process as object
processObjectData(objData);
} else {
// Try to convert to JSArray
JSArray arrayData = JSValue.toJSArray(rawData);
if (arrayData != null) {
// Process as array
processArrayData(arrayData);
} else {
call.reject("Data must be object or array");
return;
}
}
call.resolve();
}
private JSObject createSafeResponse(Map<String, Object> data) {
JSObject result = new JSObject();
for (Map.Entry<String, Object> entry : data.entrySet()) {
Object safeValue = JSValue.toJsonSafe(entry.getValue());
if (JSValue.isSerializable(safeValue)) {
result.put(entry.getKey(), safeValue);
}
}
return result;
}