# The Holon Platform - Reference manual

version 5.2.0

Copyright © 2016-2018

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 requires Java 8 or above.

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

## 3. What’s new in version 5.2.x

Three new platform modules were introduced:

- The Holon Reactor module, which provides integration between the Holon Platform core APIs, such as `Datastore` and `RestClient`, and the Project Reactor reactive programming model, using the `Flux` and `Mono` APIs.

- The Holon MongoDB Datastore module, the MongoDB reference implementation of the Datastore API, with asynchronous and reactive programming models support.

- The Holon Vaadin Flow UI module, which uses the Vaadin Flow platform to build for web applications UIs using Java and provides integration with platform foundation architecture and APIs.

Furthermore, along with all the latest bug fixes, there is also a set of useful features that made it to the 5.2 version. As usual, for each module the 5.2.x API is fully backward compatible.

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

- What’s new in the JDBC Datastore module

- What’s new in the JPA Datastore module

- What’s new in the Vaadin module

## 4. 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.

### 4.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.

### 4.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.

### 4.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</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</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.

#### 4.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>

### 4.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.

## 5. Holon Platform Modules

| See the reference manual of each module for the modules changelog.

### 5.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

### 5.2. Holon Reactor

The Holon Platform Reactor module provides integration between the Holon Platform core APIs, such as `Datastore` and `RestClient`, and the Project Reactor reactive programming model, using the `Flux` and `Mono` APIs.

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

### 5.3. 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

### 5.4. 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

### 5.5. 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

### 5.6. 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

### 5.7. 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

### 5.8. 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

### 5.9. 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

### 5.10. Holon MongoDB Datastore

The Holon MongoDB Datastore module is the MongoDB reference implementation of the Datastore API, with asynchronous and reactive programming models support.

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

### 5.11. Holon Vaadin Flow UI

The Holon Platform Vaadin Flow module uses the Vaadin Flow platform 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 the Vaadin data binding and a `Navigator` API to provide routing management with query parameters support.

The module is aligned to the last available Vaadin platform version.

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

### 5.12. Holon Vaadin 8 UI

The Holon Platform Vaadin module uses Vaadin version 8+ 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

#### 5.12.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

## 6. Holon resources

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

## 7. Appendices

### 7.1. Spring Boot starters reference

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

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-flow` | Vaadin Flow application starter using Tomcat | Vaadin Flow application starter with Holon Platform integration auto-configuration, including `Navigator` and `LocalizationContext` auto-configuration, using Tomcat as embedded servlet container. | Reference
Vaadin | `com.holon-platform.vaadin` | `holon-starter-vaadin-flow-undertow` | Vaadin Flow application starter using Undertow | Vaadin Flow application starter with Holon Platform integration auto-configuration, including `Navigator` and `LocalizationContext` auto-configuration, using Undertow as embedded servlet container. | 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