The Holon Platform - Reference manual

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

1. Holon Platform Documentation and learning

1.1. About the documentation

The Holon Platform reference guide is available as HTML and PDF documents. The latest documentation version is available at https://docs.holon-platform.com/current/reference.

Each platform module is shipped with its own documentation, which can be accessed and downloaded independently. See the Holon Platform Modules section for the available modules list and their documentation resources.

The Holon Platform is Open Source, including this documentation. If you find problems with the documentation resources or if you just want to improve them, please get involved.

1.2. Getting help and report bugs

Besides this reference guide, for more advanced topics or if you have troubles with the Holon Platform, we’d like to help and support you:

Ask a question on stackoverflow.com. We monitor questions tagged with holon-platform.
Report bugs at github.com/holon-platform/platform/issues. See the Holon Platform Modules section to report bugs for a specific platform module.
We offer professional support services from our team: learn more.

1.3. Tutorials and examples

A set of tutorials is available, see the Holon Platform Tutorials.

See github.com/holon-platform/holon-examples for a rich set of example projects.

2. Getting started

2.1. Introducing the Holon Platform

The Holon Platform is a Java development ecosystem to create and maintain high quality, enteprise-grade web applications and services.

Some main platform key points are:

Provides "real" Java API: the Holon platform is designed as a real Java API, with the aim to leverage the most recent Java features and to create strong abstraction layers to ensure implementation details encapsulation, high productivity and long-term maintanability with a minimal application upgrade effort to follow the platform evolution.
It is modular and full-stack at the same time: the Holon platform provides a full-stack application development environment, but you can select only the components or modules you need and replace or extend them leveraging on the high configurability and extensibility features ensured by the platform architecture.
The Property data model and the Datastore API: the Holon platform property data model architecture allows to use an application data model which is independent from the persistence technology and make it a shared asset for all application layers, from the backend to the UI, avoiding code duplication and using a consistent API to manage it.
It’s extensible by design: the Holon platform components are designed to be highly extensible, configurable and integrable with other frameworks or libraries. This way it is the platform which must fit your needs, and not vice-versa.

The platform is organized in modules: each module corresponds to a GitHub repository and it is composed by a number of artifacts. All the modules depends from the core module, and any other module (and its artifacts) can be used independently, to suit each project/application needs with a lightweight dependency set.

See the Holon Platform Modules section of the documentation for a list of all available modules.

2.2. System Requirements

The Holon Platform 5.2.0-alpha1 requires Java 8 or above.

Explicit build support is provided for Maven (3+).

3. What’s new in version 5.1.x

Along with all the latest bug fixes, there is also a set of useful features that made it to the 5.1 minor version. The 5.1.x API is fully compatible with the 5.0.x API. The list of the new and noteworthy features is available following the links below, organized by module:

What’s new in the Core module
What’s new in the JSON module
What’s new in the JAX-RS module
What’s new in the JDBC module
The new JPA module is now available
What’s new in the JDBC Datastore module
What’s new in the JPA Datastore module
What’s new in the Vaadin module

Each module documentation section, when necessary, provides a list of the deprecated API operations and a migration guide to learn how to replace these operations with the new provided ones.

Besides the new features documentation updates, the Holon Platform reference manual has been improved and extended to provide an even more useful and effective documentation, with more code examples and detailed explanations of the Holon Platform APIs.

3.1. Release notes

The releases of each platform module and of the platform itself are tracked in the GitHub repositories. Each release tag provides a link to the list of the closed issues, including bug fixes and enhancements.

For the platform distribution project, the release informations can be found at github.com/holon-platform/platform/releases.

3.2. Platform distribution versioning

The Holon platform use the Semantic Versioning system.

Each platform module is versioned following the semantic versioning convention.

The platform distribution artifact, which contains the Maven BOM (Bill Of Materials) to provide all the platform modules artifacts (see below), is bound to all the latest modules version at the platform release time. For this reason, the following convention is used for the platform distribution versioning:

