{"id":29285813,"url":"https://github.com/raghul-tech/filesentry","last_synced_at":"2025-07-05T23:11:23.080Z","repository":{"id":302495785,"uuid":"1012312092","full_name":"raghul-tech/FileSentry","owner":"raghul-tech","description":"FileSentry is a lightweight, cross-platform Java library for watching file changes in real time. It provides a simple API built on Java NIO WatchService, with built-in debouncing and event callbacks. Perfect for file watcher utilities, editors, live reload tools, and applications that require reliable file monitoring and notifications.","archived":false,"fork":false,"pushed_at":"2025-07-02T18:12:35.000Z","size":1,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-02T18:22:30.002Z","etag":null,"topics":["filesentry","filewatcher","java-nio","nio","watchservice"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raghul-tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T06:29:45.000Z","updated_at":"2025-07-02T18:16:16.000Z","dependencies_parsed_at":"2025-07-02T18:22:35.921Z","dependency_job_id":"18953a8c-2ecf-4bca-9a74-49bec502cf65","html_url":"https://github.com/raghul-tech/FileSentry","commit_stats":null,"previous_names":["raghul-tech/filesentry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raghul-tech/FileSentry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raghul-tech%2FFileSentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raghul-tech%2FFileSentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raghul-tech%2FFileSentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raghul-tech%2FFileSentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raghul-tech","download_url":"https://codeload.github.com/raghul-tech/FileSentry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raghul-tech%2FFileSentry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263819241,"owners_count":23516124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesentry","filewatcher","java-nio","nio","watchservice"],"created_at":"2025-07-05T23:11:21.298Z","updated_at":"2025-07-05T23:11:23.070Z","avatar_url":"https://github.com/raghul-tech.png","language":"Java","readme":"\u003ch1 align=\"center\"\u003e📂 FileSentry\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\n  \u003c!-- Maven Central --\u003e\n  \u003ca href=\"https://central.sonatype.com/artifact/io.github.raghul-tech/filesentry\"\u003e\n    \u003cimg src=\"https://img.shields.io/maven-central/v/io.github.raghul-tech/filesentry?style=for-the-badge\u0026color=blueviolet\" alt=\"Maven Central\" /\u003e\n  \u003c/a\u003e\n\n  \u003c!-- GitHub Release --\u003e\n  \u003ca href=\"https://github.com/raghul-tech/FileSentry/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/release/raghul-tech/FileSentry.svg?label=Latest%20Release\u0026style=for-the-badge\u0026color=success\" alt=\"GitHub Release\" /\u003e\n  \u003c/a\u003e\n\n  \u003c!-- Maven Build Workflow --\u003e\n  \u003ca href=\"https://github.com/raghul-tech/FileSentry/actions/workflows/maven.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/raghul-tech/FileSentry/maven.yml?label=Build\u0026style=for-the-badge\u0026color=brightgreen\" alt=\"Maven Build Status\" /\u003e\n  \u003c/a\u003e\n\n  \u003c!-- CodeQL Analysis --\u003e\n  \u003ca href=\"https://github.com/raghul-tech/FileSentry/actions/workflows/codeql.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/raghul-tech/FileSentry/codeql.yml?label=CodeQL\u0026logo=github\u0026style=for-the-badge\u0026color=informational\" alt=\"CodeQL Status\" /\u003e\n  \u003c/a\u003e\n\n  \u003c!-- Javadoc --\u003e\n  \u003ca href=\"https://javadoc.io/doc/io.github.raghul-tech/filesentry/1.0.0\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Javadoc-1.0.0-blue?style=for-the-badge\u0026logo=java\" alt=\"Javadoc (1.0.0)\" /\u003e\n  \u003c/a\u003e\n\n  \u003c!-- Support --\u003e\n  \u003ca href=\"https://buymeacoffee.com/raghultech\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-orange?style=for-the-badge\u0026logo=buy-me-a-coffee\" alt=\"Buy Me A Coffee\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n---\n\n# About  FileSentry\n\n**FileSentry** is a lightweight, cross-platform Java library for monitoring file changes in real time.  \nIt provides a simple API built on Java NIO’s `WatchService`, with built-in debouncing and event callbacks.\n\nSupports **Windows**, **Linux**, and **macOS**.\n\n---\n\n## ✨ Features\n\n✅ Watch any file for changes in real time  \n✅ Get notified when a file is modified  \n✅ Easy to integrate into Swing, JavaFX, or command-line apps  \n✅ Minimal dependencies (pure Java)  \n✅ Automatically stops when you’re done  \n✅ Suitable for:\n\n- Text editors (live reload)\n- Log viewers\n- Developer tools\n- Custom synchronization utilities\n\n---\n\n## 🚀 Getting Started\n\n### 📦 Installation\n\n**Maven:**\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.raghul-tech\u003c/groupId\u003e\n  \u003cartifactId\u003efilesentry\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n---\n\n## 💡 Example Usage\nBelow is a complete example that:\n\n- Watches sample.txt\n\n- Prints a message when the file changes\n\n- Automatically stops when the program ends\n\n```java\nimport io.github.raghultech.filesentry.FileWatcher;\n\nimport java.io.File;\nimport java.lang.ref.WeakReference;\n\n/**\n * Example of using FileSentry to monitor file changes.\n */\npublic class ExampleFileWatcher {\n\n    private FileWatcher fileWatcher;\n    private transient WeakReference\u003cThread\u003e fileWatcherThread;\n    private File currentFile = new File(\"sample.txt\"); \n\n    public void watchFileForChanges() {\n        stopFileWatcher(); // Stop previous watcher if running\n\n        if (currentFile == null || !currentFile.exists()) {\n            System.out.println(\"File not found: \" + currentFile.getAbsolutePath());\n            return;\n        }\n\n        fileWatcher = new FileWatcher(currentFile);\n        \n        // 1️⃣ Simple modify/create/delete awareness\n        fileWatcher.setFileModifyListener(changed -\u003e {\n            if (changed) {\n                System.out.println(\" Simple: File changed.\");\n                // your reload logic \n            }\n        });\n\n        // 2️⃣ State listener: existence\n        fileWatcher.setFileStateListener(exists -\u003e {\n            if (exists) {\n                System.out.println(\" State: File exists (create/modify).\");\n            } else {\n                System.out.println(\" State: File deleted.\");\n            }\n        });\n\n        // 3️⃣ Detailed change type\n        fileWatcher.setFileChangeListener(type -\u003e {\n            switch (type) {\n                case CREATED -\u003e System.out.println(\" Detailed: File CREATED.\");\n                case MODIFIED -\u003e System.out.println(\"️ Detailed: File MODIFIED.\");\n                case DELETED -\u003e System.out.println(\" Detailed: File DELETED.\");\n            }\n        });\n\n        Thread watcherThread = new Thread(fileWatcher, \"FileWatcher-Thread\");\n        watcherThread.setDaemon(true); // Allow JVM to exit if only daemon threads remain\n        fileWatcherThread = new WeakReference\u003c\u003e(watcherThread);\n        watcherThread.start();\n    }\n\n    public void stopFileWatcher() {\n        if (fileWatcher != null) {\n            fileWatcher.stopWatching();\n        }\n\n        Thread watcherThread = fileWatcherThread != null ? fileWatcherThread.get() : null;\n        if (watcherThread != null \u0026\u0026 watcherThread.isAlive()) {\n            watcherThread.interrupt();\n            try {\n                watcherThread.join(1000); // Wait for thread to exit\n            } catch (InterruptedException e) {\n                Thread.currentThread().interrupt();\n            }\n        }\n    }\n\n    public static void main(String[] args) {\n        ExampleFileWatcher watcher = new ExampleFileWatcher();\n        watcher.watchFileForChanges();\n\n        // Keep the main thread alive for demonstration\n        try {\n        \t System.out.println(\" Watching file for 60 seconds...\");\n            Thread.sleep(60000); // Run for 60 seconds\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n        }\n\n        watcher.stopFileWatcher();\n         System.out.println(\" Stopped watching.\");\n    }\n}\n\n```\n\n---\n\n## 📝 Clarify **listener behaviors** in the Features section\n\n* Just a short note describing exactly what each listener returns, so no confusion (since you had that question earlier):\n\n\u003e 📝 **Note about Listeners**\n\u003e\n\u003e - `FileModifyListener`: always `true` on any event (create, modify, delete)\n\u003e - `FileStateListener`: `true` if it is modified or created or file currently exists, `false` if deleted\n\u003e - `FileChangeListener`: returns a `FileChangeType` enum (`CREATED`, `MODIFIED`, `DELETED`)\n\n---\n\n## 🖥️ How to Run\n### ✅ Using Command Line\n1. Compile:\n```bash\njavac -cp filesentry-1.0.0.jar ExampleFileWatcher.java\n```\n\n2.Run:\n```bash\njava -cp .;filesentry-1.0.0.jar ExampleFileWatcher\n```\n\n\u003e(On Linux or mac, replace ; with :)\n\n---\n\n## 🧭 Where to Use\n- Command-line tools: watch logs or configuration files.\n\n- GUI applications: detect when a file changes and prompt the user to reload.\n\n- Development tools: implement live-reload behavior.\n\n- Scripting: monitor scripts or data files.\n\n---\n\n## 🛠️ Why Use FileSentry?\n- Zero configuration: Just point it to a file.\n\n- Cross-platform: Works on Windows, Linux, macOS.\n\n- Small footprint: No heavy dependencies.\n\n- Easy to stop: Clean shutdown with stopWatching().\n\n---\n\n## ✅ Good to Know\n- FileSentry uses Java NIO’s WatchService internally.\n\n- To avoid memory leaks, always stop your watcher when you no longer need it.\n\n- You can integrate it into larger apps (editors, tools) by starting/stopping in your app lifecycle hooks.\n\n---\n\n## 🆕 Changelog:\n\n* View all releases on the [Releases Page.](https://github.com/raghul-tech/FileSentry/releases)\n* For a detailed log of all changes, refer to the [CHANGELOG.md](CHANGELOG.md) file.\n\n---\n\n## 🤝 Contributing\n* We welcome contributions of all kinds:\n\n   * 🛠️ Bug fixes\n\n   * 🌟 Feature suggestions\n\n   * 📚 Documentation improvements\n\n   * 🧪 More usage examples\n\n\u003e Please check the [Contributing Guide](CONTRIBUTING.md) before starting.\n\n---\n\n## 🐞 Report a Bug\n   * If you've encountered a bug, please report it by clicking the link below. \n   \tThis will guide you through the bug-reporting process:\n   \t➡️ [Click here to report a bug](https://github.com/raghul-tech/FileSentry/issues)\n \n---\n\n## 📄 License\n- This project is licensed under the [MIT License](LICENSE).\n\n---\n\n## 📬 Contact\nEmail: [raghultech.app@gmail.com](mailto:raghultech.app@gmail.com)\n\n---\n\n## ☕ Support\n\u003e If you find this project useful, consider buying me a coffee!\n\n\u003ca href=\"https://buymeacoffee.com/raghultech\"\u003e \u003cimg src=\"https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-orange.svg?style=flat-square\" alt=\"Buy Me A Coffee\" /\u003e \u003c/a\u003e \n","funding_links":["https://buymeacoffee.com/raghultech"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraghul-tech%2Ffilesentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraghul-tech%2Ffilesentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraghul-tech%2Ffilesentry/lists"}