= Holon Platform Core Module - Reference manual
:description: Holon platform Core module reference documentation. \
The Core section covers all the platform foundation architecture arguments, including Context resources, the Property data model, the Datastore API, multi-tenancy support, authentication and authorization, JWT support, Spring framework and Spring Boot integration.
:revnumber: {project-version}
:apidir: ../api/holon-core
:linkattrs:
:sectnums:
:nofooter:
:toc: left
:toclevels: 4

Copyright © 2016-2019

_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._

== Introduction

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

=== Sources and contributions

The Holon Platform *Core* module source code is available from the GitHub repository link:https://github.com/holon-platform/holon-core[https://github.com/holon-platform/holon-core^].

See the repository `README` file for information about:

* The source code structure.
* How to build the module artifacts from sources.
* Where to find the code examples.
* How to contribute to the module development.

== Obtaining the artifacts

The Holon Platform uses https://maven.apache.org[Maven^] for projects build and configuration. All the platform artifacts are published in the *Maven Central Repository*, so there is no need to explicitly declare additional repositories in your project `pom` file.

At the top of each _section_ of this documentation you will find the Maven _coordinates_ (group id, artifact id and version) to obtain the artifact(s) as a dependency for your project.

A *BOM (Bill Of Materials)* `pom` is provided to import the available dependencies for a specific version in your projects. The Maven coordinates for the core BOM are the following:

_Maven coordinates_:
[source, xml, subs="attributes+"]
----
<groupId>com.holon-platform.core</groupId>
<artifactId>holon-bom</artifactId>
<version>{revnumber}</version>
----

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

[source, xml, subs="verbatim,quotes,attributes+"]
----
<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>com.holon-platform.core</groupId>
			<artifactId>holon-bom</artifactId>
			<version>{revnumber}</version>
			*<type>pom</type>*
			*<scope>import</scope>*
		</dependency>
	</dependencies>
</dependencyManagement>
----

=== Using the Platform BOM

The Holon Platform provides an *overall Maven BOM (Bill of Materials)* to easily obtain all the available platform artifacts.

See link:index.html#obtain-the-platform-artifacts[Obtain the platform artifacts] for details.

[[WhatsNew53x]]
== What's new in version 5.3.x

* *PropertySet API*:
New static `builderOf(PropertySet<P> propertySet)` method which can be used to obtain a `PropertySet` `Builder` starting from an existing `PropertySet`, cloning its configuration, identifiers and properties.

* *PropertySet Builder API*:
The `identifier(PT property)` method was deprecated in favour of the new `withIdentifier(PT property)` method to respect the naming conventions.

[[WhatsNew52x]]
== What's new in version 5.2.x

* *JDK 9+ module support*:
Support for JDK 9+ module system using `Automatic-Module-Name`.

*  *AsyncDatastore*:
The new `holon-async-datastore` artifact was introduced to provide a core link:{apidir}/com/holonplatform/async/datastore/AsyncDatastore.html[AsyncDatastore^] API. The `AsyncDatastore` API provides asynchronous Datastore API operations, using the standard JVN `CompletionStage` type to provide the operations result. See <<AvailableDatastores>> to check the specific `AsyncDatastore` support.

*  *AsyncRestClient*:
The new `holon-async-http` artifact was introduced to provide a core link:{apidir}/com/holonplatform/async/http/AsyncRestClient.html[AsyncRestClient^] API. The `AsyncRestClient` API provides asynchronous REST client API operations, using the standard JVN `CompletionStage` type to provide the operations result.

* *Property model*:
The new link:{apidir}/com/holonplatform/core/property/CollectionProperty.html[CollectionProperty^] interface was introduced to provide specific `Collection` type `Property` values, specifically using the standard `Set` and `List` collection types. See <<CollectionProperties>>.

* *QueryConfigurationProvider builder*:
A fluent builder is now available for the link:{apidir}/com/holonplatform/core/query/QueryConfigurationProvider.html[QueryConfigurationProvider^] API. The builder can be obtained using the `builder()` static method.

* *Datastore Query distinct support*:
The new `distinct()` link:{apidir}/com/holonplatform/core/query/QueryBuilder.html[QueryBuilder^] method can be used to obtain _distinct_ query projection result values. See <<QueryDistinct>>.

