Added doc entry for the new option

Added doc entry for the new option

// Allow GitHub image rendering
:imagesdir: ../../../images
=== Heatmap

The _Heatmap_ can be either be used to display unacknowledged alarms or to display ongoing outages
of nodes. Each of this visualizations can be applied either on categories or on foreign sources of
nodes. The sizing of an entity is calculated by counting the monitored services inside the entity.
Thus, a node with fewer services will appear in a smaller box than a node with more services.

The feature is by default deactivated and is configured through `opennms.properties`.

.Heatmap visualizations of alarms
image:webui/heatmap/heatmap.png[]

.Grafana Dashboard configuration properties
[options="header, autowidth"]
|===
| Name                                       | Type      | Description                                                  | Default
| `org.opennms.heatmap.defaultMode`          | _String_  | There exist two options for using the heatmap: `alarms` and
                                                           `outages`. This option configures which are displayed per
                                                           default.
                                                                                | `alarms`
| `org.opennms.heatmap.defaultHeatmap`       | _String_  | This option defines which _Heatmap_ is displayed by default.
                                                           The two valid options are `categories` or `foreignSources`   | `categories`
| `org.opennms.heatmap.categoryFilter`       | _String_  | The following option is used to filter for categories to be
                                                           displayed in the _Heatmap_. This option uses the Java regular
                                                           expression syntax. The default is `.*` so all categories will
                                                           be displayed.                                                | `.*`
| `org.opennms.heatmap.foreignSourceFilter`  | _String_  | The following option is used to filter for foreign sources
                                                           to be displayed in the _Heatmap_. This option uses the Java
                                                           regular expression syntax. The default is `.*` so all foreign
                                                           sources will be displayed.                                   | `.*`
| `org.opennms.heatmap.onlyUnacknowledged`   | _Boolean_ | This option configures whether only unacknowledged alarms
                                                           will be taken into account when generating the alarm-based
                                                           version of the _Heatmap_.                                    | `false`
| `org.opennms.web.console.centerUrl`        | _String_  |  You can also place the _Heatmap_ on the landing page by
                                                           setting this option to `/heatmap/heatmap-box.jsp`.           | `/surveillance-box.jsp`
|===

TIP: You can use negative lookahead expressions for excluding categories you wish not to be displayed in the heatmap,
e.g. by using an expression like `^(?!XY).*` you can filter out entities with names starting with `XY`.

// Allow GitHub image rendering
:imagesdir: ../../../images
=== Heatmap

The _Heatmap_ can be either be used to display unacknowledged alarms or to display ongoing outages
of nodes. Each of this visualizations can be applied either on categories or on foreign sources of
nodes. The sizing of an entity is calculated by counting the monitored services inside the entity.
Thus, a node with fewer services will appear in a smaller box than a node with more services.

The feature is by default deactivated and is configured through `opennms.properties`.

.Heatmap visualizations of alarms
image:webui/heatmap/heatmap.png[]

.Grafana Dashboard configuration properties
[options="header, autowidth"]
|===
| Name                                       | Type      | Description                                                  | Default
| `org.opennms.heatmap.defaultMode`          | _String_  | There exist two options for using the heatmap: `alarms` and
                                                           `outages`. This option configures which are displayed per
                                                           default.
                                                                                | `alarms`
| `org.opennms.heatmap.defaultHeatmap`       | _String_  | This option defines which _Heatmap_ is displayed by default.
                                                           The two valid options are `categories` or `foreignSources`   | `categories`
| `org.opennms.heatmap.categoryFilter`       | _String_ |  The following option is used to filter for categories to be
                                                           displayed in the _Heatmap_. This option uses the Java regular
                                                           expression syntax. The default is `.*` so all categories will
                                                           be displayed.                                                | `.*`
| `org.opennms.heatmap.foreignSourceFilter`  | _String_ |  The following option is used to filter for foreign sources
                                                           to be displayed in the _Heatmap_. This option uses the Java
                                                           regular expression syntax. The default is `.*` so all foreign
                                                           sources will be displayed.                                   | `.*`
| `org.opennms.web.console.centerUrl`        | _String_ |  You can also place the _Heatmap_ on the landing page by
                                                           setting this option to `/heatmap/heatmap-box.jsp`.           | `/surveillance-box.jsp`
|===

TIP: You can use negative lookahead expressions for excluding categories you wish not to be displayed in the heatmap,
e.g. by using an expression like `^(?!XY).*` you can filter out entities with names starting with `XY`.


DBZ-271 Switching to "one sentence per line" style to facilite diffs of later changes

= Avro Serialization
:awestruct-layout: doc
:linkattrs:
:icons: font
:source-highlighter: highlight.js

Debezium connectors are used with the Kafka Connect framework to capture changes in databases and generate change events.
The Kafka Connect workers then apply to each of the messages generated by the connector the transformations configured for the connector,
serialize each message key and value into a binary form using the worker's http://docs.confluent.io/current/connect/concepts.html#connect-converters[_converters_],
and finally write each messages into the correct Kafka topic.

The converters are specified in the the Kafka Connect worker configuration, and the same converters are used for all connectors deployed to that worker's cluster.
Kafka Connect comes with a _JSON converter_ that serialize the message keys and values into JSON documents,
and the JSON converter can be configured to include or exclude the message schema using the (`key.converter.schemas.enable` and `value.converter.schemas.enable`) properties.
Our link:/docs/tutorial[tutorial] shows what the messages look like when both payload and schemas are included, but the schemas make the messages very verbose.
If you want your messages serialized with JSON, consider setting these properties to `false` to exclude the verbose schema information.

