# The Holon Platform

version 5.0.2

Copyright © 2016-2017

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 the 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. Examples

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 all new Java 8 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’s 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: 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.0.2 requires Java 8 or above. Explicit build support is provided for Maven (3+).

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

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

### 2.5. 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.0.2</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.0.2</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.

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

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

## 3. Holon Platform Modules

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

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

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

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

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

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

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

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

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

## 4. Holon resources

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