* *Datastore Query select all projection*:
A new link:{apidir}/com/holonplatform/core/query/SelectAllProjection.html[SelectAllProjection^] is now available to obtain all the values af a persistent data entity instance using the `Datastore` query API. See <<BuiltinQueryProjections>>.

* *Datastore Query locks*:
The new link:{apidir}/com/holonplatform/core/query/lock/LockQuery.html[LockQuery^] API is a `Datastore` query extension to provide database lock support, through the link:{apidir}/com/holonplatform/core/query/lock/LockSupport.html[LockSupport^]. Currently, only the _pessimistic_ lock mode is supported. For the query lock support availability, see the specific `Datastore` implementations documentation.

* *@EnableDatastoreConfiguration annotation*:
The link:{apidir}/com/holonplatform/spring/EnableDatastoreConfiguration.html[EnableDatastoreConfiguration^] annotation can be used on Spring configuration classes to enable a post processor for automatic `Datastore` Spring bean types configuration. See <<EnableDatastoreConfiguration>>.

* *LocalizationChangeListener*:
The new link:{apidir}/com/holonplatform/core/i18n/LocalizationContext.LocalizationChangeListener.html[LocalizationChangeListener^] interface can be used to listen to `LocalizationContext` localization changes. See <<LocalizationChangeListener>>.

* The Holon Platform *Spring* and *Spring Boot* support is now targeted on the version *5.x* and *2.1.x* respectively.

[[MigratingFrom51x]]
=== Migrating from version 5.1.x

==== API changes

* *Transaction API*: 
The link:{apidir}/com/holonplatform/core/datastore/transaction/TransactionConfiguration.html[TransactionConfiguration^] API was made more abstract and implementation independent, using the link:{apidir}/com/holonplatform/core/datastore/transaction/TransactionOptions.html[TransactionOptions^] interface to represent transaction configuration options. The `TransactionOptions` has to be extended by concrete implementations to represent and provide the supported transaction configuration attributes.
For this reason, the `com.holonplatform.core.datastore.transaction.TransactionIsolation` enumeration was moved to the *holon-jdbc* module.

Furthermore, the `TransactionException` class hierarchy was moved from the link:{apidir}/com/holonplatform/core/datastore/transaction/Transaction.html[Transaction^] interface to the new {apidir}/com/holonplatform/core/datastore/transaction/TransactionStatus.html[TransactionStatus^] interface, which represents a base transaction definition, shared with the asynchronous Datastore implementations.

[[WhatsNew51x]]
== What's new in version 5.1.x

=== Property model

* The `Property` instance identification strategy can now be customized using specific _equals_ and _hashCode_ handlers. See <<PropertyIdentity>>.

* The `PathProperty` interface now provides a set of sub types, to consistently handle property _expressions_ which are type specific, for the main Java types (*String*, *Numbers*, *Temporal types* and *Boolean*). See <<PathPropertySubTypes>>.

* The `PropertySet` interface now supports a generic *configuration* container, likewise the `Property` interface. See <<PropertySetConfiguration>>.

* The `PropertySet` interface now supports _identifier_ properties declaration, which can be used to provide a virtual primary key to distinguish a `PropertyBox` instance from another (using the _identifier_ property values), both at Java objects level (`equals` and `hashCode`) and at persistence architecture level. See <<IdentifierProperties>>.

* Just like the `Property` instances, the `PropertyBox` instances identification strategy can now be customized using specific _equals_ and _hashCode_ handlers. Furthermore, if the `PropertyBox` property set declares one or more _identifier_ property, their values will be used by default to implement the `PropertyBox` instance identification strategy. See <<PropertyBoxIdentification>>.

* The new <<BeanPropertySetPostProcessor>> interface can be used to extend the <<BeanIntrospector>> Bean introspection strategy at Bean property set level, allowing for example to customize the Bean property set configuration. See <<BeanPropertySetPostProcessor>>.

* The <<BeanDataPath,@DataPath>> annotation can be used on Bean classes to declare a *data path mapping* name different from the Bean class or property name, when the Bean class is used in a persistence context and it is bound to a data model definition. See <<BeanDataPath>>.

=== Datastore