When a new platform module version is released, a new platform distribution version is released too, and the platform overall version is incremented according to the module version: if it is a patch version release, the platform patch version is incremented; if it is a minor version release, the platform minor version is incremented instead.
When more than one platform module version changes, the most significative version change is taken into account: if the minor version of a module is changed, the platform minor version is incremented; if only the patch version of the modules is changed, the platform patch version is incremented instead.
The platform major version number is incremented for breaking and not backward-compatible API changes. In this case, all the platform modules will be versioned with the new major version number.
The platform patch version number can be incremented even if there are not any module version changes, for example to release a documentation or BOM project fix.

3.3. Obtain the platform artifacts

The Holon Platform uses Maven to build and distribute the platform artifacts, using the com.holon-platform base group id.

All the production releases (including binaries, sources and javadocs) are hosted in the Maven Central repository.

The easiest way to obtain the Holon Platform artifacts is by using the platform BOM (Bill Of Materials), which provides a complete set of dependencies of the latest release of each module. The Maven coordinates of the platform BOM are:

Platform BOM Maven coordinates:

<groupId>com.holon-platform</groupId>
<artifactId>bom</artifactId>
<version>5.2.0-alpha1</version>

The BOM can be imported an used in a Maven project in the following way:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.holon-platform</groupId>
      <artifactId>bom</artifactId>
      <version>5.2.0-alpha1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

With the platform BOM imported in your dependency management section, you can declare and obtain the artifacts you need without specifying the artifact version, which will be the latest version provided by the platform bom. For example:

<dependencies>
  <dependency>
    <groupId>com.holon-platform.core</groupId>
    <artifactId>holon-core</artifactId>
  </dependency>
</dependencies>

See the Holon Platform Modules section for detailed informations about each module’s artifacts.

3.3.1. Pre-releases

The platform pre-releases are hosted in the Holon Platform pre-releases Bintray repository.

To obtain a pre-release artifact you need to add the following repository specification either in settings.xml or in your pom.xml:

<repositories>
    <!-- ... -->
   <repository>
    <id>holon-platform-pre-releases</id>
    <name>Holon Platform pre-releases</name>
    <url>http://dl.bintray.com/holon-platform/pre-releases</url>
    </repository>
</repositories>

3.4. Spring and Spring Boot integration

The Holon Platform provides a wide integration with the Spring Framework and Spring Boot.

A set of Enable* type annotation are available for a quick and simple configuration of the most common and useful Spring-enabled platform components.

Besides, a complete and powerful set of Spring Boot auto-configuration classes and starters are provided for each platform module.

See each module specific documentation for available Spring and Spring Boot configuration helpers and resources.

4. Holon Platform Modules

See the reference manual of each module to lean about the new and noteworthy features introduced with the 5.1.x platform version.

4.1. Holon Core

The Holon Platform Core module represents the platform foundation, providing the definition of the overall architecture, base structures and APIs.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-core	github.com/holon-platform/holon-core/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-core

github.com/holon-platform/holon-core/issues

4.2. Holon JSON

The Holon Platform JSON module provides JSON support and integration with the platform foundation elements, using common libraries such as Jackson and Gson.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-json	github.com/holon-platform/holon-json/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-json

github.com/holon-platform/holon-json/issues

4.3. Holon JAX-RS

The Holon Platform JAX-RS module provides support, services and configuration helpers to build and consume RESTful Web Services using the Java API for RESTful Web Services (JAX-RS) standard. The module ensures the integration between JAX-RS compliant components with the platform foundation elements and architectural structures (such as Property, PropertyBox and Authentication) and provides support and configuration facilities for popular libraries such as Jersey, Resteasy and Swagger for API documentation following the OpenAPI Specification (OAS).

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-jaxrs	github.com/holon-platform/holon-jaxrs/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-jaxrs

github.com/holon-platform/holon-jaxrs/issues

4.4. Holon JDBC

The Holon Platform JDBC module represents the platform support for the Java DataBase Connectivity API, dealing with DataSource configuration and multi-tenancy support.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-jdbc	github.com/holon-platform/holon-jdbc/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-jdbc

github.com/holon-platform/holon-jdbc/issues

4.5. Holon JDBC Datastore

The Holon JDBC Datastore module is the Java DataBase Connectivity reference implementation of the Datastore abstraction.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-datastore-jdbc	github.com/holon-platform/holon-datastore-jdbc/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-datastore-jdbc