Another option is to serialize the message keys and values using https://avro.apache.org/[Apache Avro].
The Avro binary format is extremely compact and efficient, and Avro schemas make it possible to ensure that the messages have the correct structure.
Avro's schema evolution mechanism makes it possible to evolve the schemas over time,
which is essential for Debezium connectors that dynamically generate the message schemas to match the structure of the database tables.
Over time, the change events captured by Debezium connectors and written by Kafka Connect into a topic may have different versions of the same schema,
and Avro serialization makes it far easier for consumers to adapt to the changing schema.

Confluent provides http://docs.confluent.io/current/schema-registry/docs/index.html[several components] that work with Avro:
 * An Avro Converter that can be used in Kafka Connect workers to map the Kafka Connect schemas into Avro schemas and to then use those Avro schemas to serialize the message keys and values into the very compact Avro binary form.
 * A Schema Registry that tracks all of the Avro schemas used in Kafka topics, and where the Avro Converter sends the generated Avro schemas.
 Since the Avro schemas are stored in this registry, each message need only include a tiny _schema identifier_.
 This makes each message even smaller, and for an I/O bound system like Kafka this means more total throughput of the producers and consumers.
 * Avro _serdes_ (serializers and deserializers) for Kafka producers and consumers.
 Any Kafka consumer applications you write to consume change events can use the Avro serdes to deserialize the changes events.

These Confluent components are open source, and you can install them into any Kafka distribution and use them with Kafka Connect.
However, Confluent also provides a https://www.confluent.io/product/confluent-open-source/[Confluent Open Source Platform] that includes the standard Kafka distribution as well as these and other Confluent open source components, including several source and sink connectors.
Some Docker images for Kafka Connect also contain the Avro converter. This includes recent link:/docs/docker/[Debezium Docker images] that include the Debezium connectors, Kafka Connect, and the Avro converter.

== Technical information
A system that wants to use Avro serialization needs to complete two steps

* Deploy a https://github.com/confluentinc/schema-registry[Schema Registry] instance
* Use these properties to configure Apache Connect instance
[source]
----
key.converter=io.confluent.connect.avro.AvroConverter
key.converter.schema.registry.url=http://localhost:8081
value.converter=io.confluent.connect.avro.AvroConverter
value.converter.schema.registry.url=http://localhost:8081
----
Note: In addition to setting key/value converters,it is *strongly recommended* to set internal key/value converters to use JSON converters for easier analysis of stored configuration and offsets.
If you would still prefer to use Avro converter it is not possible now due to a https://issues.apache.org/jira/browse/KAFKA-3988[known issue].
[source]
----
internal.key.converter=org.apache.kafka.connect.json.JsonConverter
internal.value.converter=org.apache.kafka.connect.json.JsonConverter
----

== Debezium Docker Images
Deploy a Schema Registry instance
[source]
----
docker run -it --rm --name schema-registry \
    --link zookeeper \
    -e SCHEMA_REGISTRY_KAFKASTORE_CONNECTION_URL=zookeeper:2181 \
    -e SCHEMA_REGISTRY_HOST_NAME=schema-registry \
    -e SCHEMA_REGISTRY_LISTENERS=http://schema-registry:8081 \
    -p 8181:8181 confluentinc/cp-schema-registry
----
Run a Kafka Connect image configured to use Avro
[source]
----
docker run -it --rm --name connect \
    --link zookeeper:zookeeper \
    --link kafka:kafka \
    --link mysql:mysql \
    --link schema-registry:schema-registry \
    -e GROUP_ID=1 \
    -e CONFIG_STORAGE_TOPIC=my_connect_configs \
    -e OFFSET_STORAGE_TOPIC=my_connect_offsets \
    -e CONNECT_KEY_CONVERTER=io.confluent.connect.avro.AvroConverter \
    -e CONNECT_VALUE_CONVERTER=io.confluent.connect.avro.AvroConverter \
    -e CONNECT_INTERNAL_KEY_CONVERTER=org.apache.kafka.connect.json.JsonConverter \
    -e CONNECT_INTERNAL_VALUE_CONVERTER=org.apache.kafka.connect.json.JsonConverter \
    -e CONNECT_KEY_CONVERTER_SCHEMA_REGISTRY_URL=http://schema-registry:8081 \
    -e CONNECT_VALUE_CONVERTER_SCHEMA_REGISTRY_URL=http://schema-registry:8081 \
    -p 8083:8083 debezium/connect:0.5
----

== Confluent Open Source
Please refer to http://docs.confluent.io/current/connect/quickstart.html#goal-of-this-quickstart[a quickstart] in Confluent's documentation.


Fix api location

Fix api location

= Holon JAX-RS integration
:revnumber: {project-version}
:apidir: ../api/holon-jax-rs
:linkattrs:
:sectnums:
:nofooter:
:toc: left
:toclevels: 3

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

== Introduction

The introduction goes here.

== System requirements

=== Java

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

= Holon JAX-RS integration
:revnumber: {project-version}
:apidir: ../../api/holon-jax-rs
:linkattrs:
:sectnums:
:nofooter:
:toc: left
:toclevels: 3

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

== Introduction

The introduction goes here.

== System requirements

=== Java

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