Plugin Call System

/**
 * Wraps a call from the web layer to native Android plugin
 * Provides access to call data and response methods
 */
public class PluginCall {
    
    /** Special callback ID indicating no matching callback on client side */
    public static final String CALLBACK_ID_DANGLING = "-1";
    
    /**
     * Create a plugin call instance
     * @param msgHandler - Message handler for sending responses
     * @param pluginId - ID of the target plugin
     * @param callbackId - Callback ID for response routing
     * @param methodName - Name of the method being called
     * @param data - Call parameters as JSObject
     */
    public PluginCall(MessageHandler msgHandler, String pluginId, String callbackId, String methodName, JSObject data);
    
    /**
     * Send success response with result data
     * @param successResult - PluginResult containing response data
     */
    public void successCallback(PluginResult successResult);
    
    /**
     * Send error response with message
     * @param msg - Error message string
     */
    public void errorCallback(String msg);
    
    /**
     * Resolve the call with success data (convenience method)
     * @param data - JSObject containing response data
     */
    public void resolve(JSObject data);
    
    /**
     * Resolve the call with no data (convenience method)
     */
    public void resolve();
    
    /**
     * Reject the call with error message (convenience method)
     * @param msg - Error message string
     */
    public void reject(String msg);
    
    /**
     * Reject the call with error message and error code
     * @param msg - Error message string
     * @param code - Error code string
     */
    public void reject(String msg, String code);
    
    /**
     * Reject the call with error message and optional exception (convenience method)
     * @param msg - Error message string
     * @param ex - Optional exception that caused the error
     */
    public void reject(String msg, Exception ex);
    
    /**
     * Reject the call with error message and additional data
     * @param msg - Error message string
     * @param data - Additional error data as JSObject
     */
    public void reject(String msg, JSObject data);
    
    /**
     * Reject the call with error message, code, and exception
     * @param msg - Error message string
     * @param code - Error code string
     * @param ex - Exception that caused the error
     */
    public void reject(String msg, String code, Exception ex);
    
    /**
     * Reject the call with error message, code, and data
     * @param msg - Error message string
     * @param code - Error code string
     * @param data - Additional error data as JSObject
     */
    public void reject(String msg, String code, JSObject data);
    
    /**
     * Reject the call with error message, exception, and data
     * @param msg - Error message string
     * @param ex - Exception that caused the error
     * @param data - Additional error data as JSObject
     */
    public void reject(String msg, Exception ex, JSObject data);
    
    /**
     * Reject the call with error message, code, exception, and data (convenience method)
     * @param msg - Error message string
     * @param code - Error code string
     * @param ex - Optional exception that caused the error
     * @param data - Optional error data as JSObject
     */
    public void reject(String msg, String code, Exception ex, JSObject data);
    
    /**
     * Get the call parameters as JSObject
     * @returns JSObject containing all call parameters
     */
    public JSObject getData();
    
    /**
     * Get the name of the method being called
     * @returns Method name string
     */
    public String getMethodName();
    
    /**
     * Get the plugin ID for this call
     * @returns Plugin ID string
     */
    public String getPluginId();
    
    /**
     * Get the callback ID for response routing
     * @returns Callback ID string
     */
    public String getCallbackId();
    
    /**
     * Set whether this call should be kept alive for multiple responses
     * Used for event listeners and streaming operations
     * @param keepAlive - Boolean indicating if call should remain active
     */
    public void setKeepAlive(boolean keepAlive);
    
    /**
     * Check if this call is configured to stay alive
     * @returns Boolean indicating if call will remain active
     */
    public boolean isKeptAlive();
    
    /**
     * Check if this call has been released and should no longer be used
     * @returns Boolean indicating if call is released
     * @deprecated Use isKeptAlive() instead
     */
    @Deprecated
    public boolean isReleased();
    
    /**
     * Reject the call with "UNIMPLEMENTED" error code
     * Used for API methods not yet implemented on this platform
     */
    public void unimplemented();
    
    /**
     * Reject the call with "UNIMPLEMENTED" error code and custom message
     * @param msg - Custom error message for unimplemented functionality
     */
    public void unimplemented(String msg);
    
    /**
     * Reject the call with "UNAVAILABLE" error code
     * Used when API is not available due to missing prerequisites
     */
    public void unavailable();
    
    /**
     * Reject the call with "UNAVAILABLE" error code and custom message
     * @param msg - Custom error message for unavailable functionality
     */
    public void unavailable(String msg);
}

@PluginMethod
public void getData(PluginCall call) {
    // Get parameters from the call
    String userId = call.getString("userId");
    boolean includeMetadata = call.getBoolean("includeMetadata", false);
    
    try {
        // Perform operation
        JSObject result = new JSObject();
        result.put("data", fetchUserData(userId));
        if (includeMetadata) {
            result.put("metadata", getMetadata());
        }
        
        // Send success response
        call.resolve(result);
    } catch (Exception ex) {
        // Send error response
        call.reject("Failed to fetch data", ex);
    }
}

@PluginMethod
public void startListening(PluginCall call) {
    // Keep call alive for multiple responses
    call.setKeepAlive(true);
    
    // Start background task that sends periodic updates
    startPeriodicUpdates(call);
    
    // Initial response
    JSObject initial = new JSObject();
    initial.put("status", "listening");
    call.resolve(initial);
}

/**
 * Contains response data sent back to JavaScript layer
 * Supports both success and error states
 */
public class PluginResult {
    
    /**
     * Create empty plugin result
     */
    public PluginResult();
    
    /**
     * Create plugin result with success data
     * @param data - JSObject containing response data
     */
    public PluginResult(JSObject data);
    