github.com/holon-platform/holon-datastore-jdbc/issues

4.6. Holon JPA

The Holon Platform JPA module contains the base support classes for the Java Persistence API. Especially, provides a set of JPA annotations bean post processors to seamlessy use and configure JPA entity beans within the Holon Platform Property architecture and bean introspection facilities.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-jpa	github.com/holon-platform/holon-jpa/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-jpa

github.com/holon-platform/holon-jpa/issues

4.7. Holon JPA Datastore

The Holon JPA Datastore module is the Java Persistence API reference implementation of the Datastore abstraction.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-datastore-jpa	github.com/holon-platform/holon-datastore-jpa/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-datastore-jpa

github.com/holon-platform/holon-datastore-jpa/issues

4.8. Holon JPA Datastore QueryDSL integration

This module provides a set of QueryDSL integration features for the JPA Datastore module.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-datastore-jpa-querydsl	github.com/holon-platform/holon-datastore-jpa-querydsl/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-datastore-jpa-querydsl

github.com/holon-platform/holon-datastore-jpa-querydsl/issues

4.9. Holon MongoDB Datastore

The Holon MongoDB Datastore module is the MongoDB reference implementation of the Datastore abstraction.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-datastore-mongo	github.com/holon-platform/holon-datastore-mongo/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-datastore-mongo

github.com/holon-platform/holon-datastore-mongo/issues

4.10. Holon Vaadin UI

The Holon Platform Vaadin module uses Vaadin to build User Interfaces for web applications using Java. This module provides integration with platform foundation architecture, a set of components and builders, configuration helpers, a complete Datastore integration with Vaadin data binding and a full support for virtual pages and navigation.

This module requires Vaadin version 8.1.x or higher.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-vaadin	github.com/holon-platform/holon-vaadin/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-vaadin

github.com/holon-platform/holon-vaadin/issues

4.10.1. Holon Vaadin 7 compatibility module

A Vaadin UI integration module using the version 7 of the Vaadin framework is also available, providing an API almost completely compatible with the official Vaadin (version 8) module.

Documentation	Sources	Issues
html \| pdf	github.com/holon-platform/holon-vaadin7	github.com/holon-platform/holon-vaadin7/issues

Documentation

Sources

Issues

html | pdf

github.com/holon-platform/holon-vaadin7

github.com/holon-platform/holon-vaadin7/issues

5. Holon resources

See The Holon Platform website for additional resources, news, events and commercial support.

6. Appendices

6.1. Spring Boot starters reference

Below a list of the available Spring Boot starters in the Holon Platform version 5.2.0-alpha1, ordered by module:

Module Group id Artifact id Name Description Reference

