Configuration and Utilities

/**
 * Manages Capacitor application configuration
 * Loads and provides access to capacitor.config.json settings
 */
public class CapConfig {
    
    /**
     * Load default configuration from application context
     * @param context - Android context for loading config
     * @returns CapConfig instance with loaded configuration
     */
    public static CapConfig loadDefault(Context context);
    
    /**
     * Load configuration from specific assets path
     * @param context - Android context
     * @param assetPath - Path to configuration file in assets
     * @returns CapConfig instance with loaded configuration
     */
    public static CapConfig loadFromAssets(Context context, String assetPath);
    
    /**
     * Get plugin-specific configuration
     * @param pluginName - Name of the plugin
     * @returns JSONObject with plugin configuration or null if not found
     */
    public JSONObject getPluginConfiguration(String pluginName);
    
    /**
     * Get string configuration value
     * @param key - Configuration key
     * @param defaultValue - Default value if key not found
     * @returns String value or default
     */
    public String getString(String key, String defaultValue);
    
    /**
     * Get boolean configuration value
     * @param key - Configuration key
     * @param defaultValue - Default value if key not found
     * @returns Boolean value or default
     */
    public boolean getBoolean(String key, boolean defaultValue);
    
    /**
     * Get integer configuration value
     * @param key - Configuration key
     * @param defaultValue - Default value if key not found
     * @returns Integer value or default
     */
    public int getInt(String key, int defaultValue);
    
    /**
     * Get server URL for the application
     * @returns String URL or null if not configured
     */
    public String getServerUrl();
    
    /**
     * Check if live reload is enabled
     * @returns Boolean indicating if live reload is active
     */
    public boolean isLiveReloadEnabled();
    
    /**
     * Get logging configuration
     * @returns JSONObject with logging settings
     */
    public JSONObject getLoggingConfig();
    
    /**
     * Get all configuration as JSONObject
     * @returns JSONObject containing all configuration
     */
    public JSONObject toJSONObject();
}

@CapacitorPlugin(name = "MyPlugin")
public class MyPlugin extends Plugin {
    
    @Override
    public void load() {
        CapConfig config = CapConfig.loadDefault(getContext());
        
        // Get plugin-specific configuration
        JSONObject pluginConfig = config.getPluginConfiguration("MyPlugin");
        if (pluginConfig != null) {
            String apiKey = pluginConfig.optString("apiKey", "");
            boolean enableDebug = pluginConfig.optBoolean("enableDebug", false);
            configurePlugin(apiKey, enableDebug);
        }
        
        // Get global configuration
        String serverUrl = config.getServerUrl();
        boolean liveReload = config.isLiveReloadEnabled();
        
        if (liveReload) {
            enableDevelopmentMode();
        }
    }
}

/**
 * Logging utilities for Capacitor plugins and runtime
 * Provides consistent logging with different levels
 */
public class Logger {
    
    /**
     * Log debug message
     * @param msg - Debug message string
     */
    public static void debug(String msg);
    
    /**
     * Log debug message with tag
     * @param tag - Log tag for filtering
     * @param msg - Debug message string
     */
    public static void debug(String tag, String msg);
    
    /**
     * Log info message
     * @param msg - Info message string
     */
    public static void info(String msg);
    
    /**
     * Log info message with tag
     * @param tag - Log tag for filtering
     * @param msg - Info message string
     */
    public static void info(String tag, String msg);
    
    /**
     * Log warning message
     * @param msg - Warning message string
     */
    public static void warn(String msg);
    
    /**
     * Log warning message with tag
     * @param tag - Log tag for filtering
     * @param msg - Warning message string
     */
    public static void warn(String tag, String msg);
    
    /**
     * Log error message
     * @param msg - Error message string
     */
    public static void error(String msg);
    
    /**
     * Log error message with tag
     * @param tag - Log tag for filtering
     * @param msg - Error message string
     */
    public static void error(String tag, String msg);
    
    /**
     * Log error message with exception
     * @param msg - Error message string
     * @param ex - Exception to log
     */
    public static void error(String msg, Exception ex);
    
    /**
     * Log error message with tag and exception
     * @param tag - Log tag for filtering
     * @param msg - Error message string
     * @param ex - Exception to log
     */
    public static void error(String tag, String msg, Exception ex);
    