    /**
     * Create plugin result with success data and keep-alive flag
     * @param data - JSObject containing response data
     * @param keepAlive - Whether to keep the call active for more responses
     */
    public PluginResult(JSObject data, boolean keepAlive);
    
    /**
     * Set the result data
     * @param data - JSObject containing response data
     */
    public void setData(JSObject data);
    
    /**
     * Get the result data
     * @returns JSObject containing response data
     */
    public JSObject getData();
    
    /**
     * Set whether this result should keep the call alive
     * @param keepAlive - Boolean indicating if call should remain active
     */
    public void setKeepAlive(boolean keepAlive);
    
    /**
     * Check if this result keeps the call alive
     * @returns Boolean indicating if call will remain active
     */
    public boolean isKeepAlive();
}

@PluginMethod
public void processData(PluginCall call) {
    JSObject result = new JSObject();
    result.put("processed", true);
    result.put("timestamp", System.currentTimeMillis());
    
    // Create and send result
    PluginResult pluginResult = new PluginResult(result);
    call.successCallback(pluginResult);
}

@PluginMethod  
public void streamData(PluginCall call) {
    // Send initial response but keep call alive
    JSObject initial = new JSObject();
    initial.put("streaming", true);
    
    PluginResult initialResult = new PluginResult(initial, true);
    call.successCallback(initialResult);
    
    // Continue sending updates...
}

/**
 * Parameter access methods (available on PluginCall instance)
 */
public class PluginCall {
    /**
     * Get string parameter with null fallback
     * @param name - Parameter name
     * @returns String value or null if not present
     */
    public String getString(String name);
    
    /**
     * Get string parameter with default value
     * @param name - Parameter name  
     * @param defaultValue - Default value if parameter not present
     * @returns String value or default
     */
    public String getString(String name, String defaultValue);
    
    /**
     * Get integer parameter
     * @param name - Parameter name
     * @returns Integer value or null if not present or not a number
     */
    public Integer getInt(String name);
    
    /**
     * Get integer parameter with default value
     * @param name - Parameter name
     * @param defaultValue - Default value if parameter not present
     * @returns Integer value or default
     */
    public Integer getInt(String name, Integer defaultValue);
    
    /**
     * Get boolean parameter
     * @param name - Parameter name
     * @returns Boolean value or null if not present
     */
    public Boolean getBoolean(String name);
    
    /**
     * Get boolean parameter with default value
     * @param name - Parameter name
     * @param defaultValue - Default value if parameter not present
     * @returns Boolean value or default
     */
    public Boolean getBoolean(String name, Boolean defaultValue);
    
    /**
     * Get double parameter
     * @param name - Parameter name
     * @returns Double value or null if not present or not a number
     */
    public Double getDouble(String name);
    
    /**
     * Get double parameter with default value
     * @param name - Parameter name
     * @param defaultValue - Default value if parameter not present
     * @returns Double value or default
     */
    public Double getDouble(String name, Double defaultValue);
    
    /**
     * Get float parameter
     * @param name - Parameter name
     * @returns Float value or null if not present or not a number
     */
    public Float getFloat(String name);
    
    /**
     * Get JSObject parameter
     * @param name - Parameter name
     * @returns JSObject value or null if not present
     */
    public JSObject getObject(String name);
    
    /**
     * Get JSArray parameter
     * @param name - Parameter name
     * @returns JSArray value or null if not present
     */
    public JSArray getArray(String name);
    
    /**
     * Check if parameter exists
     * @param name - Parameter name
     * @returns Boolean indicating if parameter is present
     * @deprecated Presence of a key should not be considered significant. Use typed accessors to check the value instead.
     */
    @Deprecated
    public boolean hasOption(String name);
}

@PluginMethod
public void configureSettings(PluginCall call) {
    // Get various parameter types
    String name = call.getString("name", "default");
    Integer timeout = call.getInt("timeout", 5000);
    Boolean enabled = call.getBoolean("enabled", true);
    Double threshold = call.getDouble("threshold", 0.5);
    
    // Get complex objects
    JSObject config = call.getObject("config");
    JSArray items = call.getArray("items");
    
    // Check if optional parameters exist
    if (call.hasOption("customData")) {
        JSObject customData = call.getObject("customData");
        // Process custom data
    }
    
    // Configure and respond
    configureWithParameters(name, timeout, enabled, threshold);
    call.resolve();
}

/**
 * Exception types for plugin operations
 */
public class PluginInvocationException extends Exception {
    /**
     * Create plugin invocation exception
     * @param message - Error message
     * @param cause - Underlying cause
     */
    public PluginInvocationException(String message, Throwable cause);
}

public class InvalidPluginMethodException extends Exception {
    /**
     * Create invalid plugin method exception
     * @param message - Error message
     */
    public InvalidPluginMethodException(String message);
}

/**
 * Error response patterns for PluginCall
 */
public class PluginCall {
    /**
     * Reject with structured error information
     * @param msg - Error message
     * @param code - Error code for client-side handling
     * @param ex - Exception that caused the error
     * @param data - Additional error data
     */
    public void reject(String msg, String code, Exception ex, JSObject data);
}

@PluginMethod
public void validateInput(PluginCall call) {
    try {
        String input = call.getString("input");
        if (input == null || input.isEmpty()) {
            JSObject errorData = new JSObject();
            errorData.put("field", "input");
            errorData.put("requirement", "non-empty string");
            
            call.reject("Input validation failed", "VALIDATION_ERROR", null, errorData);
            return;
        }
        
        // Process valid input
        JSObject result = processInput(input);
        call.resolve(result);
        
    } catch (SecurityException ex) {
        call.reject("Access denied", "PERMISSION_DENIED", ex, null);
    } catch (Exception ex) {
        call.reject("Processing failed", "INTERNAL_ERROR", ex, null);
    }
}