https://github.com/bsommerfeld/jshepherd
Annotation Based Java Config Management Library Supporting JSON, TOML, YAML and Properties.
https://github.com/bsommerfeld/jshepherd
annotation config configuration java json library management properties toml yaml yml
Last synced: about 2 months ago
JSON representation
Annotation Based Java Config Management Library Supporting JSON, TOML, YAML and Properties.
- Host: GitHub
- URL: https://github.com/bsommerfeld/jshepherd
- Owner: bsommerfeld
- Created: 2024-11-21T00:14:57.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-08-10T01:24:33.000Z (2 months ago)
- Last Synced: 2025-08-10T03:04:59.003Z (2 months ago)
- Topics: annotation, config, configuration, java, json, library, management, properties, toml, yaml, yml
- Language: Java
- Homepage:
- Size: 196 KB
- Stars: 22
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JShepherd
JShepherd is an annotation based automatic configuration management library for Java that supports multiple formats (
YAML, JSON, TOML, Properties) with automatic format detection based on file extensions.
## Installation
JShepherd is now modular. You need to include the core module and any format-specific modules you want to use.
### Maven
```xml
jitpack.io
https://jitpack.io
com.github.bsommerfeld.jshepherd
core
VERSION
com.github.bsommerfeld.jshepherd
json
VERSION
com.github.bsommerfeld.jshepherd
yaml
VERSION
com.github.bsommerfeld.jshepherd
toml
VERSION
com.github.bsommerfeld.jshepherd
properties
VERSION
```
### Gradle
```groovy
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
dependencies {
// Core module (required)
implementation 'com.github.bsommerfeld.jshepherd:core:VERSION'
// Format-specific modules (include only what you need)
implementation 'com.github.bsommerfeld.jshepherd:json:VERSION'
implementation 'com.github.bsommerfeld.jshepherd:yaml:VERSION'
implementation 'com.github.bsommerfeld.jshepherd:toml:VERSION'
implementation 'com.github.bsommerfeld.jshepherd:properties:VERSION'
}
```
Replace `VERSION` with the latest version of JShepherd.
## Quick Start
Define your configuration as a POJO extending `ConfigurablePojo`:
```java
@Comment("My Application Configuration")
public class AppConfig extends ConfigurablePojo {
@Key("app-name")
@Comment("The application name")
private String appName = "MyApp";
@Key("server-port")
@Comment("Server port number")
private int serverPort = 8080;
@Key("debug-mode")
@Comment("Enable debug logging")
private boolean debugMode = false;
// Constructor and getters/setters...
public AppConfig() {
}
@PostInject
private void validateConfigValues() {
if (serverPort < 0)
throw new IllegalArgumentException("Port cannot be negative.");
}
public String getAppName() {
return appName;
}
public void setAppName(String appName) {
this.appName = appName;
}
// ... other getters/setters
}
```
Load and use your configuration:
```java
public class App {
public static void main(String[] args) {
// File extension determines format automatically
Path configFile = Paths.get("config.yaml"); // or .json, .toml, .properties
AppConfig config = ConfigurationLoader.load(configFile, AppConfig::new);
System.out.println("App: " + config.getAppName());
System.out.println("Port: " + config.getServerPort());
// Modify and save
config.setServerPort(9090);
config.save();
// Reload from file
config.reload();
}
}
```
## Supported Formats
| Format | Extensions | Comments Support | Documentation |
|----------------|-----------------|---------------------|---------------------|
| **YAML** | `.yaml`, `.yml` | ✅ Inline comments | Native support |
| **JSON** | `.json` | ❌ No native support | Separate `.md` file |
| **TOML** | `.toml` | ✅ Inline comments | Native support |
| **Properties** | `.properties` | ✅ Inline comments | Native support |
### JSON Documentation Files
When using JSON format with comments enabled, JShepherd automatically creates a companion documentation file:
```java
// config.json + config-documentation.md will be created
AppConfig config = ConfigurationLoader.load(
Paths.get("config.json"),
AppConfig::new,
true // Enable documentation generation
);
```
## Key Features
* **🎯 Automatic Format Detection**: File extension determines the persistence format
* **📝 Annotation-Driven**: Use `@Key`, `@Comment`, and `@CommentSection` for structure and documentation
* **🔄 Live Reload**: Call `config.reload()` to update from external file changes
* **💾 Simple Persistence**: Call `config.save()` to write changes back to file
* **📚 Documentation Generation**: Automatic documentation files for formats without native comment support
* **🔧 Type Safety**: Full compile-time type checking with self-referential generics
* **⚡ Zero Configuration**: Works out of the box with sensible defaults
* **🧩 Modular Structure**: Include only the format modules you need
## Annotations
| Annotation | Purpose | Example |
|------------------------------|----------------------------------|------------------------------------|
| `@Key("custom-name")` | Custom field name in config file | Maps `serverPort` → `server-port` |
| `@Comment("Description")` | Field documentation | Adds comments above the field |
| `@CommentSection("Section")` | Group related fields | Creates section headers |
| `@PostInject` | Post-load initialization | Method called after config loading |
## Example Output
**YAML** (`config.yaml`):
```yaml
# My Application Configuration
# The application name
app-name: MyApp
# Server port number
server-port: 9090
# Enable debug logging
debug-mode: false
```
**JSON** (`config.json` + `config-documentation.md`):
```json
{
"app-name": "MyApp",
"server-port": 9090,
"debug-mode": false
}
```
For detailed technical documentation, see: [Technical Documentation (German)](.docs/TECHNISCHE_DOKUMENTATION_de_V3.md)
*AI tools were used to assist in the development of this library.*