    /**
     * Set logging level for filtering
     * @param level - Minimum log level to display
     */
    public static void setLogLevel(int level);
    
    /**
     * Check if debug logging is enabled
     * @returns Boolean indicating if debug logs will be shown
     */
    public static boolean isDebuggable();
}

@CapacitorPlugin(name = "FileManager")
public class FileManagerPlugin extends Plugin {
    
    private static final String TAG = "FileManager";
    
    @PluginMethod
    public void readFile(PluginCall call) {
        String path = call.getString("path");
        Logger.debug(TAG, "Reading file: " + path);
        
        try {
            String content = readFileContent(path);
            Logger.info(TAG, "File read successfully: " + path);
            
            JSObject result = new JSObject();
            result.put("content", content);
            call.resolve(result);
            
        } catch (FileNotFoundException ex) {
            Logger.warn(TAG, "File not found: " + path);
            call.reject("File not found", "FILE_NOT_FOUND", ex, null);
        } catch (Exception ex) {
            Logger.error(TAG, "Failed to read file: " + path, ex);
            call.reject("Read failed", "READ_ERROR", ex, null);
        }
    }
}

/**
 * Enum representing Android permission states
 */
public enum PermissionState {
    /** Permission has been granted by the user */
    GRANTED,
    /** Permission has been denied by the user */
    DENIED,
    /** Permission requires user prompt (first time request) */
    PROMPT,
    /** Permission requires prompt with rationale explanation */
    PROMPT_WITH_RATIONALE
}

/**
 * Utility class for permission operations
 */
public class PermissionHelper {
    
    /**
     * Check current state of a permission
     * @param context - Android context
     * @param permission - Permission string to check
     * @returns PermissionState enum value
     */
    public static PermissionState checkPermission(Context context, String permission);
    
    /**
     * Check if permission requires rationale explanation
     * @param activity - Activity context
     * @param permission - Permission string to check
     * @returns Boolean indicating if rationale should be shown
     */
    public static boolean shouldShowRequestPermissionRationale(Activity activity, String permission);
    
    /**
     * Check multiple permissions at once
     * @param context - Android context
     * @param permissions - Array of permission strings
     * @returns Map of permission names to PermissionState values
     */
    public static Map<String, PermissionState> checkPermissions(Context context, String[] permissions);
    
    /**
     * Get all granted permissions from a set
     * @param context - Android context
     * @param permissions - Array of permission strings to check
     * @returns Array of granted permission strings
     */
    public static String[] getGrantedPermissions(Context context, String[] permissions);
    
    /**
     * Get all denied permissions from a set
     * @param context - Android context
     * @param permissions - Array of permission strings to check
     * @returns Array of denied permission strings
     */
    public static String[] getDeniedPermissions(Context context, String[] permissions);
}

@CapacitorPlugin(
    name = "LocationPlugin",
    permissions = {
        @Permission(strings = {Manifest.permission.ACCESS_FINE_LOCATION}, alias = "location")
    }
)
public class LocationPlugin extends Plugin {
    
    @PluginMethod
    public void getCurrentLocation(PluginCall call) {
        String[] permissions = {Manifest.permission.ACCESS_FINE_LOCATION};
        PermissionState state = PermissionHelper.checkPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION);
        
        switch (state) {
            case GRANTED:
                getLocation(call);
                break;
            case DENIED:
            case PROMPT:
                requestPermissionForAlias("location", call, "locationPermissionCallback");
                break;
            case PROMPT_WITH_RATIONALE:
                // Show rationale then request
                showLocationRationale(call);
                break;
        }
    }
    
    @PermissionCallback
    private void locationPermissionCallback(PluginCall call) {
        if (PermissionHelper.checkPermission(getContext(), Manifest.permission.ACCESS_FINE_LOCATION) == PermissionState.GRANTED) {
            getLocation(call);
        } else {
            call.reject("Location permission required");
        }
    }
}

/**
 * File operation utilities for Capacitor plugins
 */
public class FileUtils {
    
    /**
     * Get application files directory
     * @param context - Android context
     * @returns File pointing to app files directory
     */
    public static File getFilesDir(Context context);
    
    /**
     * Get application cache directory
     * @param context - Android context
     * @returns File pointing to app cache directory
     */
    public static File getCacheDir(Context context);
    
    /**
     * Get external files directory
     * @param context - Android context
     * @returns File pointing to external files directory or null if not available
     */
    public static File getExternalFilesDir(Context context);
    
