🔮 Obsidian Framework

A modern, minimalist, and robust Java 21+ framework.

Focused on developer ergonomics, offering advanced reflection, flexible configuration, concurrency abstractions, and high-quality utility APIs.

---

📖 Available Languages: English | Português Brasileiro | Deutsch | Español

📌 Overview

Obsidian is a collection of elegant, independent, and highly specialized Java modules that simplify backend development. Each module is designed to solve specific problems with a fluent, intuitive API, minimizing boilerplate and maximizing type safety.

Built for Java 21, Obsidian leverages modern language features to deliver a seamless developer experience.

✨ Core Modules

⚙️ Obsidian Configuration

A minimalist, annotation-driven system for mapping environment variables (.env) directly to Java fields.

• Automatic mapping and type conversion
• Default values and required validation
• Clean and intuitive API

@Env("DB_URL")
@RequiredEnv
String dbUrl;

@Env("PORT")
@Default("8080")
int port;

🪞 Obsidian Reflection

A fluent and powerful API that makes working with java.lang.reflect safe and intuitive.

• Chainable, builder-pattern reflection
• Semantic filters for methods and fields
• Simple instantiation without boilerplate

// Invoke all getters effortlessly
Reflect.on(user)
    .methods()
    .getters()
    .each(System.out::println);

⏳ Obsidian Promise

Modern, functional asynchronous computation built on top of Java concurrency.

• Thread-safe, immutable futures
• Advanced functional composition (map, flatMap)
• Robust error recovery and timeout management

Promise<User> user = loadUser(id)
    .timeout(Duration.ofSeconds(5))
    .retry(3)
    .recover(e -> User.guest());

🧩 Obsidian Collections & Core

High-performance fundamental utilities, functional tools, and advanced data structures.

• Try for elegant error handling without try/catch hell
• Box thread-safe mutable state containers (Atomic, Volatile, Plain)
• When API for fluent conditional chains and pattern matching

Try<Integer> score = Try.of(() -> parseScore())
    .map(n -> n * 2)
    .recover(e -> 0);

When.when(user.isPremium())
    .then(() -> applyDiscount())
    .execute();

---

🚀 Installation & Quick Start

Obsidian is modular. You can import the entire framework or just the modules you need. Artifact Group: io.obsidian

Maven Configuration

Add the dependencies to your pom.xml:

<dependencies>
    <dependency>
        <groupId>io.obsidian</groupId>
        <artifactId>obsidian</artifactId> <!-- Core Module -->
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>io.obsidian</groupId>
        <artifactId>obsidian-configuration</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
    <!-- Add other modules: obsidian-reflection, obsidian-promise, obsidian-collections -->
</dependencies>

Gradle Configuration (Kotlin DSL)

dependencies {
    implementation("io.obsidian:obsidian:1.0.0-SNAPSHOT")
    implementation("io.obsidian:obsidian-configuration:1.0.0-SNAPSHOT")
    implementation("io.obsidian:obsidian-reflection:1.0.0-SNAPSHOT")
    implementation("io.obsidian:obsidian-promise:1.0.0-SNAPSHOT")
}

🔑 Using GitHub Packages

Obsidian is published to GitHub Packages. To pull Obsidian modules via GitHub Packages, authenticate your Gradle/Maven build using your GitHub Personal Access Token (PAT).

For Gradle (build.gradle.kts):

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/nadezhdkov/Obsidian")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
        }
    }
}

(Store gpr.user and gpr.key securely in your ~/.gradle/gradle.properties)

---

🏗️ Development & Building

The project is structured as a multi-module Gradle build, requiring Java 21.

# Clone the repository
git clone https://github.com/nadezhdkov/Obsidian.git
cd Obsidian

# Compile and Build
./gradlew build

# Run all test suites
./gradlew test

# Publish to local Maven repository
./gradlew publishToMavenLocal

Project Structure

• obsidian-configuration: Environment variable mapping framework
• obsidian-reflection: Fluent Reflection API
• obsidian-promise: Async processing utilities
• obsidian-collections: Specialized collections and data streams
• src/main/java/obsidian: Core framework (Functional interfaces, Control Flow, Concurrent utilities)

---

🤝 Contributing

We welcome community contributions! Please read our guidelines to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Verify your code with ./gradlew build
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

🐛 Issues & Support

Found an issue or have a feature request? Let us know!

• Create a bug report on GitHub.
• For usage queries, check out the documentation in the /docs directory.

📄 License

Obsidian is completely open-source and released under the Apache License 2.0.

Developed with ❤️ using modern Java