This is an automated email from the ASF dual-hosted git repository. jkevan pushed a commit to branch UNOMI-225-ES7-documentation in repository https://gitbox.apache.org/repos/asf/unomi.git
commit 926388b97a8dde8e445bf8f056577f303e080830 Author: Kevan <[email protected]> AuthorDate: Fri Nov 22 18:08:47 2019 +0100 Provide documentation for ES7 support and Data model changes --- manual/src/main/asciidoc/5-min-quickstart.adoc | 2 +- .../src/main/asciidoc/building-and-deploying.adoc | 1 + manual/src/main/asciidoc/index.adoc | 2 + manual/src/main/asciidoc/new-data-model.adoc | 52 ++++++++++++++++++++++ 4 files changed, 56 insertions(+), 1 deletion(-) diff --git a/manual/src/main/asciidoc/5-min-quickstart.adoc b/manual/src/main/asciidoc/5-min-quickstart.adoc index 0e5fc4e..6469cbc 100644 --- a/manual/src/main/asciidoc/5-min-quickstart.adoc +++ b/manual/src/main/asciidoc/5-min-quickstart.adoc @@ -16,7 +16,7 @@ 1) Install JDK 8 (http://www.oracle.com/technetwork/java/javase/downloads/index.html) and make sure you set the JAVA_HOME variable https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ -2) Download ElasticSearch here : https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3 (please <strong>make sure</strong> you use the proper version : 5.6.3) +2) Download ElasticSearch here : https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2 (please <strong>make sure</strong> you use the proper version : 7.4.2) 3) Uncompress it and change the `config/elasticsearch.yml` to include the following config : <code>cluster.name: contextElasticSearch</code> diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc index cf34343..0430503 100644 --- a/manual/src/main/asciidoc/building-and-deploying.adoc +++ b/manual/src/main/asciidoc/building-and-deploying.adoc @@ -61,6 +61,7 @@ on your version of Apache Unomi. Apache Unomi <= 1.2 : https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2[https://www.elastic.co/downloads/past-releases/elasticsearch-5-1-2] Apache Unomi >= 1.3 : https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3[https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3] +Apache Unomi >= 1.5 : https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2[https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2] Uncompress the downloaded package into a directory diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index 4f1f2b2..8c89727 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -103,3 +103,5 @@ include::extending-plugins.adoc[] include::custom-extensions.adoc[] include::patches.adoc[] + +include::new-data-model.adoc[] \ No newline at end of file diff --git a/manual/src/main/asciidoc/new-data-model.adoc b/manual/src/main/asciidoc/new-data-model.adoc new file mode 100644 index 0000000..e33e0e2 --- /dev/null +++ b/manual/src/main/asciidoc/new-data-model.adoc @@ -0,0 +1,52 @@ +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +=== Data Model changes for Apache Unomi 1.5.0 + +==== Data model and ElasticSearch 7 + +Since Apache Unomi version 1.5.0 we decided to upgrade the supported ElasticSearch version to the latest 7.4.2. + +To be able to do so, we had to rework the way the data was stored inside ElasticSearch. + +Previously every items was stored inside the same ElasticSearch index but this is not allowed anymore in recent ElasticSearch versions. + +Since Apache Unomi version 1.5.0 every type of items (see section: link:#_items_and_types[Items and types]) is now stored in a dedicated separated index. + + +==== API changes + +To be able to handle the multiple indices the Persistence API implementation +(https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/persistence-elasticsearch/core/src/main/java/org/apache/unomi/persistence/elasticsearch/ElasticSearchPersistenceServiceImpl.java[ElasticSearchPersistenceServiceImpl]) +have been adapted and simplified. + +The good news is that there is no API changes, the persistence API interface didn't changed. + +Any custom Apache Unomi plugins or extensions should continue to work on Apache Unomi 1.5.0. + +The only notable changes are located at the +https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/persistence-elasticsearch/core/src/main/java/org/apache/unomi/persistence/elasticsearch/ElasticSearchPersistenceServiceImpl.java[ElasticSearchPersistenceServiceImpl Java class]. +This class should not be use directly, instead you should use OSGI service dependency injection using the interface https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/persistence-spi/src/main/java/org/apache/unomi/persistence/spi/PersistenceService.java[PersistenceService]. + +But if you are interested in the implementation changes: + +. The property `index.name` have been renamed to `index.prefix`. +Previously used for the single one index name, now every index is prefixed using this property. (`context-` by default) +. We removed the property `index.names` originally used to create additional indices (used by the geonames DB for exemple). +This property is not needed anymore because the index is automatically created by the peristence service when the mapping configuration is loaded. +Example of mapping configuration file: (https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/extensions/geonames/services/src/main/resources/META-INF/cxs/mappings/geonameEntry.json[geoname index mapping]) + +Because of this changes the geonames DB index name is now respecting the index naming with prefix like any other item type. +Previously named: `geonames` is now using the index name `context-geonameentry` +(see: link:#_installing_geonames_database[Documentation about geonames extension]). \ No newline at end of file
