{"id":23156246,"url":"https://github.com/bsommerfeld/jshepherd","last_synced_at":"2026-01-08T20:15:34.109Z","repository":{"id":263915444,"uuid":"891783195","full_name":"bsommerfeld/jshepherd","owner":"bsommerfeld","description":"Annotation Based Java Config Management Library Supporting JSON, TOML, YAML and Properties.","archived":false,"fork":false,"pushed_at":"2025-08-10T01:24:33.000Z","size":201,"stargazers_count":22,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-10T03:04:59.003Z","etag":null,"topics":["annotation","config","configuration","java","json","library","management","properties","toml","yaml","yml"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bsommerfeld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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":"2024-11-21T00:14:57.000Z","updated_at":"2025-08-10T01:23:54.000Z","dependencies_parsed_at":"2025-03-08T02:23:20.236Z","dependency_job_id":"bf855b2c-e5cf-4043-b1d9-f793acab819d","html_url":"https://github.com/bsommerfeld/jshepherd","commit_stats":null,"previous_names":["metaphoriker/coma","metaphoriker/jshepherd","bsommerfeld/jshepherd"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/bsommerfeld/jshepherd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsommerfeld%2Fjshepherd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsommerfeld%2Fjshepherd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsommerfeld%2Fjshepherd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsommerfeld%2Fjshepherd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsommerfeld","download_url":"https://codeload.github.com/bsommerfeld/jshepherd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsommerfeld%2Fjshepherd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270922510,"owners_count":24668567,"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","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["annotation","config","configuration","java","json","library","management","properties","toml","yaml","yml"],"created_at":"2024-12-17T21:12:57.654Z","updated_at":"2026-01-08T20:15:34.103Z","avatar_url":"https://github.com/bsommerfeld.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JShepherd\r\n\r\n[![Maven Central](https://img.shields.io/maven-central/v/de.bsommerfeld.jshepherd/core?label=Maven%20Central)](https://central.sonatype.com/artifact/de.bsommerfeld.jshepherd/core)\r\n\r\nJShepherd is an annotation-based configuration management library for Java that supports modern hierarchical formats (YAML, JSON, TOML) with automatic format detection based on file extensions. It intelligently merges configuration changes — adding new fields and removing obsolete ones without overwriting user-modified values.\r\n\r\n## Key Features\r\n\r\n* **🎯 Automatic Format Detection** — File extension determines persistence format\r\n* **📝 Annotation-Driven** — Declarative configuration with `@Key`, `@Comment`, `@Section`\r\n* **🔄 Smart Config Merging** — Automatically adds new keys and removes obsolete ones without losing user-modified values\r\n* **💾 Live Reload \u0026 Persistence** — Call `config.reload()` or `config.save()` at any time\r\n* **📚 Documentation Generation** — Auto-generated `.md` docs for formats without comment support (JSON)\r\n* **🔧 Type Safety** — Compile-time checking with self-referential generics\r\n* **⚡ Zero Configuration** — Sensible defaults out of the box\r\n* **🧩 Modular** — Include only the format modules you need\r\n\r\n## Installation\r\n\r\nJShepherd is available on **Maven Central**. Check the badge above for the latest version.\r\n\r\n### Maven\r\n\r\n```xml\r\n\u003cdependencies\u003e\r\n    \u003c!-- Core module (required) --\u003e\r\n    \u003cdependency\u003e\r\n        \u003cgroupId\u003ede.bsommerfeld.jshepherd\u003c/groupId\u003e\r\n        \u003cartifactId\u003ecore\u003c/artifactId\u003e\r\n        \u003cversion\u003e4.0.1\u003c/version\u003e\r\n    \u003c/dependency\u003e\r\n\r\n    \u003c!-- Format-specific modules (include only what you need) --\u003e\r\n    \u003cdependency\u003e\r\n        \u003cgroupId\u003ede.bsommerfeld.jshepherd\u003c/groupId\u003e\r\n        \u003cartifactId\u003eyaml\u003c/artifactId\u003e\r\n        \u003cversion\u003e4.0.1\u003c/version\u003e\r\n    \u003c/dependency\u003e\r\n    \u003cdependency\u003e\r\n        \u003cgroupId\u003ede.bsommerfeld.jshepherd\u003c/groupId\u003e\r\n        \u003cartifactId\u003ejson\u003c/artifactId\u003e\r\n        \u003cversion\u003e4.0.1\u003c/version\u003e\r\n    \u003c/dependency\u003e\r\n    \u003cdependency\u003e\r\n        \u003cgroupId\u003ede.bsommerfeld.jshepherd\u003c/groupId\u003e\r\n        \u003cartifactId\u003etoml\u003c/artifactId\u003e\r\n        \u003cversion\u003e4.0.1\u003c/version\u003e\r\n    \u003c/dependency\u003e\r\n\u003c/dependencies\u003e\r\n```\r\n\r\n### Gradle\r\n\r\n```groovy\r\ndependencies {\r\n    // Core module (required)\r\n    implementation 'de.bsommerfeld.jshepherd:core:4.0.1'\r\n\r\n    // Format-specific modules (include only what you need)\r\n    implementation 'de.bsommerfeld.jshepherd:yaml:4.0.1'\r\n    implementation 'de.bsommerfeld.jshepherd:json:4.0.1'\r\n    implementation 'de.bsommerfeld.jshepherd:toml:4.0.1'\r\n}\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Define Your Configuration\r\n\r\nExtend `ConfigurablePojo\u003cYourClassName\u003e` — the self-reference enables type-safe `save()` and `reload()`:\r\n\r\n```java\r\n@Comment(\"Application Configuration\")\r\npublic class AppConfig extends ConfigurablePojo\u003cAppConfig\u003e {\r\n\r\n    @Key(\"app-name\")\r\n    @Comment(\"The application name\")\r\n    private String appName = \"MyApp\";\r\n\r\n    @Key(\"server-port\")\r\n    @Comment(\"Server port number\")\r\n    private int serverPort = 8080;\r\n\r\n    @Key(\"debug-mode\")\r\n    @Comment(\"Enable debug logging\")\r\n    private boolean debugMode = false;\r\n\r\n    public AppConfig() {}\r\n\r\n    @PostInject\r\n    private void validate() {\r\n        if (serverPort \u003c 0) throw new IllegalArgumentException(\"Port cannot be negative\");\r\n    }\r\n\r\n    // Getters and setters...\r\n    public String getAppName() { return appName; }\r\n    public void setAppName(String appName) { this.appName = appName; }\r\n    public int getServerPort() { return serverPort; }\r\n    public void setServerPort(int serverPort) { this.serverPort = serverPort; }\r\n}\r\n```\r\n\r\n### 2. Load, Use, and Persist\r\n\r\n```java\r\nPath configFile = Paths.get(\"config.yaml\");  // or .json, .toml\r\n\r\n// Fluent Builder API (recommended)\r\nAppConfig config = ConfigurationLoader.from(configFile)\r\n    .withComments()      // Enable comment generation (default)\r\n    .load(AppConfig::new);\r\n\r\n// Or use the static factory method\r\nAppConfig config = ConfigurationLoader.load(configFile, AppConfig::new);\r\n\r\nSystem.out.println(\"App: \" + config.getAppName());\r\n\r\n// Modify and persist\r\nconfig.setServerPort(9090);\r\nconfig.save();\r\n\r\n// Reload from file\r\nconfig.reload();\r\n```\r\n\r\n## Supported Formats\r\n\r\n| Format   | Extensions      | Comments Support     | Notes                          |\r\n|----------|-----------------|----------------------|--------------------------------|\r\n| **YAML** | `.yaml`, `.yml` | ✅ Inline comments   | Full native support            |\r\n| **TOML** | `.toml`         | ✅ Inline comments   | Full native support + sections |\r\n| **JSON** | `.json`         | ❌ No native support | Generates `.md` documentation  |\r\n\r\n## Annotations\r\n\r\n| Annotation                   | Target       | Purpose                           |\r\n|------------------------------|--------------|-----------------------------------|\r\n| `@Key(\"name\")`               | Field        | Custom key name in config file    |\r\n| `@Comment(\"text\")`           | Type, Field  | Adds comments (header or inline)  |\r\n| `@PostInject`                | Method       | Called after configuration loaded |\r\n| `@Section(\"name\")`           | Field        | Nested POJO as section (all formats) |\r\n\r\n## Nested Sections with `@Section`\r\n\r\nThe `@Section` annotation works across all formats (YAML, TOML, JSON) to create nested configuration structures:\r\n\r\n```java\r\n@Comment(\"Server Configuration\")\r\npublic class ServerConfig extends ConfigurablePojo\u003cServerConfig\u003e {\r\n\r\n    @Key(\"host\")\r\n    private String host = \"localhost\";\r\n\r\n    @Comment(\"Database connection settings\")\r\n    @Section(\"database\")\r\n    private DatabaseSettings database = new DatabaseSettings();\r\n\r\n    @Comment(\"Cache tuning\")\r\n    @Section(\"cache\")\r\n    private CacheSettings cache = new CacheSettings();\r\n}\r\n\r\n// Section POJOs don't extend ConfigurablePojo\r\npublic class DatabaseSettings {\r\n    @Key(\"url\")\r\n    @Comment(\"JDBC connection URL\")\r\n    private String url = \"jdbc:postgresql://localhost/mydb\";\r\n    \r\n    @Key(\"pool-size\")\r\n    private int poolSize = 10;\r\n}\r\n```\r\n\r\n**YAML Output:**\r\n\r\n```yaml\r\n# Server Configuration\r\n\r\nhost: localhost\r\n\r\n# Database connection settings\r\ndatabase:\r\n  # JDBC connection URL\r\n  url: jdbc:postgresql://localhost/mydb\r\n  pool-size: 10\r\n\r\n# Cache tuning\r\ncache:\r\n  max-entries: 1000\r\n  ttl-seconds: 300\r\n```\r\n\r\n**TOML Output:**\r\n\r\n```toml\r\n# Server Configuration\r\n\r\nhost = \"localhost\"\r\n\r\n# Database connection settings\r\n[database]\r\n# JDBC connection URL\r\nurl = \"jdbc:postgresql://localhost/mydb\"\r\npool-size = 10\r\n\r\n# Cache tuning\r\n[cache]\r\nmax-entries = 1000\r\nttl-seconds = 300\r\n```\r\n\r\n**JSON Output:**\r\n\r\n```json\r\n{\r\n  \"host\": \"localhost\",\r\n  \"database\": {\r\n    \"url\": \"jdbc:postgresql://localhost/mydb\",\r\n    \"pool-size\": 10\r\n  },\r\n  \"cache\": {\r\n    \"max-entries\": 1000,\r\n    \"ttl-seconds\": 300\r\n  }\r\n}\r\n```\r\n\r\n\u003e **Note:** `@Key` fields declared after `@Section` fields do NOT belong to the section — they remain at root level. JSON does not support comments; when `withComments()` is enabled, a `config-documentation.md` file is generated alongside the JSON file.\r\n\r\n---\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsommerfeld%2Fjshepherd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsommerfeld%2Fjshepherd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsommerfeld%2Fjshepherd/lists"}