    /**
     * Convert URI to file path
     * @param context - Android context
     * @param uri - URI to convert
     * @returns String file path or null if conversion fails
     */
    public static String getFilePathFromUri(Context context, Uri uri);
    
    /**
     * Get file extension from path
     * @param path - File path string
     * @returns String file extension (without dot) or empty string
     */
    public static String getFileExtension(String path);
    
    /**
     * Get MIME type for file
     * @param path - File path string
     * @returns String MIME type or "application/octet-stream" for unknown
     */
    public static String getMimeType(String path);
    
    /**
     * Read file as string
     * @param file - File to read
     * @returns String contents of file
     * @throws IOException if read fails
     */
    public static String readFileAsString(File file) throws IOException;
    
    /**
     * Write string to file
     * @param file - File to write to
     * @param content - String content to write
     * @throws IOException if write fails
     */
    public static void writeStringToFile(File file, String content) throws IOException;
    
    /**
     * Copy file to another location
     * @param source - Source file
     * @param destination - Destination file
     * @throws IOException if copy fails
     */
    public static void copyFile(File source, File destination) throws IOException;
    
    /**
     * Check if path is valid and safe
     * @param path - Path string to validate
     * @returns Boolean indicating if path is safe to use
     */
    public static boolean isValidPath(String path);
}

@CapacitorPlugin(name = "FileHandler")
public class FileHandlerPlugin extends Plugin {
    
    @PluginMethod
    public void saveFile(PluginCall call) {
        String fileName = call.getString("fileName");
        String content = call.getString("content");
        
        if (!FileUtils.isValidPath(fileName)) {
            call.reject("Invalid file name");
            return;
        }
        
        try {
            File filesDir = FileUtils.getFilesDir(getContext());
            File targetFile = new File(filesDir, fileName);
            
            FileUtils.writeStringToFile(targetFile, content);
            
            JSObject result = new JSObject();
            result.put("path", targetFile.getAbsolutePath());
            result.put("size", targetFile.length());
            result.put("mimeType", FileUtils.getMimeType(fileName));
            
            call.resolve(result);
            
        } catch (IOException ex) {
            Logger.error("FileHandler", "Failed to save file", ex);
            call.reject("Save failed", "WRITE_ERROR", ex, null);
        }
    }
    
    @PluginMethod
    public void readFile(PluginCall call) {
        String fileName = call.getString("fileName");
        
        try {
            File filesDir = FileUtils.getFilesDir(getContext());
            File sourceFile = new File(filesDir, fileName);
            
            if (!sourceFile.exists()) {
                call.reject("File not found", "FILE_NOT_FOUND");
                return;
            }
            
            String content = FileUtils.readFileAsString(sourceFile);
            
            JSObject result = new JSObject();
            result.put("content", content);
            result.put("size", sourceFile.length());
            result.put("extension", FileUtils.getFileExtension(fileName));
            
            call.resolve(result);
            
        } catch (IOException ex) {
            Logger.error("FileHandler", "Failed to read file", ex);
            call.reject("Read failed", "READ_ERROR", ex, null);
        }
    }
}

/**
 * JSON utility methods
 */
public class JSONUtils {
    /**
     * Convert Map to JSONObject safely
     * @param map - Map to convert
     * @returns JSONObject or empty object if conversion fails
     */
    public static JSONObject mapToJSONObject(Map<String, Object> map);
    
    /**
     * Convert JSONObject to Map
     * @param obj - JSONObject to convert
     * @returns Map<String, Object> with all values
     */
    public static Map<String, Object> jsonObjectToMap(JSONObject obj);
}

/**
 * Internal utility methods for Capacitor runtime
 */
public class InternalUtils {
    /**
     * Check if running on main thread
     * @returns Boolean indicating if on main/UI thread
     */
    public static boolean isMainThread();
    
    /**
     * Get application info from context
     * @param context - Android context
     * @returns ApplicationInfo instance
     */
    public static ApplicationInfo getApplicationInfo(Context context);
}

/**
 * Web color utility for parsing CSS color values
 */
public class WebColor {
    /**
     * Parse CSS color string to Android color int
     * @param colorString - CSS color string (hex, rgb, etc.)
     * @returns Integer color value or null if parse fails
     */
    public static Integer parseColor(String colorString);
}