Module	Group id	Artifact id	Name	Description	Reference
Core	`com.holon-platform.core`	`holon-starter`	Core starter	Base starter to enable the core auto-configuration features provided by the Holon Platform: Spring context scope, Spring tenant scope and JWT configuration.	Reference
Core	`com.holon-platform.core`	`holon-starter-test`	Core test starter	Convenience starter to provide a base set of test dependencies, including Spring and Spring Boot test dependencies, JUnit and Mockito.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey-client`	Jersey + Jackson client starter	JAX-RS client starter using Jersey as JAX-RS implementation and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey-client-gson`	Jersey + Gson client starter	JAX-RS client starter using Jersey as JAX-RS implementation and Gson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy-client`	Jersey + Jackson client starter	JAX-RS client starter using Resteasy as JAX-RS implementation and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy-client-gson`	Jersey + Jackson client starter	JAX-RS client starter using Resteasy as JAX-RS implementation and Gson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey`	Jersey + Tomcat + Jackson server starter	JAX-RS server starter using Jersey as JAX-RS implementation, Tomcat as embedded servlet container and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey-gson`	Jersey + Tomcat + Gson server starter	JAX-RS server starter using Jersey as JAX-RS implementation, Tomcat as embedded servlet container and Gson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey-undertow`	Jersey + Undertow + Jackson server starter	JAX-RS server starter using Jersey as JAX-RS implementation, Undertow as embedded servlet container and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-jersey-undertow-gson`	Jersey + Undertow + Gson server starter	JAX-RS server starter using Jersey as JAX-RS implementation, Undertow as embedded servlet container and Gson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy`	Resteasy + Tomcat + Jackson server starter	JAX-RS server starter using Resteasy as JAX-RS implementation, Tomcat as embedded servlet container and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy-gson`	Resteasy + Tomcat + Gson server starter	JAX-RS server starter using Resteasy as JAX-RS implementation, Tomcat as embedded servlet container and Gson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy-undertow`	Resteasy + Undertow + Jackson server starter	JAX-RS server starter using Resteasy as JAX-RS implementation, Undertow as embedded servlet container and Jackson as JSON provider.	Reference
JAX-RS	`com.holon-platform.jaxrs`	`holon-starter-resteasy-undertow-gson`	Resteasy + Undertow + Gson server starter	JAX-RS server starter using Resteasy as JAX-RS implementation, Undertow as embedded servlet container and Gson as JSON provider.	Reference
JDBC	`com.holon-platform.jdbc`	`holon-starter-jdbc`	JDBC DataSource starter	Starter to enable the Holon Platform `DataSource` auto-configuration features, as described in the DataSource auto-configuration documentation.	Reference
JDBC	`com.holon-platform.jdbc`	`holon-starter-jdbc-hikaricp`	JDBC DataSource starter + HikariCP	Starter to enable the Holon Platform `DataSource` auto-configuration features, as described in the DataSource auto-configuration documentation and additionally providing the HikariCP pooling DataSource dependency.	Reference
JDBC Datastore	`com.holon-platform.jdbc`	`holon-starter-jdbc-datastore`	JDBC Datastore starter	JDBC `Datastore` auto-configuration starter, including the Holon Platform `DataSource` auto-configuration features.	Reference
JDBC Datastore	`com.holon-platform.jdbc`	`holon-starter-jdbc-datastore-hikaricp`	JDBC Datastore starter + HikariCP	JDBC `Datastore` auto-configuration starter, including the Holon Platform `DataSource` auto-configuration features and additionally providing the HikariCP pooling DataSource dependency.	Reference
JPA Datastore	`com.holon-platform.jpa`	`holon-starter-jpa-hibernate`	JPA configuration and Datastore starter using Hibernate	Spring JPA stack and JPA `Datastore` auto-configuration starter, using Hibernate ORM as persistence provider.	Reference
JPA Datastore	`com.holon-platform.jpa`	`holon-starter-jpa-eclipselink`	JPA configuration and Datastore starter using Eclipselink	Spring JPA stack and JPA `Datastore` auto-configuration starter, using Eclipselink as persistence provider.	Reference
QueryDSL JPA	`com.holon-platform.jpa`	`holon-starter-jpa-querydsl-hibernate`	JPA configuration and Datastore starter with QueryDSL integration using Hibernate	Spring JPA stack, JPA `Datastore` and QueryDSL integration auto-configuration starter, using Hibernate ORM as persistence provider.	Reference
QueryDSL JPA	`com.holon-platform.jpa`	`holon-starter-jpa-querydsl-eclipselink`	JPA configuration and Datastore starter with QueryDSL integration using Eclipselink	Spring JPA stack, JPA `Datastore` and QueryDSL integration auto-configuration starter, using Eclipselink as persistence provider.	Reference
Vaadin	`com.holon-platform.vaadin`	`holon-starter-vaadin`	Vaadin application starter using Tomcat	Vaadin application starter with Holon Platform integration auto-configuration, including `ViewNavigator` auto-configuration, using Tomcat as embedded servlet container.	Reference
Vaadin	`com.holon-platform.vaadin`	`holon-starter-vaadin-undertow`	Vaadin application starter using Undertow	Vaadin application starter with Holon Platform integration auto-configuration, including `ViewNavigator` auto-configuration, using Undertow as embedded servlet container.	Reference

Core

com.holon-platform.core

holon-starter

Core starter

Base starter to enable the core auto-configuration features provided by the Holon Platform: Spring context scope, Spring tenant scope and JWT configuration.