Xorcery

A set of Java libraries dedicated to helping you build better applications.

Table of Contents

• Features
• Getting Started
  • Prerequisites
  • Installation
• Usage
• API Documentation
• Building from Source
• Running Tests
• Contributing
• License
• Contact

Features

Xorcery contains several core modules, which are used by most applications and services:

• Core: dependency injection and runtime level support through HK2
• Configuration: composable, overridable, uses YAML+JSON-Schema for editing and validation
• JSON: JSON merging and reference resolving, primarily for configuration handling
• JUnit: helpers to run Xorcery in tests
• Log4j: integration of configuration and DI with Log4j2
• Runner: standard Main class with CLI to startup your application
• Util: various helper classes

Extensions

The majority of the useful modules used to build applications and services are in the extensions, which you can add to your own project as needed.

• AWS Authentication
• Certificate management
• DNS client and registration
• EventStore client
• JAX-RS server helpers
• Jersey JAX-RS client
• Jersey JAX-RS server
• Jetty client
• Jetty server
• JSON:API
• JSON-Schema
• JWT server
• Keystore management
• Kurrent client
• Maven plugins: JSON-Schema generation for module configurations, etc.
• OpenSearch client
• OpenTelemetry: SDK integration, exporters, modules, and JDK/JVM/system integrations
• Reactive streams over websockets: integrated with Project Reactor(Flux)
• Secrets access
• Status API
• Thymeleaf integration
• Build and runtime translation

Most modules are integrated with the Configuration object, Log4j2 loggers, and OpenTelemetry observability support. Many of these only require you to add it as a dependency and providing your own configuration overrides. Some of them provide APIs and SPIs that you can use or implement in your own modules.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Java 21 or higher
• Maven 3.6+ or Gradle 6.0+
• Git (for cloning the repository)

You can verify your Java installation:

java -version
javac -version

Installation

Option 1: Maven (Recommended)

Add the Maven BOM dependency to your pom.xml:

<dependencyManagement>
  <dependency>
      <groupId>dev.xorcery</groupId>
      <artifactId>xorcery-bom</artifactId>
      <version>${xorcery.version}</version>
      <type>pom</type>
      <scope>import</scope>
  </dependency>
</dependencyManagement>

and then add any modules you want to use which are included in the BOM, including a reference to our repository server:

<dependencies>
    ...
    <dependency>
        <groupId>dev.xorcery</groupId>
        <artifactId>xorcery-dns-client</artifactId>
    </dependency>
    ...
</dependencies>

<repositories>
    ...
    <repository>
        <id>cantara-releases</id>
        <name>Cantara Release Repository</name>
        <url>https://mvnrepo.cantara.no/content/repositories/releases/</url>
    </repository>
    <repository>
        <id>cantara-snapshots</id>
        <name>Cantara Snapshot Repository</name>
        <url>https://mvnrepo.cantara.no/content/repositories/snapshots/</url>
    </repository>
</repositories>

Option 2: Clone and Build

git clone https://github.com/Cantara/xorcery.git
cd xorcery
mvn clean install

Usage

Basic Example

import dev.xorcery.core.Xorcery;
import dev.xorcery.configuration.Configuration;
import dev.xorcery.configuration.builder.ConfigurationBuilder;

public class Example {
    public static void main(String[] args) throws Throwable {
        // Add all module configuration and optional overrides, and then merge them into a single configuration
        Configuration configuration = new ConfigurationBuilder().addDefaults().build();
        try (Xorcery xorcery = new Xorcery(configuration)){
            // This will use HK2 to find any enabled services, instantiate them using DI, and optionally use
            // run-level semantics to get the application into a started state
        }
        // At this point the Xorcery instance has been closed/stopped, and all services are shutdown. 
        // Use shutdown hooks in your application for long-lived services that are stopped manually
    }
}

You can do this both for your applications and for running tests. Each named service automatically gets a feature flag in the configuration (e.g. service "foo" is controlled by "foo.enabled: true/false" in config), which makes it straightforward to run Xorcery with all or a subset of the packaged services, depending on your needs.

API Documentation

See Javadocs

Building from Source

Using Maven

# Clone the repository
git clone https://github.com/Cantara/xorcery.git
cd xorcery

# Compile and install all modules
mvn clean install

Running Tests

Unit Tests

# Maven
mvn test

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Start for Contributors

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

Development Setup

git clone https://github.com/Cantara/xorcery.git
cd xorcery
mvn clean install

Code Style

This project follows Google Java Style Guide. Please ensure your code adheres to these standards.

FAQ

Q: What Java versions are supported? A: Java 21 and higher are supported.

Q: How do I report a bug? A: Please create an issue on GitHub with a detailed description and steps to reproduce.

Q: Is this project production-ready? A: Yes, this project is actively used in production environments.

License

This project is licensed under the ASLv2 License - see the LICENSE file for details.

Contact

Project Maintainer: Rickard Oberg

• Email: [email protected]
• GitHub: @rickardoberg
• LinkedIn: Your Profile

Acknowledgments

• Thanks to all contributors who have helped shape this project
• Built with ❤️ using Java

---

⭐ If you find this project helpful, please give it a star on GitHub!