UNOMI-259
- Update documentation for JDK 11 & ElasticSearch 7
Signed-off-by: Serge Huber <shuber@apache.org>
diff --git a/manual/pom.xml b/manual/pom.xml
index f18ed7e..71d44d6 100644
--- a/manual/pom.xml
+++ b/manual/pom.xml
@@ -44,7 +44,7 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
- <version>1.5.7.1</version>
+ <version>1.6.0</version>
<executions>
<execution>
<id>output-html</id>
@@ -85,12 +85,12 @@
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
- <version>1.5.7.1</version>
+ <version>1.6.0</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
- <version>1.5.0-alpha.16</version>
+ <version>1.5.0-rc.1</version>
</dependency>
</dependencies>
<executions>
diff --git a/manual/src/main/asciidoc/5-min-quickstart.adoc b/manual/src/main/asciidoc/5-min-quickstart.adoc
index 6469cbc..98982f3 100644
--- a/manual/src/main/asciidoc/5-min-quickstart.adoc
+++ b/manual/src/main/asciidoc/5-min-quickstart.adoc
@@ -13,8 +13,8 @@
//
=== Five Minutes QuickStart
-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/
+1) Install JDK 8 (https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) and make sure you set the
+JAVA_HOME variable https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ (see our <<_jdk_compatibility,Getting Started>> guide for more information on JDK compatibility)
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)
@@ -36,3 +36,9 @@
11) If something goes wrong, you should check the logs in `./data/log/karaf.log`. If you get errors on ElasticSearch,
make sure you are using the proper version.
+
+Next steps:
+
+- Connect to http://localhost:8181 to try our some live examples (such as the web tracker)
+- Trying our integration <<_samples,samples page>>
+- Learning more about the <<_web_tracker,web tracker>>
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc
index 0430503..ec74505 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -118,7 +118,7 @@
environment if you intend to re-deploy the context server KAR iteratively.
Additional requirements:
-* Apache Karaf 3.x, http://karaf.apache.org[http://karaf.apache.org]
+* Apache Karaf 4.2.x, http://karaf.apache.org[http://karaf.apache.org]
Before deploying, make sure that you have Apache Karaf properly installed. You will also have to increase the
default maximum memory size and perm gen size by adjusting the following environment values in the bin/setenv(.bat)
@@ -136,8 +136,8 @@
[source]
----
- feature:repo-add cxf 3.0.2
- feature:repo-add cellar 3.0.3
+ feature:repo-add cxf-jaxrs 3.3.4
+ feature:repo-add cellar 4.1.3
feature:repo-add mvn:org.apache.unomi/unomi-kar/VERSION/xml/features
feature:install unomi-kar
----
@@ -166,21 +166,19 @@
[source]
----
-Matching Java Virtual Machines (7):
- 1.7.0_51, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_51.jdk/Contents/Home
- 1.7.0_45, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_45.jdk/Contents/Home
- 1.7.0_25, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_25.jdk/Contents/Home
- 1.6.0_65-b14-462, x86_64: "Java SE 6" /Library/Java/JavaVirtualMachines/1.6.0_65-b14-462.jdk/Contents/Home
- 1.6.0_65-b14-462, i386: "Java SE 6" /Library/Java/JavaVirtualMachines/1.6.0_65-b14-462.jdk/Contents/Home
- 1.6.0_65-b14-462, x86_64: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
- 1.6.0_65-b14-462, i386: "Java SE 6" /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
+Matching Java Virtual Machines (3):
+ 11.0.5, x86_64: "OpenJDK 11.0.5" /Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home
+ 1.8.0_181, x86_64: "Java SE 8" /Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home
+ 1.7.0_80, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
+
+/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home
----
You can then select the one you want using :
[source]
----
-export JAVA_HOME=`/usr/libexec/java_home -v 1.7.0_51`
+export JAVA_HOME=`/usr/libexec/java_home -v 1.8.0_181`
----
and then check that it was correctly referenced using:
@@ -194,9 +192,9 @@
[source]
----
-java version "1.7.0_51"
-Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
-Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
+openjdk version "11.0.5" 2019-10-15
+OpenJDK Runtime Environment (build 11.0.5+10)
+OpenJDK 64-Bit Server VM (build 11.0.5+10, mixed mode)
----
==== Running the integration tests
@@ -206,7 +204,7 @@
to use these tests is to run them from a continuous integration server such as Jenkins, Apache Gump, Atlassian Bamboo or
others.
-Note : the integration tests require a JDK 7 or more recent !
+Note : the integration tests require a JDK 8 or more recent !
To run the tests simply activate the following profile :
diff --git a/manual/src/main/asciidoc/getting-started.adoc b/manual/src/main/asciidoc/getting-started.adoc
index e478de6..d5fb13a 100644
--- a/manual/src/main/asciidoc/getting-started.adoc
+++ b/manual/src/main/asciidoc/getting-started.adoc
@@ -20,13 +20,33 @@
This document assumes that you are already familiar with Unomi's <<_concepts,concepts>>. On the technical side, we
also assume working knowledge of https://git-scm.com/[git] to be able to retrieve the code for Unomi and the example.
-Additionally, you will require a working Java 7 or above install. Refer to http://www.oracle.com/technetwork/java/javase/[http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 7 or greater.
+Additionally, you will require a working Java 8 or above install. Refer to http://www.oracle.com/technetwork/java/javase/[http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 8 or greater.
+
+===== JDK compatibility
+
+Starting with Java 9, Oracle made some big changes to the Java platform releases. This is why Apache Unomi is focused on
+supporting the Long Term Supported versions of the JDK, currently versions 8 and 11. We do not test with intermediate
+versions so they may or may not work properly. Currently the most tested version is version 8 and version 11 is also
+supported.
+
+Also, as there are new licensing restrictions on JDKs provided by Oracle for production usages, Apache Unomi has also
+added support for OpenJDK builds. Other JDK distributions might also work but are not regularly tested so you should use
+them at your own risks.
+
+===== ElasticSearch compatibility
+
+Starting with version 1.5.0 Apache Unomi adds compatibility with ElasticSearch 7.4 . It is highly recommended to use the
+ElasticSearch version provided by the documentation when possible. However minor versions (7.4.x) should also work, and
+one version higher (7.5) will usually work. Going higher than that is risky given the way that ElasticSearch is developed
+and breaking changes are introduced quite often. If in doubt, don't hesitate to check with the Apache Unomi community
+to get the latest information about ElasticSearch version compatibility.
==== Running Unomi
===== Start Unomi
-Start Unomi according to the <<_5-min-quickstart,5 minute quick start>> or by compiling using the building link:building-and-deploying.html#Deploying_the_generated_package[instructions]. Once you have Karaf running,
+Start Unomi according to the <<_five_minutes_quickstart,five minutes quick start>> or by compiling using the
+<<_building,building instructions>>. Once you have Karaf running,
you should wait until you see the following messages on the Karaf console:
[source]
@@ -44,5 +64,7 @@
This indicates that all the Unomi services are started and ready to react to requests. You can then open a browser and go to `http://localhost:8181/cxs` to see the list of
available RESTful services or retrieve an initial context at `http://localhost:8181/context.json` (which isn't very useful at this point).
-Now that your service is up and running you can go look at the <<_request-examples,request examples>> to learn basic
+You can now find an introduction page at the following location: http://localhost:8181
+
+Also now that your service is up and running you can go look at the <<_request-examples,request examples>> to learn basic
requests you can do once your server is up and running.
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/privacy.adoc b/manual/src/main/asciidoc/privacy.adoc
index 93eb353..c42842a 100644
--- a/manual/src/main/asciidoc/privacy.adoc
+++ b/manual/src/main/asciidoc/privacy.adoc
@@ -14,7 +14,7 @@
Apache Unomi provides an endpoint to manage visitor privacy. You will find in this section information about what it
includes as well as how to use it.
-==== Setting up access to the privacy endpoint
+=== Setting up access to the privacy endpoint
The privacy endpoint is a bit special, because despite being protected by basic authentication as the rest of the REST
API is is actually designed to be available to end-users.
@@ -29,7 +29,7 @@
geographic location)
2. proxy to /cxs/privacy
-==== Anonymizing a profile
+=== Anonymizing a profile
It is possible to anonymize a profile, meaning it will remove all "identifying" property values from the profile.
Basically all properties with the tag `personalIdentifierProperties` will be purged from the profile.
@@ -44,7 +44,7 @@
where `{profileID}` must be replaced by the actual identifier of a profile
and `ASCOPE` must be replaced by a scope identifier.
-==== Downloading profile data
+=== Downloading profile data
It is possible to download the profile data of a user. This will only download the profile for a user using the
specified ID as a cookie value.
@@ -61,7 +61,7 @@
where `PROFILE-ID` is the profile identifier for which to download the profile.
-==== Deleting a profile
+=== Deleting a profile
It is possible to delete a profile, but this works a little differently than you might expect. In all cases the data
contained in the profile will be completely erased. If the `withData` optional flag is set to true, all past event and
@@ -75,6 +75,6 @@
where `{profileID}` must be replaced by the actual identifier of a profile
and the `withData` specifies whether the data associated with the profile must be anonymized or not
-==== Related
+=== Related
You might also be interested in the <<Consent API>> section that describe how to manage profile consents.
diff --git a/manual/src/main/asciidoc/samples/twitter-sample.adoc b/manual/src/main/asciidoc/samples/twitter-sample.adoc
index ccd2828..bb4e505 100644
--- a/manual/src/main/asciidoc/samples/twitter-sample.adoc
+++ b/manual/src/main/asciidoc/samples/twitter-sample.adoc
@@ -174,7 +174,7 @@
Let's look at the context request structure:
-[source,json]
+[source]
----
{
source: <Item source of the context request>,
