<commit_before>= Holon Platform JAX-RS Module - Reference manual
:description: Holon platform JAX-RS module reference documentation. \
It concerns the platform JAX-RS and REST services support, including authentication and authorization, JWT support, Jersey and Resteasy integration, Swagger OpenAPI support, Spring framework integration and Spring Boot auto-configuration.
:revnumber: {project-version}
:apidir: ../api/holon-jax-rs
:coreapidir: ../api/holon-core
:linkattrs:
:sectnums:
:nofooter:
:toc: left
:toclevels: 3

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

== Introduction

The Holon Platform *JAX-RS* module provides support, components and configuration helpers concerning the link:https://github.com/jax-rs/spec/blob/master/spec.pdf[JAX-RS^] - _Java API for RESTful Web Services_.

The module provides *JAX-RS* implementations and integrations for platform foundation components and structures, such as the link:holon-core.html#RestClient[RestClient] API, server-side authentication and authorization using a link:holon-core.html#Realm[Realm] and a complete link:http://swagger.io[Swagger^] _OpenAPI_ support for data containers such as link:holon-core.html#PropertyBox[PropertyBox].

Regarding the *JSON* data-interchange format, this module uses the link:holon-json.html[Holon JSON module] to make available the Holon platform JSON extensions and configuration facilities for JAX-RS endpoints and clients, allowing to seamlessy use link:https://github.com/FasterXML/jackson[Jackson^] or link:https://github.com/google/gson[Gson^] as JSON providers and provide support for _temporal_ types (including the `java.time.*` API) and the `PropertyBox` type out-of-the-box. 

Furthermore, the module makes available a set of *auto-configuration* features, both for the JAX-RS ecosystem and for the link:https://spring.io[Spring^] and link:https://projects.spring.io/spring-boot[Spring Boot^] world.

A complete support for the most used JAX-RS implementations (link:https://github.com/jersey[Jersey^] and  link:http://resteasy.jboss.org[Resteasy^]) is provided, including Resteasy auto-configuration classes for Spring Boot integration.

== 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.jaxrs</groupId>
<artifactId>holon-jaxrs-bom</artifactId>
<version>{revnumber}</version><commit_msg>5.1.0 documentation updates<commit_after>= Holon Platform JAX-RS Module - Reference manual
:description: Holon platform JAX-RS module reference documentation. \
It concerns the platform JAX-RS and REST services support, including authentication and authorization, JWT support, Jersey and Resteasy integration, Swagger OpenAPI support, Spring framework integration and Spring Boot auto-configuration.
:revnumber: {project-version}
:apidir: ../api/holon-jax-rs
:coreapidir: ../api/holon-core
:linkattrs:
:sectnums:
:nofooter:
:toc: left
:toclevels: 3

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

== Introduction

The Holon Platform *JAX-RS* module provides support, components and configuration helpers concerning the link:https://github.com/jax-rs/spec/blob/master/spec.pdf[JAX-RS^] - _Java API for RESTful Web Services_.

The module provides *JAX-RS* implementations and integrations for platform foundation components and structures, such as the link:holon-core.html#RestClient[RestClient] API, server-side authentication and authorization using a link:holon-core.html#Realm[Realm] and a complete link:http://swagger.io[Swagger^] _OpenAPI_ support for data containers such as link:holon-core.html#PropertyBox[PropertyBox].

Regarding the *JSON* data-interchange format, this module uses the link:holon-json.html[Holon JSON module] to make available the Holon platform JSON extensions and configuration facilities for JAX-RS endpoints and clients, allowing to seamlessy use link:https://github.com/FasterXML/jackson[Jackson^] or link:https://github.com/google/gson[Gson^] as JSON providers and provide support for _temporal_ types (including the `java.time.*` API) and the `PropertyBox` type out-of-the-box. 

The module provides a full support for link:http://swagger.io[Swagger^] and the *OpenAPI specification* including support for the `PropertyBox` type (to be exposed as a Swagger _Model_ definition) and for Swagger API listing endpoints (both in _JSON_ and _YAML_ formats) auto-configuration. 

Furthermore, the module makes available a set of *auto-configuration* features, both for the JAX-RS ecosystem and for the link:https://spring.io[Spring^] and link:https://projects.spring.io/spring-boot[Spring Boot^] world.

A complete support for the most used JAX-RS implementations (link:https://github.com/jersey[Jersey^] and  link:http://resteasy.jboss.org[Resteasy^]) is provided, including Resteasy auto-configuration classes for Spring Boot integration.

=== Sources and contributions

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

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.jaxrs</groupId>
<artifactId>holon-jaxrs-bom</artifactId>
<version>{revnumber}</version>
{'fraction_non_alphanumeric': 0.08316008316008316, 'fraction_numerical': 0.0029106029106029108, 'mean_word_length': 5.419928825622776, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4041316', 'n_tokens_mistral': 1994, 'n_tokens_neox': 1882, 'n_words': 822}