UNOMI-960: API Javadoc, manual docs, and validation tooling

CLAUDE.md

@@ -17,8 +17,10 @@ limitations under the License.
 # Apache Unomi — CLAUDE.md
 
 Apache Unomi is a Java/OSGi customer data platform running on Apache Karaf. Multi-module Maven
-reactor; most runtime code is packaged as OSGi bundles wired via Blueprint XML
-(`OSGI-INF/blueprint/blueprint.xml` in each module), not Spring/CDI.
+reactor; runtime code is packaged as OSGi bundles. **New code uses OSGi Declarative Services**
+(`@Component`, `@Reference`, `@Activate`). Legacy modules still ship Blueprint XML
+(`OSGI-INF/blueprint/blueprint.xml`) during migration — do not add new Blueprint files; see
+`CODING_GUIDELINES.md` and `manual/.../writing-plugins.adoc`.
 
 ## Dual persistence backends — the #1 thing to know
 

README.md

@@ -39,6 +39,16 @@ Branches
 compile and be stable. These are recommended for users that prefer to work from the source code. Otherwise you can find 
 packaged binaries on the [Apache Unomi website](https://unomi.apache.org). 
 
+
+Apache Unomi 3.x
+--------------
+Unomi 3.0+ requires **Java 17**, **Karaf 4.4**, and **Elasticsearch 9.x**. Unomi 3.1 adds **multi-tenancy**, **OpenSearch 3** support, a cluster-aware **task scheduler**, and persistence-based clustering.
+
+* Build and run: see `manual/src/main/asciidoc/building-and-deploying.adoc` or `manual/src/main/asciidoc/5-min-quickstart.adoc`
+* Docker: see `docker/README.md`
+* Multi-tenancy and API keys: see `manual/src/main/asciidoc/multitenancy.adoc`
+* Migrations: see `manual/src/main/asciidoc/migrations/migrations.adoc`
+
 Documentation
 -------------
 You can find all the updated documentation, including building and deployment instructions, on the [Apache Unomi 

api/src/main/java/org/apache/unomi/api/BatchUpdate.java

@@ -20,7 +20,10 @@
 import org.apache.unomi.api.conditions.Condition;
 
 /**
- * A representation of an operation to update the value of a property on items matching a specific condition.
+ * Bulk property update specification executed as a scroll query.
+ * Selects items with a {@link org.apache.unomi.api.conditions.Condition}, sets one
+ * property (Apache Commons BeanUtils expression) to a new value, and optionally
+ * applies a {@link PropertyMergeStrategyType} when merging complex fields.
  */
 public class BatchUpdate {
     private String propertyName;
@@ -31,11 +34,10 @@ public class BatchUpdate {
     private int scrollBatchSize = 1000;
 
     /**
-     * Retrieves the property name which value needs to be updated. Note that the property name follows the
-     * <a href='https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils/expression/DefaultResolver.html'>Apache Commons BeanUtils expression
-     * format</a>
+     * Property to update, as an Apache Commons BeanUtils expression
+     * (see <a href="https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils/expression/DefaultResolver.html">BeanUtils expression format</a>).
      *
-     * @return an Apache Commons BeanUtils expression identifying which property we want to update
+     * @return property expression to update
      */
     public String getPropertyName() {
         return propertyName;
@@ -51,7 +53,7 @@ public void setPropertyName(String propertyName) {
     }
 
     /**
-     * Retrieves the new property value.
+     * New value to assign to the property.
      *
      * @return the new property value
      */
@@ -69,7 +71,7 @@ public void setPropertyValue(Object propertyValue) {
     }
 
     /**
-     * Retrieves the condition which items we want to update must satisfy.
+     * Condition that items must match to be updated.
      *
      * @return the condition which items we want to update must satisfy
      */
@@ -87,7 +89,7 @@ public void setCondition(Condition condition) {
     }
 
     /**
-     * Retrieves the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed.
+     * {@link PropertyMergeStrategyType} id to use when merging the new value.
      *
      * @return the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed
      */

api/src/main/java/org/apache/unomi/api/ClusterNode.java

@@ -18,13 +18,17 @@
 package org.apache.unomi.api;
 
 /**
- * Information about a cluster node.
+ * Runtime snapshot of one Apache Unomi node in a cluster.
+ * Stores health and topology flags such as load averages, addresses, uptime,
+ * and whether the node is a master (coordination only) or data node (stores
+ * context data). Cluster services publish these objects so operators can
+ * inspect cluster state.
  */
 public class ClusterNode extends Item {
 
     private static final long serialVersionUID = 1281422346318230514L;
 
-    // Item type identifier for cluster nodes.
+    /** Item type identifier for cluster nodes. */
     public static final String ITEM_TYPE = "clusterNode";
 
     private double cpuLoad;
@@ -41,35 +45,35 @@ public class ClusterNode extends Item {
     private ServerInfo serverInfo;
 
     /**
-     * Instantiates a new Cluster node.
+     * Creates an empty cluster node with item type {@link #ITEM_TYPE}.
      */
     public ClusterNode() {
         super();
         setItemType(ITEM_TYPE);
     }
 
     /**
-     * Retrieves the cpu load.
+     * Current CPU load on this node.
      *
-     * @return the cpu load
+     * @return CPU load
      */
     public double getCpuLoad() {
         return cpuLoad;
     }
 
     /**
-     * Sets the cpu load.
+     * Sets the CPU load.
      *
-     * @param cpuLoad the cpu load
+     * @param cpuLoad CPU load
      */
     public void setCpuLoad(double cpuLoad) {
         this.cpuLoad = cpuLoad;
     }
 
     /**
-     * Retrieves the public host address.
+     * Public host address clients use to reach this node.
      *
-     * @return the public host address
+     * @return public host address
      */
     public String getPublicHostAddress() {
         return publicHostAddress;
@@ -78,151 +82,151 @@ public String getPublicHostAddress() {
     /**
      * Sets the public host address.
      *
-     * @param publicHostAddress the public host address
+     * @param publicHostAddress public host address
      */
     public void setPublicHostAddress(String publicHostAddress) {
         this.publicHostAddress = publicHostAddress;
     }
 
     /**
-     * Retrieves the internal host address which uses the HTTP/HTTPS protocol for communications between clients and the context server.
+     * Internal HTTP/HTTPS address used for client-to-server communication.
      *
-     * @return the internal host address
+     * @return internal host address
      */
     public String getInternalHostAddress() {
         return internalHostAddress;
     }
 
     /**
-     * Sets the internal host address which uses the HTTP/HTTPS protocol for communications between clients and the context server.
+     * Sets the internal HTTP/HTTPS host address.
      *
-     * @param internalHostAddress the internal host address
+     * @param internalHostAddress internal host address
      */
     public void setInternalHostAddress(String internalHostAddress) {
         this.internalHostAddress = internalHostAddress;
     }
 
     /**
-     * Retrieves the load average for the last minute, five minutes and fifteen minutes.
+     * Load averages for the last 1, 5, and 15 minutes.
      *
-     * @return an array of {@code double} containing, in order and starting from index {@code 0}, the load average for the last minute, last five minutes and last fifteen minutes
+     * @return three-element array: index 0 = 1 min, 1 = 5 min, 2 = 15 min
      */
     public double[] getLoadAverage() {
         return loadAverage;
     }
 
     /**
-     * Sets the load average for the last minute, five minutes and fifteen minutes.
+     * Sets load averages for the last 1, 5, and 15 minutes.
      *
-     * @param loadAverage an array of {@code double} containing, in order and starting from index {@code 0}, the load average for the last minute, last five minutes and last fifteen minutes
+     * @param loadAverage three-element array: index 0 = 1 min, 1 = 5 min, 2 = 15 min
      */
     public void setLoadAverage(double[] loadAverage) {
         this.loadAverage = loadAverage;
     }
 
     /**
-     * Retrieves the uptime.
+     * Node uptime in milliseconds.
      *
-     * @return the uptime
+     * @return uptime
      */
     public long getUptime() {
         return uptime;
     }
 
     /**
-     * Sets the uptime.
+     * Sets the node uptime.
      *
-     * @param uptime the uptime
+     * @param uptime uptime in milliseconds
      */
     public void setUptime(long uptime) {
         this.uptime = uptime;
     }
 
     /**
-     * Determines whether this ClusterNode is a master node, i.e. this node doesn't store any data but is only focused on cluster management operations.
+     * Whether this node is a master (coordination only, no local context data).
      *
-     * @return {@code true} if this node is a master node, {@code false} otherwise
+     * @return {@code true} if this is a master node
      */
     public boolean isMaster() {
         return master;
     }
 
     /**
-     * Specifies whether this ClusterNode is a master node, i.e. this node doesn't store any data but is only focused on cluster management operations..
+     * Sets whether this node is a master (coordination only, no local context data).
      *
-     * @param master {@code true} if this node is a master node, {@code false} otherwise
+     * @param master {@code true} for a master node
      */
     public void setMaster(boolean master) {
         this.master = master;
     }
 
     /**
-     * Determines whether this ClusterNode locally stores data.
+     * Whether this node stores context data locally.
      *
-     * @return {@code true} if this node locally stores data, {@code false} otherwise
+     * @return {@code true} if this is a data node
      */
     public boolean isData() {
         return data;
     }
 
     /**
-     * Specifies whether this ClusterNode locally stores data.
+     * Sets whether this node stores context data locally.
      *
-     * @param data {@code true} if this node locally stores data, {@code false} otherwise
+     * @param data {@code true} for a data node
      */
     public void setData(boolean data) {
         this.data = data;
     }
 
     /**
-     * Retrieves the node start time in milliseconds.
+     * When this node started (milliseconds since epoch).
      *
-     * @return the start time
+     * @return start time
      */
     public long getStartTime() {
         return startTime;
     }
 
     /**
-     * Sets the node start time in milliseconds.
+     * Sets the node start time.
      *
-     * @param startTime the start time
+     * @param startTime start time in milliseconds
      */
     public void setStartTime(long startTime) {
         this.startTime = startTime;
     }
 
     /**
-     * Retrieves the last heartbeat time in milliseconds.
+     * When this node last sent a heartbeat (milliseconds since epoch).
      *
-     * @return the last heartbeat time
+     * @return last heartbeat time
      */
     public long getLastHeartbeat() {
         return lastHeartbeat;
     }
 
     /**
-     * Sets the last heartbeat time in milliseconds.
+     * Sets the last heartbeat time.
      *
-     * @param lastHeartbeat the last heartbeat time
+     * @param lastHeartbeat last heartbeat time in milliseconds
      */
     public void setLastHeartbeat(long lastHeartbeat) {
         this.lastHeartbeat = lastHeartbeat;
     }
 
     /**
-     * Gets the server information.
+     * Build and capability details for this node.
      *
-     * @return the server information
+     * @return server information
      */
     public ServerInfo getServerInfo() {
         return serverInfo;
     }
 
     /**
-     * Sets the server information.
+     * Sets the server information for this node.
      *
-     * @param serverInfo the server information
+     * @param serverInfo server information
      */
     public void setServerInfo(ServerInfo serverInfo) {
         this.serverInfo = serverInfo;