* A deep revision of the `Expression` based architecture, which is the foundation, above all, of the `Datastore` API and the abstract `Query` engine. This lead to a more consistent and extensible architecture, along with considerable performance improvements. See the <<Query>> and <<DatastoreExtension>> sections of the `Datastore` documentation.

* New standard `QueryFunction` implementations was made available for the core `Datastore` API. Besides <<StringRelatedFunctions,String related functions>>, a set of *temporal* data types related functions is now available to obtain current date/time (with `java.time.*` types support) and to extract a temporal part (_year_, _month_, _day_, _hour_). See <<TemporalFunctions>>.

* A new `Transactional` API which can be used when a `Datastore` implementation supports *transactions*, which can be managed at a higher level, in an abstract and implementation-independent way. The `Transactional` API allows to execute `Datastore` operations whithin a transaction, taking care of the transaction lifecycle and providing transaction reference to perform _commit_ and _rollback_ operations. See <<TransactionalDatastores>>.

* New `DataMappable` API to represent data model _mappings_. See <<DataMappable>>.

=== JWT authentication

* The JWT configuration now supports a wider range of key sources, formats (such as the `PKCS#12` key store format) and encodings (such as the `PEM` encoding) for private and public key declarations when an asymmetric signing algorithm is used. See <<JwtConfiguration,JWT configuration>>.

=== Spring ecosystem integration

* The `TenantScopeManager` API is now available to manage the _tenant_ scoped beans lifecycle. See <<TenantScopeManager>>.

* The new `holon-spring-security` artifact provides integration between the Holon Platform authentication and authorization architecture and the *Spring Security* one. Furthermore, a `holon-starter-security` Spring Boot starter is now available for quick project setup. See <<SpringSecurity>>.

[[MigratingFrom50x]]
=== Migrating from version 5.0.x

==== Deprecations

* *PropertySet API*: link:{apidir}/com/holonplatform/core/property/PropertySet.html#join-com.holonplatform.core.property.PropertySet...-[join^]. Using this method causes the loss of any property set configuration and/or identifier property declaration. Use the default <<PropertySet,PropertySet>> builder instead.
* *BeanPropertySet API*: link:{apidir}/com/holonplatform/core/beans/BeanPropertySet.html#create-java.lang.Class-com.holonplatform.core.Path-[create providing a parent path^]. The bean properties _parent path_ will always be the `FinalPath` which represents the Bean class, with the bean fully qualified class name as path name. Use the default `create(Class<? extends T> beanClass)` method instead. The same considerations are valid for the `getPropertySet` method of the <<BeanIntrospector,BeanIntrospector>> API.
* *BeanPropertySet/BeanPropertyInspector API*: link:{apidir}/com/holonplatform/core/beans/BeanPropertyInspector.html#requireProperty-java.lang.String-[requireProperty^] methods. The methods name are changed in `property` for consistency with the naming conventions of the new `BeanPropertyInspector` API.
* *SubQuery API*: link:{apidir}/com/holonplatform/core/datastore/relational/SubQuery.html#create-com.holonplatform.core.datastore.Datastore-java.lang.Class-[creation methods providing a Datastore^]. The `Datastore` parameter is no longer required. Use the new `create(...)` method versions which does not require the `Datastore` parameter.
* *JwtConfigProperties API*: link:{apidir}/com/holonplatform/auth/jwt/JwtConfigProperties.html[private and public key source configuration properties^]. The private and public key sources can now be specified using the `publickey.source` property and using the `file:` and `classpath:` prefixes to declare the source type.
* *JwtTokenBuilder API*: link:{apidir}/com/holonplatform/auth/jwt/JwtTokenBuilder.html#buildJwtToken-com.holonplatform.auth.jwt.JwtConfiguration-com.holonplatform.auth.Authentication-java.lang.String-[static token creation method]. The `JwtTokenBuilder` is now an interface. The default implementation can be obtained using the `get()` static method.

==== Property model

With the introduction of the <<PathPropertySubTypes,PathProperty sub types>>, a `PathProperty` declaration should be made using the most suitable sub type, if available.

This is also necessary to use the convenience `QueryFilter` and `QueryFunction` static builder methods to create an expression using the property itself. The expression builder methods are now *organized by sub type*, so, for example, the `contains` method is only available for `String` type properties and the `StringProperty` sub type should by used in this case.

