Note
Hartshorn is currently in active development. You are welcome to use it, but please be aware that it may not be stable yet and features are subject to change at any time (though deprecation notices are typically given in advance). If you encounter any issues, please report them on the issue tracker.
Hartshorn is a modern framework built on the JVM platform that offers support for modular, scalable, and testable application development using Java and other JVM-based languages. Its main objective is to simplify the creation and administration of complex JVM applications by providing developers with an easy to use ecosystem of utilities and conventions. To learn more about Hartshorn's fundamental technologies and principles, you can refer to the dedicated topic on core technologies.
If you are new to Hartshorn, the official documentation website has a getting started section that provides comprehensive guides to help you get started quickly. The guides use Hartshorn's application starter to facilitate your initial setup. Additionally, if you only need the Maven dependencies for your project, they are listed below for your convenience.
The framework provides the flexibility to selectively utilize the required modules by including their dedicated dependencies. You can access all the modules and their corresponding releases on Maven Central.
To begin, add the following Maven dependency:
<dependency>
<groupId>org.dockbox.hartshorn</groupId>
<artifactId>hartshorn-launchpad</artifactId>
<version>${version}</version>
</dependency>If you are using Gradle, use this implementation:
implementation "org.dockbox.hartshorn:hartshorn-launchpad:$version"The process of starting with Hartshorn is straightforward, and the example below will help you understand the basic steps of setting up and executing your first application.
The HartshornApplication class is used to build Hartshorn applications. It serves as the entry point of your application and performs the bootstrapping process. The process initiates a self-contained ApplicationContext that manages your application's lifecycle.
public static void main(String[] args) {
// Derives the main class automatically ..
ApplicationContext applicationContext = HartshornApplication.create(args);
// .. alternatively you can pass your main class as an argument
ApplicationContext applicationContext = HartshornApplication.create(MyMainClass.class, args);
// .. or you can configure almost every aspect of the application
ApplicationContext applicationContext = HartshornApplication.createApplication(MyMainClass.class, args).initialize(configurer -> {
// See HartshornApplicationConfigurer for more options
});
}ApplicationContext is at the heart of Hartshorn, and its primary responsibility is to manage your application's lifecycle. It also manages your application's dependency injection container, which enables the injection of dependencies.
The @Binds annotation is used to declare dependencies, which binds a type to its implementation. However, typically you should not use it directly. Instead, you can use the provided @Singleton and @Prototype annotations to declare your components. @Singleton components are created once and shared across the application, while @Prototype components are created each time they are requested.
@Configuration
public class HelloWorldConfiguration {
@Singleton // Shared across the application
public String helloWorld() {
return "Hello World!";
}
@Prototype // Created each time it is requested
public OtherComponent otherComponent() {
return new OtherComponent();
}
}Managed components are part of your application structure, meaning they are automatically discovered and registered. Components annotated with @Component or a stereotype annotation annotated with @Component, such as @Configuration, are considered managed.
@Component
public class HelloWorldComponent {
@Inject
private String helloWorld;
public void sayHelloWorld() {
System.out.println(helloWorld);
}
}Finally, we can bring everything together and print "Hello World!" to the console using our SampleService.
public static void main(String[] args) {
ApplicationContext applicationContext = HartshornApplication.create();
HelloWorldComponent helloWorldComponent = applicationContext.get(HelloWorldComponent.class);
helloWorldComponent.sayHelloWorld();
}Once you've taken your first steps with Hartshorn, it's essential to expand your knowledge of the framework. The documentation is an excellent starting point that will help you become more familiar with the framework. Additionally, you can explore the examples repository for more comprehensive examples.
If you want to build Hartshorn yourself, either to access pre-release versions or to customize the framework, the guide below explains how to build usable JAR artifacts.
Important
Note that you will need a Java installation with JDK 21 or a more recent version for all platforms.
Hartshorn uses Maven to automate builds, performing several steps before and after a build has completed. To build all Hartshorn modules at once, run mvn clean install in the base directory. This will build all modules and run all tests. If you want to skip tests, you can use the -DskipTests flag.
Looking to get involved with Hartshorn? We would love to have you on board! Whether you want to report a bug, have a question, or even contribute code, your help is greatly appreciated. Before you start, please take a moment to read through our contribution guidelines to ensure that your efforts align with our community standards and development practices.
At Dockbox, we value our community of contributors and strive to maintain an open and collaborative environment. Our project is powered by the contributions of individuals like you, who are passionate about building high-quality software and sharing their knowledge with others.
If you're looking for ways to contribute, we have plenty of opportunities available. You can help us by reporting bugs, reviewing code, writing documentation, or even contributing your own code changes. No contribution is too small, and we welcome all levels of experience.
We also welcome QA testers who try out Hartshorn in their own projects to see what works and what doesn't. Your feedback can help us improve the quality of the framework and make it even more valuable for our users.
Hartshorn is Open Source software released under the Apache 2.0 license.