UNOMI-892-maven-cache: Adopt Maven Build Cache, consolidate BUILDING into manual, update website docs

.mvn/extensions.xml

@@ -20,6 +20,11 @@
 
 -->
 <extensions>
+    <extension>
+        <groupId>org.apache.maven.extensions</groupId>
+        <artifactId>maven-build-cache-extension</artifactId>
+        <version>1.2.1</version>
+    </extension>
     <extension>
         <groupId>com.gradle</groupId>
         <artifactId>develocity-maven-extension</artifactId>

.mvn/maven-build-cache-config.xml

@@ -0,0 +1,43 @@
+<!-- -
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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.
+ -->
+<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
+    <configuration>
+        <enabled>true</enabled>
+        <hashAlgorithm>SHA-256</hashAlgorithm>
+        <validateXml>true</validateXml>
+        <remote enabled="false">
+            <url>http://host:port</url>
+        </remote>
+        <local>
+            <maxBuildsCached>3</maxBuildsCached>
+        </local>
+        <projectVersioning adjustMetaInf="true" />
+    </configuration>
+    <input>
+        <global>
+            <includes>
+                <include>src/</include>
+            </includes>
+            <excludes>
+                <exclude>pom.xml</exclude>
+                <exclude>src/main/javagen/**</exclude>
+            </excludes>
+        </global>
+    </input>
+</cache>

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "java.compile.nullAnalysis.mode": "automatic"
+}

BUILDING

@@ -18,74 +18,10 @@
 Building Apache Unomi
 =====================
 
-Initial Setup
--------------
+This file has been deprecated to avoid duplication. Please use the online manual for up-to-date instructions:
 
-1) Install J2SE 17 SDK (or later), which can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html
+  Online manual (Building): https://unomi.apache.org/manual/latest/index.html#_building
 
-2) Make sure that your JAVA_HOME environment variable is set to the newly installed
-   JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or
-   $JAVA_HOME$/bin (unix).
+To propose edits to the build documentation, update the source Asciidoc here:
 
-3) Install Maven 3.0.3 (or later), which can be downloaded from
-   http://maven.apache.org/download.html. Make sure that your PATH includes
-   the MVN_HOME/bin directory.
-
-
-Building
---------
-
-1) Change to the top level directory of Apache Unomi source distribution.
-2) Run
-
-         $> mvn clean install
-
-   This will compile Apache Unomi and run all of the tests in the
-   Apache Unomi source distribution. Alternatively, you can run
-
-         $> mvn -P \!integration-tests clean install
-
-   This will compile Apache Unomi without running the tests and takes less
-   time to build.
-
-3) The distributions will be available under "package/target" directory.
-
-Updating the website
---------------------
-
-We provide two scripts to generate the website and upload the modifications
-to the live SVN repository. To generate the website and check if everything is in
-place simply launch:
-
-    ./generate-site.sh
-
-The generated site will then be in the target/site directory
-
-Once it is ready to be published to the live site, simply use the following
-command:
-
-    ./generate-site-and-upload.sh SVNusername SVNpassword
-
-Where the required username and password have the proper credentials for the SVN
-Apache repository.
-
-JGitFlow
---------
-
-We now can use the [JGitFlow Maven plugin](http://jgitflow.bitbucket.org) to make it easier to work with feature,
-hotfix and other types of branches.
-
-For example, to start a feature branch, simply use
-
-    mvn jgitflow:feature-start
-
-This will prompt you for the feature name, and then create a feature branch and update
-all the POMs to have a version that contains the feature name. This makes it then a lot
-easier to integrate with continuous integration systems to generate builds for the
-feature branch.
-
-Once the feature is completed you can use
-
-    mvn jgitflow:feature-finish
-
-To merge the branch into master.
+  manual/src/main/asciidoc/building-and-deploying.adoc

manual/src/main/asciidoc/building-and-deploying.adoc

@@ -28,7 +28,7 @@ directly as described in this section.
  JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or
  $JAVA_HOME$/bin (unix).
 
-. Install Maven 3.9.6 (or later), which can be downloaded from
+. Install Maven 3.9.8 (or later), which can be downloaded from
  http://maven.apache.org/download.html[http://maven.apache.org/download.html]. Make sure that your PATH includes
  the MVN_HOME/bin directory.
 
@@ -159,6 +159,103 @@ export NO_COLOR=1
 +
 For a complete list of options and examples, run `./build.sh --help`.
 
+==== Updating the website
+
+Use the top-level `generate-manual.sh` script to generate and publish the documentation website.
+
+[source]
+----
+./generate-manual.sh publish <svn_user> <svn_pass>
+./generate-manual.sh simulate <svn_user> <svn_pass>
+----
+
+Modes:
+
+* `publish`: generates all documentation and publishes to Apache SVN
+** Generates exactly 2 versions (latest + stable)
+** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master
+** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches
+** Removes old versions automatically on the website
+
+* `simulate`: dry-run; prints the commands without making changes
+
+Requirements:
+
+* Java 17+, Maven 3.6+, Git, SVN client, `bc`
+* Access to the `master` and the stable branch configured in `generate-manual-config.sh`
+
+Outputs and locations:
+
+* Staging directories under `target/generated-docs/` (created by the build)
+* Website content committed to `$SVN_WEBSITE_BASE/manual/<version>`
+* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/<version>`
+
+Notes:
+
+* The script sources optional `generate-manual-config.sh` and `shell-utils.sh` for configuration/utilities.
+* Javadoc aggregation is attempted; if it fails (toolchain mismatch), the rest still publishes.
+
+==== JGitFlow
+
+You can use the https://jgitflow.bitbucket.org[JGitFlow Maven plugin] to work with feature, hotfix and other types of branches.
+
+For example, to start a feature branch, simply use:
+
+[source]
+----
+mvn jgitflow:feature-start
+----
+
+This will prompt you for the feature name, and then create a feature branch and update all the POMs to have a version that contains the feature name. This makes it easier to integrate with continuous integration systems to generate builds for the feature branch.
+
+Once the feature is completed you can use:
+
+[source]
+----
+mvn jgitflow:feature-finish
+----
+
+To merge the branch into master.
+
+==== Maven Build Cache
+
+Apache Unomi uses the Maven Build Cache extension to significantly improve build efficiency by caching compiled artifacts and avoiding unnecessary recompilation (build time without/with cached artifacts ~2mn/~3s).
+
+The build cache is enabled by default and configured in the `.mvn/maven-build-cache-config.xml` file. The cache configuration includes:
+
+* Local caching with up to 3 builds cached
+* SHA-256 hash algorithm for cache keys
+* Includes all source directories (`src/`)
+* Excludes `pom.xml` files and generated sources (`src/main/javagen/**`)
+
+Command line control:
+
+* Disable cache: `mvn -Dmaven.build.cache.enabled=false clean install`
+  ** Completely turns off the build cache functionality
+  ** Maven will not store or retrieve any build outputs from the cache
+  ** Performs a full build as if the cache were not present
+  ** Use this when you want to ensure no cache influence on the build
+
+* Skip cache (force rebuild): `mvn -Dmaven.build.cache.skipCache=true clean install`
+  ** Skips looking up artifacts in caches but still writes new results to cache
+  ** Forces Maven to rebuild everything without using cached artifacts
+  ** New build results will be stored in cache for future builds
+  ** Use this to force a complete rebuild while keeping cache functionality active
+
+* Enable cache (default): `mvn -Dmaven.build.cache.enabled=true clean install`
+  ** Enables full cache functionality (read and write)
+  ** Maven will use cached artifacts when available and store new results
+  ** This is the default behavior when the cache is enabled
+
+Purging the build cache:
+
+To completely reset the build cache and force a full rebuild, manually delete the cache directory: `rm -rf ~/.m2/build-cache` (Unix/Mac) or `rmdir /s %USERPROFILE%\.m2\build-cache` (Windows)
+
+For more information, see the official documentation:
+
+* https://maven.apache.org/extensions/maven-build-cache-extension/[Maven Build Cache Extension Overview]
+* https://maven.apache.org/extensions/maven-build-cache-extension/parameters.html[Build Cache Parameters Reference]
+
 ==== Installing an ElasticSearch server
 
 Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch server as this is no longer supported by