[source, java]
----
include::{examplesdir}/com/holonplatform/core/examples/ExampleProperty.java[tag=subtypes1,indent=0]
----
<1> Create a `StringProperty` path property type with the `name` path name
<2> The `StringProperty` type makes available convenience expression builder methods according to the `String` property type, for example `contains`

== Core API, services and components

=== Introduction

The `holon-core` artifact is the Holon platform *core* API and implementation asset, defining and providing the main platform architecture concepts and structures. All other platform artifacts derive from this one and declares it as a dependency.

_Maven coordinates_:
[source, xml, subs="attributes+"]
----
<groupId>com.holon-platform.core</groupId>
<artifactId>holon-core</artifactId>
<version>{revnumber}</version>
----

include::include/core/_context.adoc[]

include::include/core/_config.adoc[]

include::include/core/_validation.adoc[]

include::include/core/_presenter.adoc[]

include::include/core/_i18n.adoc[]

include::include/core/_properties.adoc[]

include::include/core/_beans.adoc[]

include::include/core/_datastore.adoc[]

include::include/core/_datamappable.adoc[]

include::include/core/_tenancy.adoc[]

include::include/core/_utils.adoc[]

== HTTP messages and RESTful Java client

The `holon-http` artifact provides base *HTTP* protocol support to the Holon platform, dealing with HTTP _messages_ and providing support for _RESTful_ web services invocation through a _client_ API.

_Maven coordinates_:
[source, xml, subs="attributes+"]
----
<groupId>com.holon-platform.core</groupId>
<artifactId>holon-http</artifactId>
<version>{revnumber}</version>
----

include::include/http/_messages.adoc[]

include::include/http/_restclient.adoc[]

[[Auth]]
== Authentication and Authorization

The `holon-auth` artifact provides a complete and highly configurable *authentication* and *authorization* architecture, integrated with all the platform modules. 

_Maven coordinates_:
[source, xml, subs="attributes+"]
----
<groupId>com.holon-platform.core</groupId>
<artifactId>holon-auth</artifactId>
<version>{revnumber}</version>
----

include::include/auth/_realm.adoc[]

include::include/auth/_credentials.adoc[]

include::include/auth/_account.adoc[]

include::include/auth/_context.adoc[]

include::include/auth/_annotation.adoc[]

include::include/auth/_jwt.adoc[]

[[SpringIntegration]]
== Spring ecosystem integration

The `holon-spring` artifact provides integration with the https://spring.io[Spring^] framework and auto-configuration features using https://projects.spring.io/spring-boot[Spring Boot^].

_Maven coordinates_:
[source, xml, subs="attributes+"]
----
<groupId>com.holon-platform.core</groupId>
<artifactId>holon-spring</artifactId>
<version>{revnumber}</version>
----

include::include/spring/_context.adoc[]

include::include/spring/_tenant.adoc[]

include::include/spring/_datastore.adoc[]

include::include/spring/_restclient.adoc[]

include::include/spring/_boot.adoc[]

include::include/spring/_security.adoc[]

== Loggers

By default, the Holon platform uses the https://www.slf4j.org[SLF4J^] API for logging. The use of SLF4J is optional: it is enabled when the presence of SLF4J is detected in the classpath. Otherwise, logging will fall back to JUL (`java.util.logging`).

The following logger names are available:

* `com.holonplatform.core`: the root *core* logger
** `presentation`: for logs related to values presentation
** `i18n`: for logs related to localization and internationalization
** `beans`: for logs related to bean inspection and bean properties
** `property`: for logs related to the `Property` architecture, including `PropertyBox`, property presenters and renderers
** `query`: for logs related to `Query` definition and execution
** `datastore`: for logs related to `Datastore` configuration and operation execution
* `com.holonplatform.jdbc`: for logs related to *JDBC* support classes, such as DataSource builders
* `com.holonplatform.http`: for logs related to *HTTP* support classes, such as `RestClient`
* `com.holonplatform.spring`: for logs related to https://spring.io[Spring^] integration

== System requirements

=== Java

The Holon Platform core module requires https://www.java.com[Java] *8* or higher.
