You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@unomi.apache.org by sh...@apache.org on 2026/07/12 04:30:02 UTC
(unomi) branch UNOMI-960-javadoc-cleanup created (now c119f91b1)
This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a change to branch UNOMI-960-javadoc-cleanup
in repository https://gitbox.apache.org/repos/asf/unomi.git
at c119f91b1 UNOMI-960: Improve api Javadoc and add pragmatic validation tooling
This branch includes the following new commits:
new c119f91b1 UNOMI-960: Improve api Javadoc and add pragmatic validation tooling
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(unomi) 01/01: UNOMI-960: Improve api Javadoc and add pragmatic validation tooling
Posted by sh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
sergehuber pushed a commit to branch UNOMI-960-javadoc-cleanup
in repository https://gitbox.apache.org/repos/asf/unomi.git
commit c119f91b1c807a5454eb215a5723ed9c83fc7ebb
Author: Serge Huber <sh...@apache.org>
AuthorDate: Sun Jul 12 06:29:50 2026 +0200
UNOMI-960: Improve api Javadoc and add pragmatic validation tooling
Expand and fix public/protected Javadoc in the api module, configure
doclint to fail only on broken links/HTML/syntax, and add a Checkstyle
profile plus build.sh --javadoc two-pass checks for tag gaps on the
published API surface.
---
.../java/org/apache/unomi/api/BatchUpdate.java | 5 +-
.../java/org/apache/unomi/api/ClusterNode.java | 30 +--
.../java/org/apache/unomi/api/ConsentStatus.java | 11 +-
.../main/java/org/apache/unomi/api/CustomItem.java | 4 +-
.../main/java/org/apache/unomi/api/EventInfo.java | 23 ++-
.../java/org/apache/unomi/api/EventProperty.java | 6 +-
.../java/org/apache/unomi/api/EventSource.java | 41 ++++
.../java/org/apache/unomi/api/EventTarget.java | 37 ++++
.../apache/unomi/api/EventsCollectorRequest.java | 14 +-
.../org/apache/unomi/api/ExecutionContext.java | 79 ++++++-
.../main/java/org/apache/unomi/api/GeoPoint.java | 4 +-
api/src/main/java/org/apache/unomi/api/Item.java | 89 ++++++--
.../main/java/org/apache/unomi/api/Metadata.java | 35 +---
.../java/org/apache/unomi/api/MetadataItem.java | 28 ++-
.../main/java/org/apache/unomi/api/Parameter.java | 56 ++++-
.../java/org/apache/unomi/api/PartialList.java | 40 +++-
api/src/main/java/org/apache/unomi/api/Patch.java | 40 ++++
.../main/java/org/apache/unomi/api/Persona.java | 13 ++
.../java/org/apache/unomi/api/PersonaSession.java | 23 ++-
.../org/apache/unomi/api/PersonaWithSessions.java | 35 +++-
.../apache/unomi/api/PersonalizationResult.java | 48 ++++-
.../main/java/org/apache/unomi/api/PluginType.java | 4 +-
.../main/java/org/apache/unomi/api/Profile.java | 2 +
.../java/org/apache/unomi/api/ProfileAlias.java | 44 ++++
.../unomi/api/PropertyMergeStrategyExecutor.java | 4 +-
.../unomi/api/PropertyMergeStrategyType.java | 26 ++-
.../java/org/apache/unomi/api/PropertyType.java | 44 ++--
api/src/main/java/org/apache/unomi/api/Scope.java | 4 +-
.../main/java/org/apache/unomi/api/ServerInfo.java | 85 +++++++-
.../main/java/org/apache/unomi/api/Session.java | 10 +
.../org/apache/unomi/api/SystemPropertiesItem.java | 4 +-
.../java/org/apache/unomi/api/TimestampedItem.java | 4 +-
api/src/main/java/org/apache/unomi/api/Topic.java | 22 ++
.../main/java/org/apache/unomi/api/ValueType.java | 12 +-
.../apache/unomi/api/actions/ActionExecutor.java | 4 +-
.../unomi/api/actions/ActionPostExecutor.java | 4 +-
.../org/apache/unomi/api/actions/ActionType.java | 4 +-
.../org/apache/unomi/api/campaigns/Campaign.java | 4 +-
.../apache/unomi/api/campaigns/CampaignDetail.java | 6 +-
.../org/apache/unomi/api/conditions/Condition.java | 4 +-
.../unomi/api/conditions/ConditionValidation.java | 4 +-
.../exceptions/BadSegmentConditionException.java | 4 +-
.../main/java/org/apache/unomi/api/goals/Goal.java | 38 +++-
.../org/apache/unomi/api/goals/GoalReport.java | 75 ++++++-
.../java/org/apache/unomi/api/lists/UserList.java | 4 +-
.../java/org/apache/unomi/api/query/DateRange.java | 31 ++-
.../java/org/apache/unomi/api/query/IpRange.java | 31 ++-
.../org/apache/unomi/api/query/NumericRange.java | 32 ++-
.../java/org/apache/unomi/api/query/Query.java | 50 +++--
.../org/apache/unomi/api/rules/RuleStatistics.java | 12 +-
.../unomi/api/security/EncryptionService.java | 3 +-
.../api/security/SecurityServiceConfiguration.java | 129 +++++++++++-
.../unomi/api/segments/DependentMetadata.java | 27 +++
.../apache/unomi/api/segments/ScoringElement.java | 4 +-
.../unomi/api/segments/SegmentsAndScores.java | 4 +-
.../apache/unomi/api/services/ClusterService.java | 5 +-
.../api/services/ConditionValidationService.java | 21 +-
.../unomi/api/services/DefinitionsService.java | 4 +-
.../unomi/api/services/EventListenerService.java | 4 +-
.../apache/unomi/api/services/EventService.java | 4 +-
.../api/services/ExecutionContextManager.java | 3 +-
.../apache/unomi/api/services/GoalsService.java | 4 +-
.../unomi/api/services/InvalidObjectInfo.java | 74 ++++++-
.../unomi/api/services/PersonalizationService.java | 75 +++++--
.../apache/unomi/api/services/PrivacyService.java | 3 +-
.../apache/unomi/api/services/ProfileService.java | 58 +-----
.../apache/unomi/api/services/QueryService.java | 3 +-
.../unomi/api/services/RuleListenerService.java | 7 +-
.../apache/unomi/api/services/RulesService.java | 4 +-
.../unomi/api/services/SchedulerService.java | 21 ++
.../apache/unomi/api/services/ScopeService.java | 5 +-
.../apache/unomi/api/services/SegmentService.java | 4 +-
.../api/services/TenantLifecycleListener.java | 3 +-
.../apache/unomi/api/services/TopicService.java | 9 +-
.../apache/unomi/api/services/UserListService.java | 3 +-
.../unomi/api/services/ValueTypeValidator.java | 3 +-
.../unomi/api/tenants/ApiKeyCreationResult.java | 13 ++
.../org/apache/unomi/api/tenants/AuditService.java | 9 +-
.../apache/unomi/api/tenants/ItemAuditService.java | 3 +-
.../unomi/api/tenants/TenantAuditService.java | 3 +-
.../unomi/api/tenants/TenantBackupMetadata.java | 26 +++
.../unomi/api/tenants/TenantEventPurgeResult.java | 56 ++++-
.../apache/unomi/api/tenants/TenantScopeUsage.java | 28 ++-
.../org/apache/unomi/api/tenants/TenantStatus.java | 4 +-
.../org/apache/unomi/api/tenants/TenantUsage.java | 134 +++++++++++-
.../unomi/api/tenants/TenantUsageService.java | 1 +
.../api/tenants/security/SecurityAuditReport.java | 49 +++++
.../api/tenants/security/SecuritySettings.java | 66 ++++++
.../org/apache/unomi/api/utils/ParserHelper.java | 227 ++++++++++++++++++++-
.../java/org/apache/unomi/api/utils/YamlUtils.java | 3 +
build.sh | 22 +-
config/checkstyle-javadoc.xml | 31 +++
pom.xml | 42 ++++
93 files changed, 2124 insertions(+), 310 deletions(-)
diff --git a/api/src/main/java/org/apache/unomi/api/BatchUpdate.java b/api/src/main/java/org/apache/unomi/api/BatchUpdate.java
index 8f55a5195..240b0c8ad 100644
--- a/api/src/main/java/org/apache/unomi/api/BatchUpdate.java
+++ b/api/src/main/java/org/apache/unomi/api/BatchUpdate.java
@@ -20,7 +20,10 @@ package org.apache.unomi.api;
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.
+ * Describes a bulk update operation that changes a property on every item
+ * matching a {@link org.apache.unomi.api.conditions.Condition}.
+ * Used when administrators or imports need to apply the same property change
+ * to many profiles, sessions, or other items at once.
*/
public class BatchUpdate {
private String propertyName;
diff --git a/api/src/main/java/org/apache/unomi/api/ClusterNode.java b/api/src/main/java/org/apache/unomi/api/ClusterNode.java
index a80b5689f..09bed0dd8 100644
--- a/api/src/main/java/org/apache/unomi/api/ClusterNode.java
+++ b/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;
@@ -50,7 +54,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the cpu load.
- *
* @return the cpu load
*/
public double getCpuLoad() {
@@ -59,7 +62,6 @@ public class ClusterNode extends Item {
/**
* Sets the cpu load.
- *
* @param cpuLoad the cpu load
*/
public void setCpuLoad(double cpuLoad) {
@@ -68,7 +70,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the public host address.
- *
* @return the public host address
*/
public String getPublicHostAddress() {
@@ -77,7 +78,6 @@ public class ClusterNode extends Item {
/**
* Sets the public host address.
- *
* @param publicHostAddress the public host address
*/
public void setPublicHostAddress(String publicHostAddress) {
@@ -86,7 +86,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the internal host address which uses the HTTP/HTTPS protocol for communications between clients and the context server.
- *
* @return the internal host address
*/
public String getInternalHostAddress() {
@@ -95,7 +94,6 @@ public class ClusterNode extends Item {
/**
* Sets the internal host address which uses the HTTP/HTTPS protocol for communications between clients and the context server.
- *
* @param internalHostAddress the internal host address
*/
public void setInternalHostAddress(String internalHostAddress) {
@@ -104,7 +102,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the load average for the last minute, five minutes and fifteen 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
*/
public double[] getLoadAverage() {
@@ -113,7 +110,6 @@ public class ClusterNode extends Item {
/**
* Sets the load average for the last minute, five minutes and fifteen 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
*/
public void setLoadAverage(double[] loadAverage) {
@@ -122,7 +118,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the uptime.
- *
* @return the uptime
*/
public long getUptime() {
@@ -131,7 +126,6 @@ public class ClusterNode extends Item {
/**
* Sets the uptime.
- *
* @param uptime the uptime
*/
public void setUptime(long uptime) {
@@ -140,7 +134,6 @@ public class ClusterNode extends Item {
/**
* 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.
- *
* @return {@code true} if this node is a master node, {@code false} otherwise
*/
public boolean isMaster() {
@@ -148,8 +141,7 @@ public class ClusterNode extends Item {
}
/**
- * 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..
- *
+ * 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.
* @param master {@code true} if this node is a master node, {@code false} otherwise
*/
public void setMaster(boolean master) {
@@ -158,7 +150,6 @@ public class ClusterNode extends Item {
/**
* Determines whether this ClusterNode locally stores data.
- *
* @return {@code true} if this node locally stores data, {@code false} otherwise
*/
public boolean isData() {
@@ -167,7 +158,6 @@ public class ClusterNode extends Item {
/**
* Specifies whether this ClusterNode locally stores data.
- *
* @param data {@code true} if this node locally stores data, {@code false} otherwise
*/
public void setData(boolean data) {
@@ -176,7 +166,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the node start time in milliseconds.
- *
* @return the start time
*/
public long getStartTime() {
@@ -185,7 +174,6 @@ public class ClusterNode extends Item {
/**
* Sets the node start time in milliseconds.
- *
* @param startTime the start time
*/
public void setStartTime(long startTime) {
@@ -194,7 +182,6 @@ public class ClusterNode extends Item {
/**
* Retrieves the last heartbeat time in milliseconds.
- *
* @return the last heartbeat time
*/
public long getLastHeartbeat() {
@@ -203,7 +190,6 @@ public class ClusterNode extends Item {
/**
* Sets the last heartbeat time in milliseconds.
- *
* @param lastHeartbeat the last heartbeat time
*/
public void setLastHeartbeat(long lastHeartbeat) {
@@ -212,7 +198,6 @@ public class ClusterNode extends Item {
/**
* Gets the server information.
- *
* @return the server information
*/
public ServerInfo getServerInfo() {
@@ -221,7 +206,6 @@ public class ClusterNode extends Item {
/**
* Sets the server information.
- *
* @param serverInfo the server information
*/
public void setServerInfo(ServerInfo serverInfo) {
diff --git a/api/src/main/java/org/apache/unomi/api/ConsentStatus.java b/api/src/main/java/org/apache/unomi/api/ConsentStatus.java
index 1f5b20d27..3ece0c5c8 100644
--- a/api/src/main/java/org/apache/unomi/api/ConsentStatus.java
+++ b/api/src/main/java/org/apache/unomi/api/ConsentStatus.java
@@ -17,14 +17,15 @@
package org.apache.unomi.api;
/**
- * This enum class represents the type of grant a @Consent might have. The revoke grant type is a special one used to
- * remove a consent for a profile.
+ * Allowed grant states for a profile {@link Consent}.
+ * Each constant tells whether consent was granted, denied, or later revoked.
+ * Revoked consents are removed from the profile rather than kept as denied.
*/
public enum ConsentStatus {
- // Consent has been granted.
+ /** Consent was explicitly granted by the profile. */
GRANTED,
- // Consent has been denied.
+ /** Consent was explicitly denied. */
DENIED,
- // Consent has been revoked.
+ /** Consent was revoked and should be removed from the profile. */
REVOKED
}
diff --git a/api/src/main/java/org/apache/unomi/api/CustomItem.java b/api/src/main/java/org/apache/unomi/api/CustomItem.java
index fab0917e4..7c471ada8 100644
--- a/api/src/main/java/org/apache/unomi/api/CustomItem.java
+++ b/api/src/main/java/org/apache/unomi/api/CustomItem.java
@@ -21,7 +21,9 @@ import java.util.HashMap;
import java.util.Map;
/**
- * A generic extension of Item for context server extensions, properties are stored in a Map.
+ * Generic {@link Item} extension for plugin-defined entity types.
+ * Properties live in a flexible map instead of typed fields, which lets
+ * extensions store custom payloads without adding new Java classes.
*/
public class CustomItem extends Item {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/EventInfo.java b/api/src/main/java/org/apache/unomi/api/EventInfo.java
index 543d6d940..df2936115 100644
--- a/api/src/main/java/org/apache/unomi/api/EventInfo.java
+++ b/api/src/main/java/org/apache/unomi/api/EventInfo.java
@@ -18,28 +18,49 @@
package org.apache.unomi.api;
/**
- * Basic event information
+ * Summary of one event type known to the server.
+ * Pairs an event type name with an occurrence count, for example when
+ * {@link ServerInfo} lists which events the running instance supports.
*/
public class EventInfo {
private String name;
private Long occurences;
+ /**
+ * Constructs a new {@code EventInfo} object.
+ */
public EventInfo() {
}
+ /**
+ * Returns the name of the event.
+ * @return The event name as a {@link String}.
+ */
public String getName() {
return name;
}
+ /**
+ * Sets the name of the event.
+ * @param name The name to set for the event.
+ */
public void setName(String name) {
this.name = name;
}
+ /**
+ * Gets the number of occurrences for this event type.
+ * @return The count of occurrences as a {@link Long}.
+ */
public Long getOccurences() {
return occurences;
}
+ /**
+ * Sets the number of occurrences for this event type.
+ * @param occurences The count of occurrences to set.
+ */
public void setOccurences(Long occurences) {
this.occurences = occurences;
}
diff --git a/api/src/main/java/org/apache/unomi/api/EventProperty.java b/api/src/main/java/org/apache/unomi/api/EventProperty.java
index d727e1498..b7c588f03 100644
--- a/api/src/main/java/org/apache/unomi/api/EventProperty.java
+++ b/api/src/main/java/org/apache/unomi/api/EventProperty.java
@@ -19,9 +19,9 @@ package org.apache.unomi.api;
import java.io.Serializable;
/**
- * An event property.
- *
- * @author Sergiy Shyrkov
+ * Named property attached to an {@link Event}.
+ * Events carry many properties; this type represents one key/value pair
+ * stored with the event for segmentation, personalization, and reporting.
*/
public class EventProperty implements Serializable {
diff --git a/api/src/main/java/org/apache/unomi/api/EventSource.java b/api/src/main/java/org/apache/unomi/api/EventSource.java
index 90128cf6c..d43ee3143 100644
--- a/api/src/main/java/org/apache/unomi/api/EventSource.java
+++ b/api/src/main/java/org/apache/unomi/api/EventSource.java
@@ -19,6 +19,10 @@ package org.apache.unomi.api;
/**
* TODO: REMOVE
+ * Describes where an event originated in the digital experience.
+ * Identifies the scope, item id, path, and type of the source page or item
+ * that triggered the event. Clients attach this information when they send
+ * events to Unomi.
*/
public class EventSource {
private String scope;
@@ -26,37 +30,74 @@ public class EventSource {
private String path;
private String type;
+ /**
+ * Constructs a new EventSource instance.
+ */
public EventSource() {
}
+ /**
+ * Returns the scope associated with this event source.
+ * @return The scope string.
+ */
public String getScope() {
return scope;
}
+ /**
+ * Sets the scope for this event source.
+ * @param scope the new scope to set.
+ */
public void setScope(String scope) {
this.scope = scope;
}
+ /**
+ * Returns the unique identifier of this event source.
+ * @return The ID string.
+ */
public String getId() {
return id;
}
+ /**
+ * Sets the unique identifier for this event source.
+ * @param id the new ID to set.
+ */
public void setId(String id) {
this.id = id;
}
+ /**
+ * Returns the path associated with this event source.
+ * @return The path string.
+ */
public String getPath() {
return path;
}
+ /**
+ * Sets the path for this event source.
+ * @param path the new path to set.
+ */
public void setPath(String path) {
this.path = path;
}
+ /**
+ * Returns the type identifier of this event source.
+ * @return The type string.
+ */
public String getType() {
return type;
}
+ /**
+ * Sets the type of this event source.
+ * This value can be used to classify the data structure or content
+ * represented by the event source, such as "string", "array", or "boolean".
+ * @param type The string representation of the desired type.
+ */
public void setType(String type) {
this.type = type;
}
diff --git a/api/src/main/java/org/apache/unomi/api/EventTarget.java b/api/src/main/java/org/apache/unomi/api/EventTarget.java
index f1bc1addc..8a172aa50 100644
--- a/api/src/main/java/org/apache/unomi/api/EventTarget.java
+++ b/api/src/main/java/org/apache/unomi/api/EventTarget.java
@@ -22,6 +22,10 @@ import java.util.Map;
/**
* TODO: REMOVE
+ * Describes what an event acted upon.
+ * Holds the target item id and type plus optional properties, for example
+ * the product or content element a user clicked. Used together with
+ * {@link Event} to give rules and analytics full context.
*/
public class EventTarget implements Serializable {
private static final long serialVersionUID = 6370790894348364803L;
@@ -29,34 +33,67 @@ public class EventTarget implements Serializable {
private String type;
private Map<String, Object> properties;
+ /**
+ * Constructs a default {@code EventTarget}.
+ */
public EventTarget() {
}
+ /**
+ * Constructs an {@code EventTarget} with the specified identifier and type.
+ * @param id The unique identifier of the event target.
+ * @param type The type associated with this event target.
+ */
public EventTarget(String id, String type) {
this.id = id;
this.type = type;
}
+ /**
+ * Returns the unique identifier of this event target.
+ * @return The {@code String} ID.
+ */
public String getId() {
return id;
}
+ /**
+ * Sets the unique identifier of this event target.
+ * @param id The new {@code String} ID.
+ */
public void setId(String id) {
this.id = id;
}
+ /**
+ * Returns the type associated with this event target.
+ * @return The {@code String} type.
+ */
public String getType() {
return type;
}
+ /**
+ * Sets the type associated with this event target.
+ * @param type The new {@code String} type.
+ */
public void setType(String type) {
this.type = type;
}
+ /**
+ * Returns a map containing arbitrary properties associated
+ * with this event target.
+ * @return The {@link java.util.Map} of properties.
+ */
public Map<String, Object> getProperties() {
return properties;
}
+ /**
+ * Sets the arbitrary properties associated with this event target.
+ * @param properties The {@link java.util.Map} of properties to set.
+ */
public void setProperties(Map<String, Object> properties) {
this.properties = properties;
}
diff --git a/api/src/main/java/org/apache/unomi/api/EventsCollectorRequest.java b/api/src/main/java/org/apache/unomi/api/EventsCollectorRequest.java
index 759a71ca8..96e69ffc9 100644
--- a/api/src/main/java/org/apache/unomi/api/EventsCollectorRequest.java
+++ b/api/src/main/java/org/apache/unomi/api/EventsCollectorRequest.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api;
import java.util.List;
/**
- * A request for events to be processed.
+ * Payload sent to the events collector endpoint.
+ * Wraps one or more {@link Event} instances that a client wants Unomi to
+ * process, evaluate against rules, and persist.
*/
public class EventsCollectorRequest {
@@ -37,13 +39,17 @@ public class EventsCollectorRequest {
/**
* Retrieves the events to be processed.
- *
* @return the events to be processed
*/
public List<Event> getEvents() {
return events;
}
+ /**
+ * Sets the list of events to be processed by this request.
+ * @param events a list containing all events that should be
+ * collected and processed.
+ */
public void setEvents(List<Event> events) {
this.events = events;
}
@@ -51,7 +57,6 @@ public class EventsCollectorRequest {
/**
* Retrieve the sessionId passed along with the request. All events will be processed with this sessionId as a
* default
- *
* @return the identifier for the session
*/
public String getSessionId() {
@@ -61,7 +66,6 @@ public class EventsCollectorRequest {
/**
* Sets the sessionId in the request. This is the preferred method of passing along a session identifier with the
* request, as passing it along in the URL can lead to potential security vulnerabilities.
- *
* @param sessionId an unique identifier for the session
*/
public void setSessionId(String sessionId) {
@@ -71,7 +75,6 @@ public class EventsCollectorRequest {
/**
* Retrieve the profileId passed along with the request. All events will be processed with this profileId as a
* default
- *
* @return the identifier for the profile
*/
public String getProfileId() {
@@ -80,7 +83,6 @@ public class EventsCollectorRequest {
/**
* Sets the profileId in the request.
- *
* @param profileId an unique identifier for the profile
*/
public void setProfileId(String profileId) {
diff --git a/api/src/main/java/org/apache/unomi/api/ExecutionContext.java b/api/src/main/java/org/apache/unomi/api/ExecutionContext.java
index 39b13f383..7506a31e5 100644
--- a/api/src/main/java/org/apache/unomi/api/ExecutionContext.java
+++ b/api/src/main/java/org/apache/unomi/api/ExecutionContext.java
@@ -21,9 +21,13 @@ import java.util.Set;
import java.util.Stack;
/**
- * Represents the execution context for operations in Unomi, including security and tenant information.
+ * Security and tenant context for an in-flight operation.
+ * Carries the active tenant id, roles, permissions, and helpers to check
+ * access or temporarily switch tenant scope. Services read this object to
+ * enforce multi-tenant isolation and authorization.
*/
public class ExecutionContext {
+ /** The constant string used to identify the system tenant. */
public static final String SYSTEM_TENANT = "system";
private String tenantId;
@@ -32,6 +36,15 @@ public class ExecutionContext {
private Stack<String> tenantStack = new Stack<>();
private boolean isSystem = false;
+ /**
+ * Constructs a new execution context with specified
+ * security and tenant details.
+ * @param tenantId The unique identifier of the tenant for this context.
+ * @param roles A set of roles assigned to the user in this
+ * context. Can be null.
+ * @param permissions A set of explicit permissions granted to the user in
+ * this context. Can be null.
+ */
public ExecutionContext(String tenantId, Set<String> roles, Set<String> permissions) {
this.tenantId = tenantId;
if (tenantId != null && tenantId.equals(SYSTEM_TENANT)) {
@@ -45,34 +58,70 @@ public class ExecutionContext {
}
}
+ /**
+ * Creates and returns a dedicated execution context
+ * representing the system tenant.
+ * @return An {@link ExecutionContext} instance configured
+ * for the system tenant.
+ */
public static ExecutionContext systemContext() {
ExecutionContext context = new ExecutionContext(SYSTEM_TENANT, null, null);
context.isSystem = true;
return context;
}
+ /**
+ * Retrieves the unique identifier of the current tenant
+ * associated with this context.
+ * @return The tenant ID string.
+ */
public String getTenantId() {
return tenantId;
}
+ /**
+ * Returns a copy of the set of roles assigned to this execution context.
+ * @return A new {@link Set} containing a copy of all assigned roles.
+ */
public Set<String> getRoles() {
return new HashSet<>(roles);
}
+ /**
+ * Returns a copy of the set of permissions granted to
+ * this execution context.
+ * @return A new {@link Set} containing a copy of all explicit permissions.
+ */
public Set<String> getPermissions() {
return new HashSet<>(permissions);
}
+ /**
+ * Checks if this execution context is designated as the system context.
+ * @return true if the context represents the system
+ * tenant, false otherwise.
+ */
public boolean isSystem() {
return isSystem;
}
+ /**
+ * Sets a new tenant ID for the current execution context. This operation
+ * saves the previous tenant ID onto an internal stack and updates the
+ * system status accordingly.
+ * @param tenantId The new tenant identifier to set.
+ */
public void setTenant(String tenantId) {
tenantStack.push(this.tenantId);
this.tenantId = tenantId;
this.isSystem = SYSTEM_TENANT.equals(tenantId);
}
+ /**
+ * Restores the execution context to the previously active tenant.
+ * If a previous tenant was set, this method pops that tenant ID from the
+ * internal stack and updates the current context state accordingly.
+ */
public void restorePreviousTenant() {
if (!tenantStack.isEmpty()) {
this.tenantId = tenantStack.pop();
@@ -80,6 +129,17 @@ public class ExecutionContext {
}
}
+ /**
+ * Validates whether the current execution context has sufficient
+ * permissions to perform a given operation.
+ * If the context is system-level, validation passes immediately. Otherwise,
+ * it checks if the required permission exists in the context's
+ * granted permissions.
+ * @param operation The specific operation name required
+ * for access validation.
+ * @throws SecurityException if the current context lacks the necessary
+ * permission for the given operation.
+ */
public void validateAccess(String operation) {
if (isSystem) {
return;
@@ -90,10 +150,27 @@ public class ExecutionContext {
}
}
+ /**
+ * Checks if the current execution context possesses a specific permission.
+ * The context is considered to have the permission if it is system-level or
+ * if the permission name is explicitly listed in the context's
+ * granted permissions.
+ * @param permission The name of the permission to check for.
+ * @return true if the context is system-level or has been granted the
+ * permission, false otherwise.
+ */
public boolean hasPermission(String permission) {
return isSystem || permissions.contains(permission);
}
+ /**
+ * Checks if the current execution context possesses a specific role.
+ * The context is considered to have the role if it is system-level or if
+ * the role name is explicitly listed in the context's granted roles.
+ * @param role The name of the role to check for.
+ * @return true if the context is system-level or has been granted the
+ * role, false otherwise.
+ */
public boolean hasRole(String role) {
return isSystem || roles.contains(role);
}
diff --git a/api/src/main/java/org/apache/unomi/api/GeoPoint.java b/api/src/main/java/org/apache/unomi/api/GeoPoint.java
index b3d0d02a6..e7481d2db 100644
--- a/api/src/main/java/org/apache/unomi/api/GeoPoint.java
+++ b/api/src/main/java/org/apache/unomi/api/GeoPoint.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api;
import java.util.Map;
/**
- * GeoPoint represents a point in geographical coordinate system using latitude and longitude.
+ * A geographic location expressed as latitude and longitude.
+ * Used on profiles, events, and queries when rules or segments need to
+ * match users or actions by location.
*/
public class GeoPoint {
diff --git a/api/src/main/java/org/apache/unomi/api/Item.java b/api/src/main/java/org/apache/unomi/api/Item.java
index ec796de52..44ff53b0f 100644
--- a/api/src/main/java/org/apache/unomi/api/Item.java
+++ b/api/src/main/java/org/apache/unomi/api/Item.java
@@ -50,6 +50,15 @@ public abstract class Item implements Serializable, YamlConvertible {
private static final Map<Class,String> itemTypeCache = new ConcurrentHashMap<>();
+ /**
+ * Retrieves the type string for a given class by attempting to read a
+ * public static String constant named {@code ITEM_TYPE} from that class.
+ * This method caches the result based on the provided class to improve
+ * performance during repeated calls.
+ * @param clazz The Class object whose item type is required.
+ * @return A string representation of the Item's type, or null if the
+ * {@code ITEM_TYPE} field cannot be found or accessed.
+ */
public static String getItemType(Class clazz) {
String itemType = itemTypeCache.get(clazz);
if (itemType != null) {
@@ -67,10 +76,30 @@ public abstract class Item implements Serializable, YamlConvertible {
return null;
}
+ /**
+ * Protected field representing the unique identifier used to identify this
+ * Item when persisted or referenced.
+ */
protected String itemId;
+ /**
+ * Protected field storing the type of this Item. This value is typically
+ * derived from a constant defined within the implementing class.
+ */
protected String itemType;
+ /**
+ * Protected field defining the scope of this Item, allowing related items
+ * to be grouped together during processing or retrieval.
+ */
protected String scope;
+ /**
+ * Protected field storing the current version number of this Item. This is
+ * used for tracking changes over time.
+ */
protected Long version;
+ /**
+ * A protected map used to store additional, non-core metadata about this
+ * Item using string keys and arbitrary object values.
+ */
protected Map<String, Object> systemMetadata = new HashMap<>();
private String tenantId;
@@ -82,6 +111,12 @@ public abstract class Item implements Serializable, YamlConvertible {
private String sourceInstanceId;
private Date lastSyncDate;
+ /**
+ * Default constructor that initializes the Item's type by calling
+ * {@link #getItemType(Class)} and sets up initial audit metadata fields.
+ * If the implementing class does not provide a public static String
+ * constant named {@code ITEM_TYPE}, an error is logged.
+ */
public Item() {
this.itemType = getItemType(this.getClass());
if (itemType == null) {
@@ -90,6 +125,11 @@ public abstract class Item implements Serializable, YamlConvertible {
initializeAuditMetadata();
}
+ /**
+ * Constructor that initializes the Item using the default mechanism and
+ * explicitly sets the item's unique identifier.
+ * @param itemId The unique ID to assign to this Item upon creation.
+ */
public Item(String itemId) {
this();
this.itemId = itemId;
@@ -103,13 +143,17 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Retrieves the Item's identifier used to uniquely identify this Item when persisted or when referred to. An Item's identifier must be unique among Items with the same type.
- *
* @return a String representation of the identifier, no particular format is prescribed as long as it is guaranteed unique for this particular Item.
*/
public String getItemId() {
return itemId;
}
+ /**
+ * Sets the unique identifier for this Item. This ID is used when persisting
+ * or referencing the item in various contexts (e.g., profiles, sessions).
+ * @param itemId the unique identifier for the Item
+ */
public void setItemId(String itemId) {
this.itemId = itemId;
}
@@ -117,7 +161,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Retrieves the Item's type used to assert metadata and structure common to Items of this type, notably for persistence purposes. The Item's type <strong>must</strong>
* match the value defined by the implementation's {@code ITEM_TYPE} public constant.
- *
* @return a String representation of this Item's type, must equal the {@code ITEM_TYPE} value
*/
public String getItemType() {
@@ -126,7 +169,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the Item's type.
- *
* @param itemType the Item's type
*/
public void setItemType(String itemType) {
@@ -135,7 +177,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Retrieves the Item's scope.
- *
* @return the Item's scope name
*/
public String getScope() {
@@ -144,7 +185,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the Item's scope.
- *
* @param scope the Item's scope
*/
public void setScope(String scope) {
@@ -166,17 +206,25 @@ public abstract class Item implements Serializable, YamlConvertible {
return itemId != null ? itemId.hashCode() : 0;
}
+ /**
+ * Retrieves the current version number of the Item.
+ * @return a {@link Long} representing the version of this Item.
+ */
public Long getVersion() {
return version;
}
+ /**
+ * Sets the version number of the Item. This is typically used when updating
+ * an existing item's state.
+ * @param version the new version to set
+ */
public void setVersion(Long version) {
this.version = version;
}
/**
* Returns the system metadata for the given key.
- *
* @param key the key
* @return the system metadata for the given key
*/
@@ -186,7 +234,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the system metadata for the given key.
- *
* @param key the key
* @param value the value
*/
@@ -194,40 +241,51 @@ public abstract class Item implements Serializable, YamlConvertible {
systemMetadata.put(key, value);
}
+ /**
+ * Retrieves the unique identifier of the tenant associated with this Item,
+ * useful for context management and logging.
+ * @return the tenant ID as a {@link String}.
+ */
public String getTenantId() {
return tenantId;
}
/**
* Sets the tenant ID.
- *
* @param tenantId the tenant ID
*/
public void setTenantId(String tenantId) {
this.tenantId = tenantId;
}
- // Audit metadata getters and setters
+ /**
+ * Retrieves the identifier of the user or system that originally created
+ * this Item. This is part of the item's audit metadata.
+ * @return the creator's ID as a {@link String}.
+ */
public String getCreatedBy() {
return createdBy;
}
/**
* Sets the created by.
- *
* @param createdBy the created by
*/
public void setCreatedBy(String createdBy) {
this.createdBy = createdBy;
}
+ /**
+ * Retrieves the identifier of the user or system that last modified this
+ * Item. This is part of the item's audit metadata.
+ * @return the last modifier's ID as a {@link String}.
+ */
public String getLastModifiedBy() {
return lastModifiedBy;
}
/**
* Sets the last modified by.
- *
* @param lastModifiedBy the last modified by
*/
public void setLastModifiedBy(String lastModifiedBy) {
@@ -236,7 +294,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Returns the date when this item was created.
- *
* @return the date when this item was created
*/
public Date getCreationDate() {
@@ -245,7 +302,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the date when this item was created.
- *
* @param creationDate the creation date
*/
public void setCreationDate(Date creationDate) {
@@ -254,7 +310,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Returns the date when this item was last modified.
- *
* @return the date when this item was last modified
*/
public Date getLastModificationDate() {
@@ -263,7 +318,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the date when this item was last modified.
- *
* @param lastModificationDate the last modification date
*/
public void setLastModificationDate(Date lastModificationDate) {
@@ -272,7 +326,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Returns the source instance ID.
- *
* @return the source instance ID
*/
public String getSourceInstanceId() {
@@ -281,7 +334,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the source instance ID.
- *
* @param sourceInstanceId the source instance ID
*/
public void setSourceInstanceId(String sourceInstanceId) {
@@ -290,7 +342,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Returns the last synchronization date.
- *
* @return the last synchronization date
*/
public Date getLastSyncDate() {
@@ -299,7 +350,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Sets the last synchronization date.
- *
* @param lastSyncDate the last synchronization date
*/
public void setLastSyncDate(Date lastSyncDate) {
@@ -309,7 +359,6 @@ public abstract class Item implements Serializable, YamlConvertible {
/**
* Converts this item to a Map structure for YAML output.
* Implements YamlConvertible interface with circular reference detection.
- *
* @param visited set of already visited objects to prevent infinite recursion (may be null)
* @return a Map representation of this item
*/
diff --git a/api/src/main/java/org/apache/unomi/api/Metadata.java b/api/src/main/java/org/apache/unomi/api/Metadata.java
index 4f650589f..b33647771 100644
--- a/api/src/main/java/org/apache/unomi/api/Metadata.java
+++ b/api/src/main/java/org/apache/unomi/api/Metadata.java
@@ -29,7 +29,9 @@ import java.util.Set;
import static org.apache.unomi.api.utils.YamlUtils.circularRef;
/**
- * A class providing information about context server entities.
+ * Common descriptive fields shared by Unomi configuration items.
+ * Includes id, name, description, scope, tags, and related attributes that
+ * appear on segments, rules, property types, and other managed entities.
*
* @see MetadataItem
*/
@@ -60,7 +62,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Instantiates a new Metadata with the specified identifier.
- *
* @param id the identifier for this Metadata
*/
public Metadata(String id) {
@@ -69,7 +70,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Instantiates a new Metadata with the provided information.
- *
* @param scope the scope for this Metadata
* @param id the identifier of the associated {@link Item}
* @param name the name
@@ -84,7 +84,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves the identifier for the entity associated with this Metadata
- *
* @return the identifier
*/
public String getId() {
@@ -93,7 +92,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the id.
- *
* @param id the id
*/
public void setId(String id) {
@@ -102,7 +100,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves the name.
- *
* @return the name
*/
public String getName() {
@@ -111,7 +108,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the name.
- *
* @param name the name
*/
public void setName(String name) {
@@ -120,7 +116,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves the description.
- *
* @return the description
*/
public String getDescription() {
@@ -129,7 +124,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the description.
- *
* @param description the description
*/
public void setDescription(String description) {
@@ -138,7 +132,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves the scope for the entity associated with this Metadata
- *
* @return the scope for the entity associated with this Metadata
* @see Item Item for a deeper discussion of scopes
*/
@@ -148,7 +141,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the scope.
- *
* @param scope the scope
*/
public void setScope(String scope) {
@@ -157,7 +149,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves a set of {@link String} tag names associated with this Metadata
- *
* @return a set of {@link String} tag names associated with this Metadata
*/
public Set<String> getTags() {
@@ -166,7 +157,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the tags.
- *
* @param tags the tag ids
*/
public void setTags(Set<String> tags) {
@@ -175,7 +165,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Retrieves a set of {@link String} system tag names associated with this Metadata
- *
* @return a set of {@link String} system tag names associated with this Metadata
*/
public Set<String> getSystemTags() {
@@ -184,7 +173,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Sets the system tags.
- *
* @param systemTags the system tag ids
*/
public void setSystemTags(Set<String> systemTags) {
@@ -193,7 +181,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Whether the associated entity is considered active by the context server, in particular to check if rules need to be created / triggered
- *
* @return {@code true} if the associated entity is enabled, {@code false} otherwise
*/
public boolean isEnabled() {
@@ -202,7 +189,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Specifies whether the associated entity should be active or not.
- *
* @param enabled {@code true} if the associated entity is enabled, {@code false} otherwise
*/
public void setEnabled(boolean enabled) {
@@ -211,7 +197,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Whether the associated entity is waiting on additional plugins to become available to be able to properly perform its function.
- *
* @return {@code true} if plugins are missing, {@code false} otherwise
*/
public boolean isMissingPlugins() {
@@ -220,7 +205,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Specifies whether the associated entity is waiting on additional plugins to become available.
- *
* @param missingPlugins {@code true} if plugins are missing, {@code false} otherwise
*/
public void setMissingPlugins(boolean missingPlugins) {
@@ -229,7 +213,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Whether the associated entity is considered for internal purposes only and should therefore be hidden to accessing UIs.
- *
* @return {@code true} if the associated entity needs to be hidden, {@code false} otherwise
*/
public boolean isHidden() {
@@ -238,7 +221,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Specifies whether the associated entity is hidden.
- *
* @param hidden {@code true} if the associated entity needs to be hidden, {@code false} otherwise
*/
public void setHidden(boolean hidden) {
@@ -247,7 +229,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Whether the associated entity can be accessed but not modified.
- *
* @return {@code true} if the associated entity can be accessed but not modified, {@code false} otherwise
*/
public boolean isReadOnly() {
@@ -256,13 +237,20 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Specifies whether the associated entity should be only accessed and not modified.
- *
* @param readOnly {@code true} if the associated entity can be accessed but not modified, {@code false} otherwise
*/
public void setReadOnly(boolean readOnly) {
this.readOnly = readOnly;
}
+ /**
+ * Compares this Metadata instance to another based on their identifiers.
+ * @param o The other {@link Metadata} object to compare against.
+ * @return An integer representing the comparison result of the IDs: a
+ * negative value if this ID is less than the specified ID, zero
+ * if the IDs are equal, or a positive value if this ID is
+ * greater than the specified ID.
+ */
public int compareTo(Metadata o) {
return getId().compareTo(o.getId());
}
@@ -289,7 +277,6 @@ public class Metadata implements Comparable<Metadata>, Serializable, YamlConvert
/**
* Converts this metadata to a Map structure for YAML output.
* Implements YamlConvertible interface with circular reference detection.
- *
* @param visited set of already visited objects to prevent infinite recursion (may be null)
* @return a Map representation of this metadata
*/
diff --git a/api/src/main/java/org/apache/unomi/api/MetadataItem.java b/api/src/main/java/org/apache/unomi/api/MetadataItem.java
index 68cf3b324..9ff4ff0d3 100644
--- a/api/src/main/java/org/apache/unomi/api/MetadataItem.java
+++ b/api/src/main/java/org/apache/unomi/api/MetadataItem.java
@@ -28,15 +28,27 @@ import java.util.Set;
import static org.apache.unomi.api.utils.YamlUtils.toYamlValue;
/**
- * A superclass for all {@link Item}s that bear {@link Metadata}.
+ * Base {@link Item} for entities that carry {@link Metadata}.
+ * Most user-facing definitions (segments, rules, property types, etc.)
+ * extend this class so they share the same identification and tagging model.
*/
public abstract class MetadataItem extends Item {
private static final long serialVersionUID = -2459510107927663510L;
+ /** The associated {@link Metadata} object for this item. */
protected Metadata metadata;
+ /**
+ * Constructs a default {@code MetadataItem}.
+ */
public MetadataItem() {
}
+ /**
+ * Constructs a {@code MetadataItem} initialized with the given metadata.
+ * The parent class ID is set using the ID from the provided metadata, and
+ * the internal metadata field is populated.
+ * @param metadata the initial metadata for this item
+ */
public MetadataItem(Metadata metadata) {
super(metadata != null ? metadata.getId() : null);
this.metadata = metadata;
@@ -44,7 +56,6 @@ public abstract class MetadataItem extends Item {
/**
* Retrieves the associated Metadata.
- *
* @return the associated Metadata
*/
@XmlElement(name = "metadata")
@@ -52,6 +63,12 @@ public abstract class MetadataItem extends Item {
return metadata;
}
+ /**
+ * Sets the associated {@link Metadata}.
+ * If the provided metadata is not null, the parent class's ID will be
+ * updated to match the ID of the new metadata object.
+ * @param metadata the metadata to set
+ */
public void setMetadata(Metadata metadata) {
if (metadata != null) {
this.itemId = metadata.getId();
@@ -59,6 +76,12 @@ public abstract class MetadataItem extends Item {
this.metadata = metadata;
}
+ /**
+ * Returns the scope for this item, taken from {@link Metadata} when present.
+ * Falls back to the item-level scope field otherwise.
+ *
+ * @return the scope id, or {@code null} if none is set
+ */
@XmlTransient
public String getScope() {
if (metadata != null) {
@@ -71,7 +94,6 @@ public abstract class MetadataItem extends Item {
* Converts this metadata item to a Map structure for YAML output.
* Merges fields from Item parent class and adds metadata field.
* Subclasses should override this method, call super.toYaml(visited), and add their specific fields.
- *
* @param visited set of already visited objects to prevent infinite recursion (may be null)
* @return a Map representation of this metadata item
*/
diff --git a/api/src/main/java/org/apache/unomi/api/Parameter.java b/api/src/main/java/org/apache/unomi/api/Parameter.java
index 10cd6083d..c43949eb0 100644
--- a/api/src/main/java/org/apache/unomi/api/Parameter.java
+++ b/api/src/main/java/org/apache/unomi/api/Parameter.java
@@ -44,35 +44,71 @@ public class Parameter implements Serializable, YamlConvertible {
private Object defaultValue;
private ConditionValidation validation;
+ /**
+ * Constructs a default {@link Parameter} instance.
+ */
public Parameter() {
}
+ /**
+ * Constructs a {@link Parameter} with specified
+ * identification and type details.
+ * @param id The unique identifier for this parameter.
+ * @param type The data type of the parameter (e.g., "string", "integer").
+ * @param multivalued Indicates if the parameter can hold multiple values.
+ */
public Parameter(String id, String type, boolean multivalued) {
this.id = id;
this.type = type;
this.multivalued = multivalued;
}
+ /**
+ * Returns the unique identifier assigned to this parameter.
+ * @return The ID string of the parameter.
+ */
public String getId() {
return id;
}
+ /**
+ * Sets the unique identifier for this parameter.
+ * @param id The new ID to assign to the parameter.
+ */
public void setId(String id) {
this.id = id;
}
+ /**
+ * Retrieves the data type associated with this parameter.
+ * @return The string representation of the parameter's type.
+ */
public String getType() {
return type;
}
+ /**
+ * Sets the data type for this parameter.
+ * @param type The new data type string (e.g., "array", "boolean").
+ */
public void setType(String type) {
this.type = type;
}
+ /**
+ * Checks if this parameter is configured to handle multiple values.
+ * @return {@code true} if the parameter is multivalued,
+ * {@code false} otherwise.
+ */
public boolean isMultivalued() {
return multivalued;
}
+ /**
+ * Sets whether this parameter can hold multiple values.
+ * @param multivalued If {@code true}, the parameter accepts multiple
+ * values; otherwise, it accepts only one.
+ */
public void setMultivalued(boolean multivalued) {
this.multivalued = multivalued;
}
@@ -86,18 +122,37 @@ public class Parameter implements Serializable, YamlConvertible {
// Avoid errors when deploying old definitions
}
+ /**
+ * Retrieves the default value configured for this parameter.
+ * @return The stored default value, which may be null if none is set.
+ */
public Object getDefaultValue() {
return defaultValue;
}
+ /**
+ * Sets the default value that should be used when evaluating conditions
+ * involving this parameter. This value can be of any type.
+ * @param defaultValue the object to be set as the default value
+ */
public void setDefaultValue(Object defaultValue) {
this.defaultValue = defaultValue;
}
+ /**
+ * Gets the condition validation rules associated with this parameter.
+ * @return The {@link ConditionValidation} object defining constraints, or
+ * null if none is configured.
+ */
public ConditionValidation getValidation() {
return validation;
}
+ /**
+ * Sets the specific condition validation rules for this parameter. This
+ * allows controlling how the parameter behaves within a condition context.
+ * @param validation the new {@link ConditionValidation} object to apply
+ */
public void setValidation(ConditionValidation validation) {
this.validation = validation;
}
@@ -105,7 +160,6 @@ public class Parameter implements Serializable, YamlConvertible {
/**
* Converts this parameter to a Map structure for YAML output.
* Implements YamlConvertible interface.
- *
* @param visited set of already visited objects to prevent infinite recursion (may be null)
* @return a Map representation of this parameter
*/
diff --git a/api/src/main/java/org/apache/unomi/api/PartialList.java b/api/src/main/java/org/apache/unomi/api/PartialList.java
index 568cf334e..afe1c9c2a 100644
--- a/api/src/main/java/org/apache/unomi/api/PartialList.java
+++ b/api/src/main/java/org/apache/unomi/api/PartialList.java
@@ -25,7 +25,6 @@ import java.util.List;
/**
* A list of elements representing a limited view of a larger list, starting from a given element (offset from the first) and showing only a given number of elements, instead of
* showing all of them. This is useful to retrieve "pages" of large element collections.
- *
* @param <T> the generic type of contained elements
*/
public class PartialList<T> implements Serializable {
@@ -45,7 +44,9 @@ public class PartialList<T> implements Serializable {
* relation we can understand if we are in the case of an accurate hit or not.
*/
public enum Relation {
+ /** Total size equals the reported value exactly. */
EQUAL,
+ /** Total size is at least the reported value (approximate lower bound). */
GREATER_THAN_OR_EQUAL_TO
}
@@ -62,7 +63,6 @@ public class PartialList<T> implements Serializable {
/**
* Instantiates a new PartialList.
- *
* @param list the limited view into the bigger List this PartialList is representing
* @param offset the offset of the first element in the view
* @param pageSize the number of elements this PartialList contains
@@ -79,7 +79,6 @@ public class PartialList<T> implements Serializable {
/**
* Retrieves the limited list view.
- *
* @return a List of the {@code size} elements starting from the {@code offset}-th one from the original, larger list
*/
public List<T> getList() {
@@ -88,7 +87,6 @@ public class PartialList<T> implements Serializable {
/**
* Sets the view list.
- *
* @param list the view list into the bigger List this PartialList is representing
*/
public void setList(List<T> list) {
@@ -97,46 +95,56 @@ public class PartialList<T> implements Serializable {
/**
* Retrieves the offset of the first element of the view.
- *
* @return the offset of the first element of the view
*/
public long getOffset() {
return offset;
}
+ /**
+ * Sets the offset of the first element in this partial list view.
+ * @param offset the starting index (offset) for the elements in the view.
+ */
public void setOffset(long offset) {
this.offset = offset;
}
/**
* Retrieves the number of elements this PartialList contains.
- *
* @return the number of elements this PartialList contains
*/
public long getPageSize() {
return pageSize;
}
+ /**
+ * Sets the maximum number of elements to be returned in
+ * this partial list view.
+ * @param pageSize the size limit for the page view.
+ */
public void setPageSize(long pageSize) {
this.pageSize = pageSize;
}
/**
* Retrieves the total size of elements in the original List.
- *
* @return the total size of elements in the original List
*/
public long getTotalSize() {
return totalSize;
}
+ /**
+ * Sets the total count of elements available in the original, full list.
+ * @param totalSize the overall size of the collection represented
+ * by this PartialList.
+ */
public void setTotalSize(long totalSize) {
this.totalSize = totalSize;
}
/**
* Retrieves the size of this PartialList. Should equal {@link #getPageSize()}.
- *
* @return the size of this PartialList
*/
@XmlTransient
@@ -146,7 +154,6 @@ public class PartialList<T> implements Serializable {
/**
* Retrieves the element at the specified index
- *
* @param index the index of the element to retrieve
* @return the element at the specified index
*/
@@ -163,6 +170,11 @@ public class PartialList<T> implements Serializable {
return scrollIdentifier;
}
+ /**
+ * Sets the scroll identifier used to continue a scrolling list query.
+ * @param scrollIdentifier a string containing the unique identifier needed
+ * for subsequent requests in a scroll operation.
+ */
public void setScrollIdentifier(String scrollIdentifier) {
this.scrollIdentifier = scrollIdentifier;
}
@@ -175,6 +187,11 @@ public class PartialList<T> implements Serializable {
return scrollTimeValidity;
}
+ /**
+ * Sets the time validity period for the scroll query.
+ * @param scrollTimeValidity a string representing how long the scroll
+ * context remains valid (e.g., "10m").
+ */
public void setScrollTimeValidity(String scrollTimeValidity) {
this.scrollTimeValidity = scrollTimeValidity;
}
@@ -188,6 +205,11 @@ public class PartialList<T> implements Serializable {
return totalSizeRelation;
}
+ /**
+ * Sets the relation describing the total size count.
+ * @param totalSizeRelation the relationship type between the total size and
+ * the actual data set.
+ */
public void setTotalSizeRelation(Relation totalSizeRelation) {
this.totalSizeRelation = totalSizeRelation;
}
diff --git a/api/src/main/java/org/apache/unomi/api/Patch.java b/api/src/main/java/org/apache/unomi/api/Patch.java
index b7fb457b4..c703ef2a8 100644
--- a/api/src/main/java/org/apache/unomi/api/Patch.java
+++ b/api/src/main/java/org/apache/unomi/api/Patch.java
@@ -29,9 +29,21 @@ import java.util.Date;
import java.util.Map;
import java.util.TreeMap;
+/**
+ * Represents a patch operation applied to an existing {@link Item}.
+ * {@link #PATCHABLE_TYPES} lists the item types that support patching.
+ * The {@link #operation} is one of {@code override}, {@code patch}, or
+ * {@code remove}: {@code override} replaces the full item, {@code patch}
+ * applies a JSON Patch payload, and {@code remove} needs no data.
+ */
public class Patch extends Item {
private static final long serialVersionUID = 4171966405850833985L;
+ /**
+ * A map containing the types of items that are capable of being patched.
+ * The keys represent item type names, and the values are {@link Class}
+ * objects corresponding to those patchable item types.
+ */
public final static Map<String, Class<? extends Item>> PATCHABLE_TYPES;
static {
@@ -47,6 +59,9 @@ public class Patch extends Item {
PATCHABLE_TYPES.put("scoring", Scoring.class);
}
+ /**
+ * The constant string used to identify this class as a "patch" item type.
+ */
public static final String ITEM_TYPE = "patch";
private String patchedItemId;
@@ -67,6 +82,10 @@ public class Patch extends Item {
return patchedItemId;
}
+ /**
+ * Sets the ID of the item that will be concerned by this patch.
+ * @param patchedItemId the id of the item
+ */
public void setPatchedItemId(String patchedItemId) {
this.patchedItemId = patchedItemId;
}
@@ -79,6 +98,10 @@ public class Patch extends Item {
return patchedItemType;
}
+ /**
+ * Sets the item type of the item that will be concerned by this patch.
+ * @param patchedItemType the item type
+ */
public void setPatchedItemType(String patchedItemType) {
this.patchedItemType = patchedItemType;
}
@@ -91,6 +114,11 @@ public class Patch extends Item {
return operation;
}
+ /**
+ * Sets the type of patch operation to perform. This can typically be
+ * 'override', 'patch', or 'remove'.
+ * @param operation the patch operation type
+ */
public void setOperation(String operation) {
this.operation = operation;
}
@@ -106,6 +134,14 @@ public class Patch extends Item {
return data;
}
+ /**
+ * Sets the data payload for the patch.
+ * For override operations, this should contain the full
+ * item representation.
+ * For patch operations, this should contain a JsonPatch object.
+ * For remove operations, no data is required.
+ * @param data the patch data
+ */
public void setData(Object data) {
this.data = data;
}
@@ -118,6 +154,10 @@ public class Patch extends Item {
return lastApplication;
}
+ /**
+ * Sets the date when the patch was last applied.
+ * @param lastApplication the date of the last application
+ */
public void setLastApplication(Date lastApplication) {
this.lastApplication = lastApplication;
}
diff --git a/api/src/main/java/org/apache/unomi/api/Persona.java b/api/src/main/java/org/apache/unomi/api/Persona.java
index 284ecb250..3dfa2e52c 100644
--- a/api/src/main/java/org/apache/unomi/api/Persona.java
+++ b/api/src/main/java/org/apache/unomi/api/Persona.java
@@ -23,13 +23,26 @@ package org.apache.unomi.api;
*/
public class Persona extends Profile {
+ /**
+ * The fixed item type identifier used when representing a persona object.
+ */
public static final String ITEM_TYPE = "persona";
private static final long serialVersionUID = -1239061113528609426L;
+ /**
+ * Constructs a new, default {@link Persona} instance.
+ * This constructor initializes the persona without an explicit ID,
+ * allowing the item ID to potentially be set subsequently.
+ */
public Persona() {
super();
}
+ /**
+ * Constructs a new {@link Persona} instance with the
+ * specified unique identifier.
+ * @param personaId The unique ID to assign to this persona.
+ */
public Persona(String personaId) {
super(personaId);
}
diff --git a/api/src/main/java/org/apache/unomi/api/PersonaSession.java b/api/src/main/java/org/apache/unomi/api/PersonaSession.java
index 0c9373dc8..47b36c081 100644
--- a/api/src/main/java/org/apache/unomi/api/PersonaSession.java
+++ b/api/src/main/java/org/apache/unomi/api/PersonaSession.java
@@ -20,15 +20,36 @@ package org.apache.unomi.api;
import java.util.Date;
/**
- * A Persona session.
+ * A browsing session attached to a {@link Persona}.
+ * Personas are test or synthetic profiles; their sessions let marketers
+ * preview personalized content as if they were a visitor in that category.
*/
public class PersonaSession extends Session {
+ /**
+ * The constant string identifier used as the item type for
+ * {@link PersonaSession} instances.
+ */
public static final String ITEM_TYPE = "personaSession";
private static final long serialVersionUID = -1499107289607498852L;
+ /**
+ * Constructs an empty {@link PersonaSession} instance.
+ * This session must be fully configured and saved using persistence
+ * services to represent a valid persona session record.
+ */
public PersonaSession() {
}
+ /**
+ * Constructs a {@link PersonaSession} associated with a given profile,
+ * item ID, and timestamp.
+ * The resulting session is initialized with a system scope metadata.
+ * @param itemId the unique identifier for the persona session item.
+ * @param profile the {@link Profile} object representing the
+ * context of the session.
+ * @param timeStamp the date and time when this session was
+ * created or recorded.
+ */
public PersonaSession(String itemId, Profile profile, Date timeStamp) {
super(itemId, profile, timeStamp, Metadata.SYSTEM_SCOPE);
}
diff --git a/api/src/main/java/org/apache/unomi/api/PersonaWithSessions.java b/api/src/main/java/org/apache/unomi/api/PersonaWithSessions.java
index 0a507e9b1..cf4a82cdb 100644
--- a/api/src/main/java/org/apache/unomi/api/PersonaWithSessions.java
+++ b/api/src/main/java/org/apache/unomi/api/PersonaWithSessions.java
@@ -22,37 +22,70 @@ import java.io.Serializable;
import java.util.List;
/**
- * A convenience object gathering a {@link Persona} and its associated {@link PersonaSession}s.
+ * Bundles a {@link Persona} with its related {@link PersonaSession} list.
+ * REST and tooling use this wrapper when returning a persona together with
+ * the sessions needed to simulate or inspect that persona.
*/
public class PersonaWithSessions implements Serializable {
private Persona persona;
private List<PersonaSession> sessions;
+ /**
+ * Constructs a new, empty {@link PersonaWithSessions} instance.
+ */
public PersonaWithSessions() {
}
+ /**
+ * Constructs a {@link PersonaWithSessions} object with the specified
+ * persona and list of sessions.
+ * @param persona the associated {@link Persona}
+ * @param sessions the list of associated {@link PersonaSession}s
+ */
public PersonaWithSessions(Persona persona, List<PersonaSession> sessions) {
this.persona = persona;
this.sessions = sessions;
}
+ /**
+ * Returns the {@link Persona} associated with this object.
+ * @return the contained {@link Persona}
+ */
public Persona getPersona() {
return persona;
}
+ /**
+ * Sets the {@link Persona} associated with this object.
+ * @param persona the new {@link Persona}
+ */
public void setPersona(Persona persona) {
this.persona = persona;
}
+ /**
+ * Returns all {@link PersonaSession}s associated with this object.
+ * @return a list of {@link PersonaSession}s
+ */
public List<PersonaSession> getSessions() {
return sessions;
}
+ /**
+ * Sets the list of {@link PersonaSession}s associated with this object.
+ * @param sessions the new list of {@link PersonaSession}s
+ */
public void setSessions(List<PersonaSession> sessions) {
this.sessions = sessions;
}
+ /**
+ * Retrieves the last session from the stored list. This is assumed to be
+ * the first element (index 0).
+ * If no sessions are present, returns null.
+ * @return the most recent {@link PersonaSession}, or null if none exist
+ */
@XmlTransient
public PersonaSession getLastSession() {
return sessions.size()>0?sessions.get(0):null;
diff --git a/api/src/main/java/org/apache/unomi/api/PersonalizationResult.java b/api/src/main/java/org/apache/unomi/api/PersonalizationResult.java
index 15c6ab5a5..0da3e2d53 100644
--- a/api/src/main/java/org/apache/unomi/api/PersonalizationResult.java
+++ b/api/src/main/java/org/apache/unomi/api/PersonalizationResult.java
@@ -25,22 +25,39 @@ import java.util.List;
import java.util.Map;
/**
- * A class to contain the result of a personalization, containing the list of content IDs as well as a changeType to
- * indicate if a profile and/or a session was modified.
+ * Outcome of a personalization request.
+ * Returns matching content ids, optional extra metadata (such as control
+ * group flags), and internal change codes when the resolved experience
+ * updated the profile or session.
*/
public class PersonalizationResult implements Serializable {
+ /**
+ * Key used in {@link #getAdditionalResultInfos()} to indicate if the
+ * personalization result was generated while running in a control group.
+ */
public final static String ADDITIONAL_RESULT_INFO_IN_CONTROL_GROUP = "inControlGroup";
+ /** Matching content identifiers for the resolved personalization. */
List<String> contentIds;
+ /** Extra key/value metadata returned to the client (for example control group flags). */
Map<String, Object> additionalResultInfos = new HashMap<>();
+ /** Internal change flags when resolution updated the profile or session. */
int changeType = EventService.NO_CHANGE;
+ /**
+ * Constructs an empty PersonalizationResult with default values.
+ */
public PersonalizationResult() {
}
+ /**
+ * Constructs a PersonalizationResult initialized with a
+ * list of content IDs.
+ * @param contentIds the list of matching ids for current personalization
+ */
public PersonalizationResult(List<String> contentIds) {
this.contentIds = contentIds;
}
@@ -53,6 +70,11 @@ public class PersonalizationResult implements Serializable {
return contentIds;
}
+ /**
+ * Sets the list of content IDs associated with this result.
+ * This overwrites any previously set content IDs.
+ * @param contentIds the new list of content IDs
+ */
public void setContentIds(List<String> contentIds) {
this.contentIds = contentIds;
}
@@ -65,6 +87,12 @@ public class PersonalizationResult implements Serializable {
return additionalResultInfos;
}
+ /**
+ * Sets the map containing additional result information. This map is useful
+ * for returning extra data to the client.
+ * @param additionalResultInfos a map of key/value pair for additional
+ * information, like: inControlGroup
+ */
public void setAdditionalResultInfos(Map<String, Object> additionalResultInfos) {
this.additionalResultInfos = additionalResultInfos;
}
@@ -74,7 +102,6 @@ public class PersonalizationResult implements Serializable {
* Control group are used to identify a profile or a session that should not get personalized results,
* instead the current profile/session should get a specific result (usually the same for all peoples falling in control group)
* Note: it's for now the responsibility of the client to decide what to do when the current personalization is under control group.
- *
* @return true in case current profile or session is in control group for the personalization.
*/
@XmlTransient
@@ -83,6 +110,13 @@ public class PersonalizationResult implements Serializable {
(Boolean) additionalResultInfos.get(ADDITIONAL_RESULT_INFO_IN_CONTROL_GROUP);
}
+ /**
+ * Sets whether this personalization result belongs to a control group by
+ * storing the boolean value in the internal additional result info map.
+ * @param inControlGroup true if the current profile or session is in
+ * control group for the
+ * personalization, false otherwise
+ */
public void setInControlGroup(boolean inControlGroup) {
this.additionalResultInfos.put(ADDITIONAL_RESULT_INFO_IN_CONTROL_GROUP, inControlGroup);
}
@@ -90,7 +124,6 @@ public class PersonalizationResult implements Serializable {
/**
* Change code in case the personalization resolution modified the profile or the session
* Only used internally, and will not be serialized either for storage or response payload.
- *
* @return change code
*/
@XmlTransient
@@ -98,6 +131,13 @@ public class PersonalizationResult implements Serializable {
return changeType;
}
+ /**
+ * Adds specified change flags to the current accumulated change type.
+ * This method uses bitwise OR operation to ensure that multiple changes
+ * are recorded without overwriting previous ones.
+ * @param changes The change code or flag(s) to add to the
+ * result's change type.
+ */
public void addChanges(int changes) {
this.changeType |= changes;
}
diff --git a/api/src/main/java/org/apache/unomi/api/PluginType.java b/api/src/main/java/org/apache/unomi/api/PluginType.java
index 1b75bff09..491cd9588 100644
--- a/api/src/main/java/org/apache/unomi/api/PluginType.java
+++ b/api/src/main/java/org/apache/unomi/api/PluginType.java
@@ -18,7 +18,9 @@
package org.apache.unomi.api;
/**
- * The interface for unomi plugins.
+ * Marker interface for Unomi plugin definition types.
+ * Implementations such as {@link PropertyMergeStrategyType} expose an id
+ * and OSGi filter so the runtime can locate the plugin implementation.
*/
public interface PluginType {
diff --git a/api/src/main/java/org/apache/unomi/api/Profile.java b/api/src/main/java/org/apache/unomi/api/Profile.java
index 76d9d63c4..ff83d068b 100644
--- a/api/src/main/java/org/apache/unomi/api/Profile.java
+++ b/api/src/main/java/org/apache/unomi/api/Profile.java
@@ -206,6 +206,7 @@ public class Profile extends Item implements SystemPropertiesItem {
/**
* @deprecated since 2.0.0 merge mechanism is now based on profile aliases, and this property is not used anymore
+ * @return the profile id this profile was merged with, or {@code null}
*/
@Deprecated
public String getMergedWith() {
@@ -214,6 +215,7 @@ public class Profile extends Item implements SystemPropertiesItem {
/**
* @deprecated since 2.0.0 merge mechanism is now based on profile aliases, and this property is not used anymore
+ * @param mergedWith the profile id this profile was merged with
*/
@Deprecated
public void setMergedWith(String mergedWith) {
diff --git a/api/src/main/java/org/apache/unomi/api/ProfileAlias.java b/api/src/main/java/org/apache/unomi/api/ProfileAlias.java
index 1434b029d..c7569df2f 100644
--- a/api/src/main/java/org/apache/unomi/api/ProfileAlias.java
+++ b/api/src/main/java/org/apache/unomi/api/ProfileAlias.java
@@ -19,8 +19,16 @@ package org.apache.unomi.api;
import java.util.Date;
+/**
+ * Maps a client-specific profile identifier to a canonical Unomi profile.
+ * Lets multiple applications reference the same visitor under different ids
+ * while sharing one merged profile record.
+ */
public class ProfileAlias extends Item {
+ /**
+ * The constant string used to identify this item type as a profile alias.
+ */
public static final String ITEM_TYPE = "profileAlias";
private String profileID;
@@ -31,37 +39,73 @@ public class ProfileAlias extends Item {
private Date modifiedTime;
+ /**
+ * Constructs an empty ProfileAlias object.
+ */
public ProfileAlias() {
}
+ /**
+ * Retrieves the unique identifier of the associated profile.
+ * @return The profile ID as a {@link String}.
+ */
public String getProfileID() {
return profileID;
}
+ /**
+ * Sets the unique identifier of the associated profile.
+ * @param profileID The profile ID to set.
+ */
public void setProfileID(String profileID) {
this.profileID = profileID;
}
+ /**
+ * Retrieves the client identifier associated with this alias.
+ * @return The client ID as a {@link String}, or null if not set.
+ */
public String getClientID() {
return clientID;
}
+ /**
+ * Sets the client identifier associated with this alias.
+ * @param clientID The client ID to set.
+ */
public void setClientID(String clientID) {
this.clientID = clientID;
}
+ /**
+ * Retrieves the date and time when this profile alias was created.
+ * @return The creation timestamp as a {@link java.util.Date}.
+ */
public Date getCreationTime() {
return creationTime;
}
+ /**
+ * Sets the date and time of creation for this profile alias.
+ * @param creationTime The creation timestamp to set.
+ */
public void setCreationTime(Date creationTime) {
this.creationTime = creationTime;
}
+ /**
+ * Retrieves the date and time when this profile alias was last modified.
+ * or null if no modification time has been recorded.
+ * @return The {@link java.util.Date} representing the modification time,
+ */
public Date getModifiedTime() {
return modifiedTime;
}
+ /**
+ * Sets the date and time when this profile alias was last modified.
+ * @param modifiedTime The new timestamp indicating the modification time.
+ */
public void setModifiedTime(Date modifiedTime) {
this.modifiedTime = modifiedTime;
}
diff --git a/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyExecutor.java b/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyExecutor.java
index c7dcd0171..88400a945 100644
--- a/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyExecutor.java
+++ b/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyExecutor.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api;
import java.util.List;
/**
- * A strategy algorithm to merge profile properties such as "adding integers", "using oldest value", "using most recent value", "merging lists", etc...
+ * Algorithm that merges two values for the same profile property.
+ * Implementations define strategies such as keep latest, sum numbers, or
+ * union lists when events update the same field.
*/
public interface PropertyMergeStrategyExecutor {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyType.java b/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyType.java
index 8a2249ec1..9596d8e63 100644
--- a/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyType.java
+++ b/api/src/main/java/org/apache/unomi/api/PropertyMergeStrategyType.java
@@ -21,7 +21,9 @@ import javax.xml.bind.annotation.XmlTransient;
import java.io.Serializable;
/**
- * A unomi plugin that defines a new property merge strategy.
+ * Plugin declaration for a profile property merge strategy.
+ * Merge strategies decide how conflicting property values are combined when
+ * several updates apply to the same profile field (sum, latest value, etc.).
*/
public class PropertyMergeStrategyType implements PluginType, Serializable {
@@ -32,13 +34,16 @@ public class PropertyMergeStrategyType implements PluginType, Serializable {
/**
* Retrieves the identifier for this PropertyMergeStrategyType.
- *
* @return the identifier for this PropertyMergeStrategyType
*/
public String getId() {
return id;
}
+ /**
+ * Sets the identifier for this PropertyMergeStrategyType.
+ * @param id the unique identifier to be set.
+ */
public void setId(String id) {
this.id = id;
}
@@ -47,22 +52,37 @@ public class PropertyMergeStrategyType implements PluginType, Serializable {
* Retrieves the OSGi filter used to identify the implementation associated with this PropertyMergeStrategyType. Filters take the following form:
* {@code (propertyMergeStrategyExecutorId=<id>)} where {@code id} corresponds to the value of the {@code propertyMergeStrategyExecutorId} service property in the
* Blueprint service definition for this PropertyMergeStrategyType.
- *
* @return the filter string used to identify the implementation associated with this PropertyMergeStrategyType
*/
public String getFilter() {
return filter;
}
+ /**
+ * Sets the OSGi filter used to identify the implementation associated with
+ * this PropertyMergeStrategyType.
+ * @param filter the filter string value.
+ */
public void setFilter(String filter) {
this.filter = filter;
}
+ /**
+ * Returns the OSGi bundle id of the plugin that registered this strategy.
+ * Used internally when resolving merge strategy implementations.
+ *
+ * @return the plugin bundle id
+ */
@XmlTransient
public long getPluginId() {
return pluginId;
}
+ /**
+ * Sets the OSGi bundle id of the plugin that registered this strategy.
+ *
+ * @param pluginId the plugin bundle id
+ */
public void setPluginId(long pluginId) {
this.pluginId = pluginId;
}
diff --git a/api/src/main/java/org/apache/unomi/api/PropertyType.java b/api/src/main/java/org/apache/unomi/api/PropertyType.java
index 090d7eec0..93ee1b226 100644
--- a/api/src/main/java/org/apache/unomi/api/PropertyType.java
+++ b/api/src/main/java/org/apache/unomi/api/PropertyType.java
@@ -26,12 +26,13 @@ import javax.xml.bind.annotation.XmlTransient;
import java.util.*;
/**
- * A user-defined profile or session property, specifying how possible values are constrained, if the value is multi-valued (a vector of values as opposed to a scalar value).
+ * Schema definition for a custom profile or session property.
+ * Declares value type, defaults, allowed ranges, merge strategy, and whether
+ * the property accepts multiple values.
*/
public class PropertyType extends MetadataItem {
/**
* The PropertyType ITEM_TYPE.
- *
* @see Item for a discussion of ITEM_TYPE
*/
public static final String ITEM_TYPE = "propertyType";
@@ -58,7 +59,6 @@ public class PropertyType extends MetadataItem {
/**
* Instantiates a new Property type with the specified Metadata.
- *
* @param metadata the metadata associated with the specified metadata
*/
public PropertyType(Metadata metadata) {
@@ -68,9 +68,7 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the target for this property type, indicating the type of elements this property type is defined for. For example, for property types attached to profiles, {@code
* target} would be {@code "profiles"}.
- *
* TODO: deprecated?
- *
* @return the target for this property type
*/
public String getTarget() {
@@ -79,9 +77,7 @@ public class PropertyType extends MetadataItem {
/**
* Sets the target for this property type.
- *
* TODO: deprecated?
- *
* @param target the target for this property type, indicating the type of elements this property type is defined for
*/
public void setTarget(String target) {
@@ -90,7 +86,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the identifier of the value type constraining values for properties using this PropertyType.
- *
* @return the value type identifier associated with values defined by this PropertyType
* @see ValueType
*/
@@ -101,7 +96,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the value type identifier.
- *
* @param valueTypeId the value type identifier
*/
public void setValueTypeId(String valueTypeId) {
@@ -110,7 +104,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the value type associated with values defined for properties using this PropertyType.
- *
* @return the value type associated with values defined for properties using this PropertyType
*/
@XmlTransient
@@ -120,7 +113,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the value type.
- *
* @param valueType the value type associated with values defined for properties using this PropertyType
*/
public void setValueType(ValueType valueType) {
@@ -129,7 +121,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the default value defined for property using this PropertyType.
- *
* @return the default value defined for property using this PropertyType
*/
public String getDefaultValue() {
@@ -138,7 +129,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the default value that properties using this PropertyType will use if no value is specified explicitly.
- *
* @param defaultValue the default value that properties using this PropertyType will use if no value is specified explicitly
*/
public void setDefaultValue(String defaultValue) {
@@ -147,9 +137,7 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the set of JCR properties from which properties of this type would be automatically initialized from.
- *
* TODO: remove from API?
- *
* @return the name of JCR properties properties of this type would be automatically initialized from
*/
public Set<String> getAutomaticMappingsFrom() {
@@ -159,7 +147,6 @@ public class PropertyType extends MetadataItem {
/**
* Specifies the set of JCR properties from which properties of this type would be automatically initialized from.
* TODO: remove from API?
- *
* @param automaticMappingsFrom the set of JCR properties from which properties of this type would be automatically initialized from
*/
public void setAutomaticMappingsFrom(Set<String> automaticMappingsFrom) {
@@ -168,7 +155,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the rank of this PropertyType for ordering purpose.
- *
* @return the rank of this PropertyType for ordering purpose
*/
public Double getRank() {
@@ -177,7 +163,6 @@ public class PropertyType extends MetadataItem {
/**
* Specifies the rank of this PropertyType for ordering purpose.
- *
* @param rank the rank of this PropertyType for ordering purpose
*/
public void setRank(Double rank) {
@@ -186,7 +171,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the identifier of the {@link PropertyMergeStrategyType} to be used in case profiles with properties using this PropertyType are being merged.
- *
* @return the identifier of the {@link PropertyMergeStrategyType} to be used in case profiles with properties using this PropertyType are being merged
*/
public String getMergeStrategy() {
@@ -195,7 +179,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the identifier of the {@link PropertyMergeStrategyType} to be used in case profiles with properties using this PropertyType are being merged
- *
* @param mergeStrategy the identifier of the {@link PropertyMergeStrategyType} to be used in case profiles with properties using this PropertyType are being merged
*/
public void setMergeStrategy(String mergeStrategy) {
@@ -204,7 +187,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the date ranges.
- *
* @return the date ranges
*/
public List<DateRange> getDateRanges() {
@@ -213,7 +195,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the date ranges.
- *
* @param dateRanges the date ranges
*/
public void setDateRanges(List<DateRange> dateRanges) {
@@ -222,7 +203,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the numeric ranges.
- *
* @return the numeric ranges
*/
public List<NumericRange> getNumericRanges() {
@@ -231,7 +211,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the numeric ranges.
- *
* @param numericRanges the numeric ranges
*/
public void setNumericRanges(List<NumericRange> numericRanges) {
@@ -240,7 +219,6 @@ public class PropertyType extends MetadataItem {
/**
* Retrieves the ip ranges.
- *
* @return the ip ranges
*/
public List<IpRange> getIpRanges() {
@@ -249,7 +227,6 @@ public class PropertyType extends MetadataItem {
/**
* Sets the ip ranges.
- *
* @param ipRanges the ip ranges
*/
public void setIpRanges(List<IpRange> ipRanges) {
@@ -258,7 +235,6 @@ public class PropertyType extends MetadataItem {
/**
* Whether properties using this property type are multi-valued.
- *
* @return {@code true} if properties of this type should be multi-valued, {@code false} otherwise
*/
public Boolean isMultivalued() {
@@ -267,7 +243,6 @@ public class PropertyType extends MetadataItem {
/**
* Specifies whether properties using this property type are multi-valued.
- *
* @param multivalued {@code true} if properties of this type should be multi-valued, {@code false} otherwise
*/
public void setMultivalued(Boolean multivalued) {
@@ -276,9 +251,7 @@ public class PropertyType extends MetadataItem {
/**
* Whether properties with this type are marked as protected. Protected properties can be displayed but their value cannot be changed.
- *
* TODO: rename to readOnly?
- *
* @return {@code true} if properties of this type are protected, {@code false} otherwise
*/
public Boolean isProtected() {
@@ -287,17 +260,26 @@ public class PropertyType extends MetadataItem {
/**
* Specifies whether properties with this type are marked as protected.
- *
* @param protekted {@code true} if properties of this type are protected, {@code false} otherwise
*/
public void setProtected(boolean protekted) {
this.protekted = protekted;
}
+ /**
+ * Retrieves the set of {@link PropertyType} objects that are considered
+ * children or subtypes of this property type.
+ * @return a set of child property types associated with this instance
+ */
public Set<PropertyType> getChildPropertyTypes() {
return childPropertyTypes;
}
+ /**
+ * Sets the collection of child property types for this property type.
+ * @param childPropertyTypes the set of {@link PropertyType} objects that
+ * are children or subtypes
+ */
public void setChildPropertyTypes(Set<PropertyType> childPropertyTypes) {
this.childPropertyTypes = childPropertyTypes;
}
diff --git a/api/src/main/java/org/apache/unomi/api/Scope.java b/api/src/main/java/org/apache/unomi/api/Scope.java
index a8fa35137..1618f6f24 100644
--- a/api/src/main/java/org/apache/unomi/api/Scope.java
+++ b/api/src/main/java/org/apache/unomi/api/Scope.java
@@ -18,7 +18,9 @@
package org.apache.unomi.api;
/**
- * Object representing a scope.
+ * Named isolation boundary for context data in Unomi.
+ * Profiles, sessions, events, and definitions belong to a scope (often a
+ * site or application) so data from one digital property does not mix with another.
*/
public class Scope extends MetadataItem {
diff --git a/api/src/main/java/org/apache/unomi/api/ServerInfo.java b/api/src/main/java/org/apache/unomi/api/ServerInfo.java
index 7b80f9487..4f973cf24 100644
--- a/api/src/main/java/org/apache/unomi/api/ServerInfo.java
+++ b/api/src/main/java/org/apache/unomi/api/ServerInfo.java
@@ -23,7 +23,9 @@ import java.util.List;
import java.util.Map;
/**
- * Basic information about a Unomi server
+ * High-level description of a running Unomi instance.
+ * Exposes version, build, SCM branch, timestamp, and the list of event types
+ * the server can handle. Clients call this to discover server capabilities.
*/
public class ServerInfo {
@@ -39,77 +41,158 @@ public class ServerInfo {
private List<String> logoLines = new ArrayList<>();
+ /**
+ * Constructs a new ServerInfo instance.
+ */
public ServerInfo() {
}
+ /**
+ * Returns the unique identifier of the server.
+ * @return The server's identifier string.
+ */
public String getServerIdentifier() {
return serverIdentifier;
}
+ /**
+ * Sets the unique identifier for this server information.
+ * @param serverIdentifier The unique identifier to set.
+ */
public void setServerIdentifier(String serverIdentifier) {
this.serverIdentifier = serverIdentifier;
}
+ /**
+ * Returns the version string of the server.
+ * @return The server's version number.
+ */
public String getServerVersion() {
return serverVersion;
}
+ /**
+ * Sets the version string for this server information.
+ * @param serverVersion The version string to set.
+ */
public void setServerVersion(String serverVersion) {
this.serverVersion = serverVersion;
}
+ /**
+ * Returns the build number of the server.
+ * @return The server's build number as a string.
+ */
public String getServerBuildNumber() {
return serverBuildNumber;
}
+ /**
+ * Sets the build number for this server information.
+ * @param serverBuildNumber The build number to set.
+ */
public void setServerBuildNumber(String serverBuildNumber) {
this.serverBuildNumber = serverBuildNumber;
}
+ /**
+ * Returns the date associated with the server's build.
+ * @return The {@link java.util.Date} representing the build date.
+ */
public Date getServerBuildDate() {
return serverBuildDate;
}
+ /**
+ * Sets the build date of the server.
+ * @param serverBuildDate the build date of the server
+ */
public void setServerBuildDate(Date serverBuildDate) {
this.serverBuildDate = serverBuildDate;
}
+ /**
+ * Retrieves the timestamp associated with the server information.
+ * @return the server's timestamp string
+ */
public String getServerTimestamp() {
return serverTimestamp;
}
+ /**
+ * Sets the timestamp for the server information.
+ * @param serverTimestamp the server's timestamp (e.g., YYYYMMDDHHmmss)
+ */
public void setServerTimestamp(String serverTimestamp) {
this.serverTimestamp = serverTimestamp;
}
+ /**
+ * Retrieves the source control management branch name of the server.
+ * @return the SCM branch name
+ */
public String getServerScmBranch() {
return serverScmBranch;
}
+ /**
+ * Sets the source control management branch name for
+ * the server information.
+ * @param serverScmBranch the SCM branch name
+ */
public void setServerScmBranch(String serverScmBranch) {
this.serverScmBranch = serverScmBranch;
}
+ /**
+ * Retrieves the list of event types supported by this server instance.
+ * @return a list of {@link EventInfo} objects representing
+ * available event types
+ */
public List<EventInfo> getEventTypes() {
return eventTypes;
}
+ /**
+ * Sets the collection of event types associated with
+ * the server information.
+ * @param eventTypes the list of event types to set
+ */
public void setEventTypes(List<EventInfo> eventTypes) {
this.eventTypes = eventTypes;
}
+ /**
+ * Retrieves a map containing various capabilities reported by the server.
+ * @return a map where keys are capability names and values are descriptions
+ */
public Map<String, String> getCapabilities() {
return capabilities;
}
+ /**
+ * Sets the map containing various capabilities reported
+ * by the Unomi server.
+ * @param capabilities The map of capability names and descriptions.
+ */
public void setCapabilities(Map<String, String> capabilities) {
this.capabilities = capabilities;
}
+ /**
+ * Retrieves the list of strings used to display the server's logo lines.
+ * @return The {@link java.util.List<java.lang.String>}
+ * containing the logo lines.
+ */
public List<String> getLogoLines() {
return logoLines;
}
+ /**
+ * Sets the list of strings that represent the server's logo lines
+ * for display purposes.
+ * @param logoLines The list of strings defining the logo lines.
+ */
public void setLogoLines(List<String> logoLines) {
this.logoLines = logoLines;
}
diff --git a/api/src/main/java/org/apache/unomi/api/Session.java b/api/src/main/java/org/apache/unomi/api/Session.java
index 8ca067720..11496be61 100644
--- a/api/src/main/java/org/apache/unomi/api/Session.java
+++ b/api/src/main/java/org/apache/unomi/api/Session.java
@@ -222,10 +222,20 @@ public class Session extends Item implements TimestampedItem, SystemPropertiesIt
this.size = size;
}
+ /**
+ * Retrieves the scope this session belongs to.
+ *
+ * @return the session scope identifier
+ */
public String getScope() {
return scope;
}
+ /**
+ * Sets the scope this session belongs to.
+ *
+ * @param scope the session scope identifier
+ */
public void setScope(String scope) {
this.scope = scope;
}
diff --git a/api/src/main/java/org/apache/unomi/api/SystemPropertiesItem.java b/api/src/main/java/org/apache/unomi/api/SystemPropertiesItem.java
index e191562cc..45786d5aa 100644
--- a/api/src/main/java/org/apache/unomi/api/SystemPropertiesItem.java
+++ b/api/src/main/java/org/apache/unomi/api/SystemPropertiesItem.java
@@ -19,7 +19,9 @@ package org.apache.unomi.api;
import java.util.Map;
/**
- * An Item that is holding system properties.
+ * {@link Item} that stores system-level properties in a map.
+ * System properties are internal or cross-cutting values kept separately
+ * from visitor profile properties.
*/
public interface SystemPropertiesItem {
diff --git a/api/src/main/java/org/apache/unomi/api/TimestampedItem.java b/api/src/main/java/org/apache/unomi/api/TimestampedItem.java
index 0a0799a15..f383efab8 100644
--- a/api/src/main/java/org/apache/unomi/api/TimestampedItem.java
+++ b/api/src/main/java/org/apache/unomi/api/TimestampedItem.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api;
import java.util.Date;
/**
- * A context-server entity that is timestamped.
+ * {@link Item} that records when it was created or last modified.
+ * Event and profile-like types implement this interface so retention,
+ * ordering, and auditing can use consistent timestamps.
*/
public interface TimestampedItem {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/Topic.java b/api/src/main/java/org/apache/unomi/api/Topic.java
index 03d789d38..dbddfd346 100644
--- a/api/src/main/java/org/apache/unomi/api/Topic.java
+++ b/api/src/main/java/org/apache/unomi/api/Topic.java
@@ -16,26 +16,48 @@
*/
package org.apache.unomi.api;
+/**
+ * Named category tag stored as an {@link Item}.
+ * Topics group configuration or content entities so administrators can
+ * organize and search related objects across the context server.
+ */
public class Topic extends Item {
+ /** Defines the item type string used for Topic entities. */
public static final String ITEM_TYPE = "topic";
private String topicId;
private String name;
+ /**
+ * Retrieves the unique identifier of this topic.
+ * @return The {@link String} ID of the topic.
+ */
public String getTopicId() {
return topicId;
}
+ /**
+ * Sets the unique identifier for this topic.
+ * @param topicId the unique ID to set.
+ */
public void setTopicId(String topicId) {
this.topicId = topicId;
}
+ /**
+ * Retrieves the name of the topic.
+ * @return The {@link String} name of the topic.
+ */
public String getName() {
return name;
}
+ /**
+ * Sets the display name for this topic.
+ * @param name the new name to set.
+ */
public void setName(String name) {
this.name = name;
}
diff --git a/api/src/main/java/org/apache/unomi/api/ValueType.java b/api/src/main/java/org/apache/unomi/api/ValueType.java
index d470a694b..9895837f0 100644
--- a/api/src/main/java/org/apache/unomi/api/ValueType.java
+++ b/api/src/main/java/org/apache/unomi/api/ValueType.java
@@ -23,7 +23,9 @@ import java.util.LinkedHashSet;
import java.util.Set;
/**
- * A value type to be used to constrain property values.
+ * Definition of allowed values for a {@link PropertyType}.
+ * Value types describe validation rules, ranges, and serializers so profile
+ * and session properties stay consistent with their schema.
*/
public class ValueType implements PluginType, Serializable {
@@ -108,11 +110,19 @@ public class ValueType implements PluginType, Serializable {
this.descriptionKey = descriptionKey;
}
+ /**
+ * {@inheritDoc}
+ */
+ @Override
@XmlTransient
public long getPluginId() {
return pluginId;
}
+ /**
+ * {@inheritDoc}
+ */
+ @Override
public void setPluginId(long pluginId) {
this.pluginId = pluginId;
}
diff --git a/api/src/main/java/org/apache/unomi/api/actions/ActionExecutor.java b/api/src/main/java/org/apache/unomi/api/actions/ActionExecutor.java
index 6f33b9e02..4941df8bf 100644
--- a/api/src/main/java/org/apache/unomi/api/actions/ActionExecutor.java
+++ b/api/src/main/java/org/apache/unomi/api/actions/ActionExecutor.java
@@ -21,7 +21,9 @@ import org.apache.unomi.api.Event;
import org.apache.unomi.api.services.EventService;
/**
- * A piece of code that performs a specified {@link Action}, given a triggering {@link Event}
+ * Runtime implementation of an {@link org.apache.unomi.api.actions.Action}.
+ * When a rule fires, executors perform the configured action (send email,
+ * set property, etc.) for the triggering {@link Event}.
*/
public interface ActionExecutor {
diff --git a/api/src/main/java/org/apache/unomi/api/actions/ActionPostExecutor.java b/api/src/main/java/org/apache/unomi/api/actions/ActionPostExecutor.java
index e80d6cd95..923ba31cc 100644
--- a/api/src/main/java/org/apache/unomi/api/actions/ActionPostExecutor.java
+++ b/api/src/main/java/org/apache/unomi/api/actions/ActionPostExecutor.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api.actions;
import org.apache.unomi.api.rules.Rule;
/**
- * An action to be executed after all {@link Rule}-derived have been processed.
+ * Hook executed after all rule actions for an event have run.
+ * Use post-executors for cleanup, logging, or follow-up work that must
+ * happen once per event after the main action chain completes.
*/
public interface ActionPostExecutor {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/actions/ActionType.java b/api/src/main/java/org/apache/unomi/api/actions/ActionType.java
index bf6fb477a..f652578b0 100644
--- a/api/src/main/java/org/apache/unomi/api/actions/ActionType.java
+++ b/api/src/main/java/org/apache/unomi/api/actions/ActionType.java
@@ -31,7 +31,9 @@ import static org.apache.unomi.api.utils.YamlUtils.circularRef;
import static org.apache.unomi.api.utils.YamlUtils.toYamlValue;
/**
- * A type definition for {@link Action}s.
+ * Declarative definition of an action that rules can trigger.
+ * Action types describe parameters and point to the {@link ActionExecutor}
+ * implementation that performs the work at runtime.
*/
public class ActionType extends MetadataItem implements PluginType, YamlConvertible {
/** Item type identifier for action types. */
diff --git a/api/src/main/java/org/apache/unomi/api/campaigns/Campaign.java b/api/src/main/java/org/apache/unomi/api/campaigns/Campaign.java
index c932475c0..ba0936345 100644
--- a/api/src/main/java/org/apache/unomi/api/campaigns/Campaign.java
+++ b/api/src/main/java/org/apache/unomi/api/campaigns/Campaign.java
@@ -26,7 +26,9 @@ import org.apache.unomi.api.goals.Goal;
import java.util.Date;
/**
- * A goal-oriented, time-limited marketing operation that needs to be evaluated for return on investment performance by tracking the ratio of visits to conversions.
+ * Time-bounded marketing program built around {@link org.apache.unomi.api.goals.Goal}s.
+ * Campaigns track entry conditions, duration, and conversion metrics so teams
+ * can measure ROI for a specific promotion or experiment.
*/
public class Campaign extends MetadataItem {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/campaigns/CampaignDetail.java b/api/src/main/java/org/apache/unomi/api/campaigns/CampaignDetail.java
index db35100a8..adeb4c1f6 100644
--- a/api/src/main/java/org/apache/unomi/api/campaigns/CampaignDetail.java
+++ b/api/src/main/java/org/apache/unomi/api/campaigns/CampaignDetail.java
@@ -18,9 +18,9 @@
package org.apache.unomi.api.campaigns;
/**
- * Details about a {@link Campaign}.
- *
- * Created by kevan on 03/06/15.
+ * Aggregated metrics for a {@link Campaign}.
+ * Summarizes participation and performance figures used in campaign reporting
+ * dashboards.
*/
public class CampaignDetail {
private long engagedProfiles = 0;
diff --git a/api/src/main/java/org/apache/unomi/api/conditions/Condition.java b/api/src/main/java/org/apache/unomi/api/conditions/Condition.java
index 248d1c43a..5ef081d22 100644
--- a/api/src/main/java/org/apache/unomi/api/conditions/Condition.java
+++ b/api/src/main/java/org/apache/unomi/api/conditions/Condition.java
@@ -38,7 +38,9 @@ import static org.apache.unomi.api.utils.YamlUtils.circularRef;
import static org.apache.unomi.api.utils.YamlUtils.toYamlValue;
/**
- * A set of elements that can be evaluated.
+ * Boolean expression evaluated against context (profiles, events, sessions).
+ * Conditions combine parameters and nested sub-conditions; segments, rules,
+ * and queries all use them to decide when logic applies.
*/
public class Condition implements Serializable, YamlConvertible {
private static final long serialVersionUID = 7584522402785053206L;
diff --git a/api/src/main/java/org/apache/unomi/api/conditions/ConditionValidation.java b/api/src/main/java/org/apache/unomi/api/conditions/ConditionValidation.java
index 9dfd5feaf..4053c5ae5 100644
--- a/api/src/main/java/org/apache/unomi/api/conditions/ConditionValidation.java
+++ b/api/src/main/java/org/apache/unomi/api/conditions/ConditionValidation.java
@@ -26,7 +26,9 @@ import java.util.Set;
import static org.apache.unomi.api.utils.YamlUtils.setToSortedList;
/**
- * Validation metadata for condition parameters
+ * Rules that constrain values allowed in a {@link Condition} parameter.
+ * Segment builders and the validation service use this metadata to reject
+ * invalid parameter values before save.
*/
public class ConditionValidation implements Serializable, YamlConvertible {
private static final long serialVersionUID = 1L;
diff --git a/api/src/main/java/org/apache/unomi/api/exceptions/BadSegmentConditionException.java b/api/src/main/java/org/apache/unomi/api/exceptions/BadSegmentConditionException.java
index 8bd908a2c..d8ee9ea93 100644
--- a/api/src/main/java/org/apache/unomi/api/exceptions/BadSegmentConditionException.java
+++ b/api/src/main/java/org/apache/unomi/api/exceptions/BadSegmentConditionException.java
@@ -18,7 +18,9 @@
package org.apache.unomi.api.exceptions;
/**
- * Exception thrown when a segment condition is invalid or cannot be used.
+ * Raised when a segment condition is malformed or cannot be evaluated.
+ * Indicates the condition JSON or references are invalid so callers can
+ * surface a clear error to administrators.
*/
public class BadSegmentConditionException extends RuntimeException {
diff --git a/api/src/main/java/org/apache/unomi/api/goals/Goal.java b/api/src/main/java/org/apache/unomi/api/goals/Goal.java
index d2cac5db8..efca37cc8 100644
--- a/api/src/main/java/org/apache/unomi/api/goals/Goal.java
+++ b/api/src/main/java/org/apache/unomi/api/goals/Goal.java
@@ -42,6 +42,7 @@ import static org.apache.unomi.api.utils.YamlUtils.toYamlValue;
* </ul>
*/
public class Goal extends MetadataItem implements YamlConvertible {
+ /** The constant string used to identify this object as a goal item type. */
public static final String ITEM_TYPE = "goal";
private static final long serialVersionUID = 6131648013470949983L;
private Condition startEvent;
@@ -50,9 +51,20 @@ public class Goal extends MetadataItem implements YamlConvertible {
private String campaignId;
+ /**
+ * Constructs an empty {@link Goal} instance.
+ * This constructor is typically used when initializing a goal object
+ * programmatically before setting its specific metadata and events.
+ */
public Goal() {
}
+ /**
+ * Constructs a {@link Goal} instance initialized with
+ * the provided metadata.
+ * to be identified or configured within a system context.
+ * @param metadata The metadata to associate with this goal, allowing it
+ */
public Goal(Metadata metadata) {
super(metadata);
}
@@ -60,39 +72,58 @@ public class Goal extends MetadataItem implements YamlConvertible {
/**
* Retrieves the {@link Condition} determining the goal's start event if any, used for more complex goals where an action has to be accomplished first before evaluating the
* success of the final goal (funnel goal for example).
- *
* @return the condition associated with the start event for this goal or {@code null} if no such event exists
*/
public Condition getStartEvent() {
return startEvent;
}
+ /**
+ * Sets the condition that must occur for the goal to begin tracking.
+ * This is used when the goal's success depends on an initial event
+ * occurring, such as in a funnel scenario.
+ * @param startEvent The {@link Condition} defining the starting event, or
+ * null if no specific start event is required.
+ */
public void setStartEvent(Condition startEvent) {
this.startEvent = startEvent;
}
/**
* Retrieves the {@link Condition} determining the target event which needs to occur to consider the goal accomplished.
- *
* @return the condition associated with the event determining if the goal is reached or not
*/
public Condition getTargetEvent() {
return targetEvent;
}
+ /**
+ * Sets the condition that must occur for the goal to be
+ * considered accomplished.
+ * This defines the target event that determines whether the
+ * goal has been reached.
+ * @param targetEvent The {@link Condition} defining the target event, or
+ * null if no specific target event is required.
+ */
public void setTargetEvent(Condition targetEvent) {
this.targetEvent = targetEvent;
}
/**
* Retrieves the identifier of the campaign this goal is part of, if any.
- *
* @return the identifier of the campaign this goal is part of, or {@code null} if this goal is not part of any campaign
*/
public String getCampaignId() {
return campaignId;
}
+ /**
+ * Sets the identifier of the campaign to which this goal belongs.
+ * This allows goals to be scoped and managed within a specific
+ * marketing campaign context.
+ * @param campaignId The unique ID of the associated campaign, or
+ * {@code null} if the goal is not tied to a campaign.
+ */
public void setCampaignId(String campaignId) {
this.campaignId = campaignId;
}
@@ -100,7 +131,6 @@ public class Goal extends MetadataItem implements YamlConvertible {
/**
* Converts this goal to a Map structure for YAML output.
* Implements YamlConvertible interface with circular reference detection.
- *
* @param visited set of already visited objects to prevent infinite recursion (may be null)
* @return a Map representation of this goal
*/
diff --git a/api/src/main/java/org/apache/unomi/api/goals/GoalReport.java b/api/src/main/java/org/apache/unomi/api/goals/GoalReport.java
index 1d4413805..0211194ba 100644
--- a/api/src/main/java/org/apache/unomi/api/goals/GoalReport.java
+++ b/api/src/main/java/org/apache/unomi/api/goals/GoalReport.java
@@ -21,28 +21,51 @@ import java.io.Serializable;
import java.util.List;
/**
- * Report information about a {@link Goal}.
+ * Performance statistics for a {@link org.apache.unomi.api.goals.Goal}.
+ * Contains counts and rates (starts, conversions, etc.) used to measure
+ * whether visitors complete the tracked goal.
*/
public class GoalReport implements Serializable {
private static final long serialVersionUID = -9150361970326342064L;
private Stat globalStats;
private List<Stat> split;
+ /**
+ * Constructs a new GoalReport instance.
+ */
public GoalReport() {
}
+ /**
+ * Retrieves the global statistics associated with this report.
+ * @return The {@link Stat} containing global statistics.
+ */
public Stat getGlobalStats() {
return globalStats;
}
+ /**
+ * Sets the global statistics for this report.
+ * @param globalStats The {@link Stat} object representing
+ * the global statistics.
+ */
public void setGlobalStats(Stat globalStats) {
this.globalStats = globalStats;
}
+ /**
+ * Retrieves the list of split statistics associated with this report.
+ * @return A {@link List} of {@link Stat} objects representing the splits.
+ */
public List<Stat> getSplit() {
return split;
}
+ /**
+ * Sets the list of split statistics for this report.
+ * @param split The {@link List} of {@link Stat} objects
+ * defining the splits.
+ */
public void setSplit(List<Stat> split) {
this.split = split;
}
@@ -58,45 +81,95 @@ public class GoalReport implements Serializable {
private double conversionRate;
private double percentage;
+ /**
+ * Constructs a new {@code Stat} instance.
+ */
public Stat() {
}
+ /**
+ * Retrieves the key associated with this statistic.
+ * @return The unique identifier (key) for the stat.
+ */
public String getKey() {
return key;
}
+ /**
+ * Sets the key used to identify this statistic.
+ * @param key The unique string key.
+ */
public void setKey(String key) {
this.key = key;
}
+ /**
+ * Retrieves the starting count of records analyzed.
+ * @return The total number of records at the start count.
+ */
public long getStartCount() {
return startCount;
}
+ /**
+ * Sets the initial count for this statistic.
+ * @param startCount The total number of records.
+ */
public void setStartCount(long startCount) {
this.startCount = startCount;
}
+ /**
+ * Retrieves the target count of successful records.
+ * @return The number of records that met the target criteria.
+ */
public long getTargetCount() {
return targetCount;
}
+ /**
+ * Sets the target count for this statistic.
+ * @param targetCount The desired or measured target count.
+ */
public void setTargetCount(long targetCount) {
this.targetCount = targetCount;
}
+ /**
+ * Retrieves the calculated conversion rate (Target
+ * Count / Start Count).
+ * @return The conversion rate as a double value.
+ */
public double getConversionRate() {
return conversionRate;
}
+ /**
+ * Sets the conversion rate statistic.
+ * This value is typically calculated as a ratio of successful
+ * targets to starting counts.
+ * @param conversionRate the calculated conversion rate (target
+ * count / start count).
+ */
public void setConversionRate(double conversionRate) {
this.conversionRate = conversionRate;
}
+ /**
+ * Retrieves the percentage value stored in this statistic.
+ * This value represents a proportion, often relative to another total.
+ * @return the percentage value.
+ */
public double getPercentage() {
return percentage;
}
+ /**
+ * Sets the calculated percentage for this goal report statistic.
+ * This value is typically derived by dividing target counts by
+ * a larger total count.
+ * @param percentage the calculated percentage value.
+ */
public void setPercentage(double percentage) {
this.percentage = percentage;
}
diff --git a/api/src/main/java/org/apache/unomi/api/lists/UserList.java b/api/src/main/java/org/apache/unomi/api/lists/UserList.java
index dc82b89b5..35d99d446 100644
--- a/api/src/main/java/org/apache/unomi/api/lists/UserList.java
+++ b/api/src/main/java/org/apache/unomi/api/lists/UserList.java
@@ -22,7 +22,9 @@ import org.apache.unomi.api.Metadata;
import org.apache.unomi.api.MetadataItem;
/**
- * Created by amidani on 24/03/2017.
+ * Named list of profile identifiers maintained for campaigns or exports.
+ * User lists let marketers target or exclude a fixed audience without
+ * defining a dynamic segment.
*/
public class UserList extends MetadataItem{
diff --git a/api/src/main/java/org/apache/unomi/api/query/DateRange.java b/api/src/main/java/org/apache/unomi/api/query/DateRange.java
index 47390b3d8..029073759 100644
--- a/api/src/main/java/org/apache/unomi/api/query/DateRange.java
+++ b/api/src/main/java/org/apache/unomi/api/query/DateRange.java
@@ -20,36 +20,65 @@ package org.apache.unomi.api.query;
import java.io.Serializable;
/**
- * A data range.
+ * Named inclusive date interval used in queries and aggregations.
+ * Pairs a label ({@code key}) with {@code from} and {@code to} bounds so
+ * conditions can match events or profiles inside a calendar window.
*/
public class DateRange implements Serializable {
private String key;
private Object from;
private Object to;
+ /**
+ * Constructs a new {@link DateRange} instance.
+ */
public DateRange() {
}
+ /**
+ * Retrieves the unique key associated with this date range.
+ * @return The string key of the range.
+ */
public String getKey() {
return key;
}
+ /**
+ * Sets the unique identifier (key) for this date range.
+ * @param key the key to set
+ */
public void setKey(String key) {
this.key = key;
}
+ /**
+ * Retrieves the starting value (from) of the date range.
+ * @return The object representing the start time or value.
+ */
public Object getFrom() {
return from;
}
+ /**
+ * Sets the starting value (from) for this date range.
+ * @param from the starting value to set
+ */
public void setFrom(Object from) {
this.from = from;
}
+ /**
+ * Retrieves the ending value (to) of the date range.
+ * @return The object representing the end time or value.
+ */
public Object getTo() {
return to;
}
+ /**
+ * Sets the ending value (to) for this date range.
+ * @param to the ending value to set
+ */
public void setTo(Object to) {
this.to = to;
}
diff --git a/api/src/main/java/org/apache/unomi/api/query/IpRange.java b/api/src/main/java/org/apache/unomi/api/query/IpRange.java
index 411f58598..b33f16dcc 100644
--- a/api/src/main/java/org/apache/unomi/api/query/IpRange.java
+++ b/api/src/main/java/org/apache/unomi/api/query/IpRange.java
@@ -20,36 +20,65 @@ package org.apache.unomi.api.query;
import java.io.Serializable;
/**
- * An IP address range.
+ * Named inclusive IP address interval for geo or network filtering.
+ * Used in segment conditions to match visitors whose IP falls between
+ * the configured lower and upper bounds.
*/
public class IpRange implements Serializable {
private String key;
private String from;
private String to;
+ /**
+ * Constructs an empty {@link IpRange} instance.
+ */
public IpRange() {
}
+ /**
+ * Retrieves the unique key associated with this IP range.
+ * @return The string key identifying the range.
+ */
public String getKey() {
return key;
}
+ /**
+ * Sets the unique identifier (key) for this IP range.
+ * @param key The key to assign to the range.
+ */
public void setKey(String key) {
this.key = key;
}
+ /**
+ * Retrieves the starting IP address string of the range.
+ * @return The 'from' boundary of the IP range.
+ */
public String getFrom() {
return from;
}
+ /**
+ * Sets the starting IP address string for this range.
+ * @param from The start boundary of the IP range.
+ */
public void setFrom(String from) {
this.from = from;
}
+ /**
+ * Retrieves the ending IP address string of the range.
+ * @return The 'to' boundary of the IP range.
+ */
public String getTo() {
return to;
}
+ /**
+ * Sets the ending IP address string for this range.
+ * @param to The end boundary of the IP range.
+ */
public void setTo(String to) {
this.to = to;
}
diff --git a/api/src/main/java/org/apache/unomi/api/query/NumericRange.java b/api/src/main/java/org/apache/unomi/api/query/NumericRange.java
index 149a35805..bb8933785 100644
--- a/api/src/main/java/org/apache/unomi/api/query/NumericRange.java
+++ b/api/src/main/java/org/apache/unomi/api/query/NumericRange.java
@@ -20,36 +20,66 @@ package org.apache.unomi.api.query;
import java.io.Serializable;
/**
- * A numeric range.
+ * Named inclusive numeric interval for query filters.
+ * Stores a label plus lower and upper bounds so conditions can match
+ * numeric profile or event properties in a range.
*/
public class NumericRange implements Serializable {
private String key;
private Double from;
private Double to;
+ /**
+ * Constructs a new NumericRange object.
+ */
public NumericRange() {
}
+ /**
+ * Retrieves the unique key associated with this numeric range.
+ * @return The string key identifying the range.
+ */
public String getKey() {
return key;
}
+ /**
+ * Sets the unique identifier (key) for this numeric range.
+ * @param key the key to set
+ */
public void setKey(String key) {
this.key = key;
}
+ /**
+ * Retrieves the starting value of the numeric range.
+ * @return The lower bound (inclusive start) of the
+ * range, or null if not set.
+ */
public Double getFrom() {
return from;
}
+ /**
+ * Sets the starting value for this numeric range.
+ * @param from the inclusive starting value of the range
+ */
public void setFrom(Double from) {
this.from = from;
}
+ /**
+ * Retrieves the ending value of the numeric range.
+ * @return The upper bound (inclusive end) of the range, or null if not set.
+ */
public Double getTo() {
return to;
}
+ /**
+ * Sets the ending value for this numeric range.
+ * @param to the inclusive ending value of the range
+ */
public void setTo(Double to) {
this.to = to;
}
diff --git a/api/src/main/java/org/apache/unomi/api/query/Query.java b/api/src/main/java/org/apache/unomi/api/query/Query.java
index 48e0c1a6b..bcfc9e3d0 100644
--- a/api/src/main/java/org/apache/unomi/api/query/Query.java
+++ b/api/src/main/java/org/apache/unomi/api/query/Query.java
@@ -22,9 +22,9 @@ import org.apache.unomi.api.conditions.Condition;
import java.io.Serializable;
/**
- * A query wrapper gathering all elements needed for a potentially complex CXS query: {@link Condition}, offset, limit, sorting specification, etc.
- *
- * Created by kevan on 14/05/15.
+ * Full specification for a context server search or aggregation.
+ * Combines a {@link Condition}, paging (offset/limit), sort order, and
+ * optional aggregate definitions in one request object.
*/
public class Query implements Serializable {
private String text;
@@ -44,7 +44,6 @@ public class Query implements Serializable {
/**
* Retrieves the text to be used in full-text searches, if any.
- *
* @return the text to be used in full-text searches or {@code null} if no full-text search is needed for this Query
*/
public String getText() {
@@ -53,7 +52,6 @@ public class Query implements Serializable {
/**
* Sets to be used in full-text searches
- *
* @param text the text to be used in full-text searches or {@code null} if no full-text search is needed for this Query
*/
public void setText(String text) {
@@ -63,7 +61,6 @@ public class Query implements Serializable {
/**
* Retrieves the offset of the first element to be retrieved
- *
* @return zero or a positive integer specifying the position of the first item to be retrieved in the total ordered collection of matching items
*/
public int getOffset() {
@@ -72,7 +69,6 @@ public class Query implements Serializable {
/**
* Sets the offset of the first element to be retrieved
- *
* @param offset zero or a positive integer specifying the position of the first item to be retrieved in the total ordered collection of matching items
*/
public void setOffset(int offset) {
@@ -81,7 +77,6 @@ public class Query implements Serializable {
/**
* Retrieves the number of elements to retrieve.
- *
* @return a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
*/
public int getLimit() {
@@ -90,7 +85,6 @@ public class Query implements Serializable {
/**
* Sets the number of elements to retrieve.
- *
* @param limit a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
*/
public void setLimit(int limit) {
@@ -99,7 +93,6 @@ public class Query implements Serializable {
/**
* Retrieves the sorting specifications for this Query in String format, if any.
- *
* @return an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements
* according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is
* optionally followed by a column ({@code :}) and an order specifier: {@code asc} or {@code desc}.
@@ -110,7 +103,6 @@ public class Query implements Serializable {
/**
* Sets the String representation of the sorting specifications for this Query if any. See {@link #getSortby()} method documentation for format.
- *
* @param sortby the String representation of the sorting specifications for this Query or {@code null} if no sorting is required
*/
public void setSortby(String sortby) {
@@ -119,7 +111,6 @@ public class Query implements Serializable {
/**
* Retrieves the {@link Condition} associated with this Query.
- *
* @return the {@link Condition} associated with this Query
*/
public Condition getCondition() {
@@ -128,7 +119,6 @@ public class Query implements Serializable {
/**
* Sets the {@link Condition} associated with this Query.
- *
* @param condition the {@link Condition} associated with this Query
*/
public void setCondition(Condition condition) {
@@ -137,7 +127,6 @@ public class Query implements Serializable {
/**
* Determines whether or not an index refresh is needed before performing this Query
- *
* @return {@code true} if an index refresh is needed before performing this Query, {@code false} otherwise
*/
public boolean isForceRefresh() {
@@ -146,25 +135,56 @@ public class Query implements Serializable {
/**
* Specifies whether or not an index refresh is needed before performing this Query.
- *
* @param forceRefresh {@code true} if an index refresh is needed before performing this Query, {@code false} otherwise
*/
public void setForceRefresh(boolean forceRefresh) {
this.forceRefresh = forceRefresh;
}
+ /**
+ * Retrieves the unique identifier used to continue a
+ * scrolling search session.
+ * This identifier must be provided when performing subsequent searches
+ * that rely on the results of a previous query.
+ * @return the scroll identifier, or {@code null} if no
+ * scroll session is active.
+ */
public String getScrollIdentifier() {
return scrollIdentifier;
}
+ /**
+ * Sets the unique identifier required to continue a
+ * scrolling search session.
+ * This value should be obtained from the results of a previous query when
+ * performing subsequent searches that rely on the continuity of results.
+ * @param scrollIdentifier the scroll identifier used for continuation, or
+ * {@code null} if no scroll is needed.
+ */
public void setScrollIdentifier(String scrollIdentifier) {
this.scrollIdentifier = scrollIdentifier;
}
+ /**
+ * Retrieves the configured time validity period for the
+ * current scroll session.
+ * This value determines how long the search results remain valid for
+ * continuation queries.
+ * @return the string representation of the time validity (e.g., "10m"), or
+ * {@code null} if no specific validity is set.
+ */
public String getScrollTimeValidity() {
return scrollTimeValidity;
}
+ /**
+ * Sets the time validity period for the current scroll session.
+ * This value specifies how long the search results remain available for
+ * continuation queries.
+ * @param scrollTimeValidity the string representation of the time validity
+ * (e.g., "10m"), or {@code null} if no specific
+ * validity is required.
+ */
public void setScrollTimeValidity(String scrollTimeValidity) {
this.scrollTimeValidity = scrollTimeValidity;
}
diff --git a/api/src/main/java/org/apache/unomi/api/rules/RuleStatistics.java b/api/src/main/java/org/apache/unomi/api/rules/RuleStatistics.java
index 4dd18c79b..2cad6e77b 100644
--- a/api/src/main/java/org/apache/unomi/api/rules/RuleStatistics.java
+++ b/api/src/main/java/org/apache/unomi/api/rules/RuleStatistics.java
@@ -29,7 +29,6 @@ public class RuleStatistics extends Item {
/**
* The RuleStatistics ITEM_TYPE.
- *
* @see Item for a discussion of ITEM_TYPE
*/
public static final String ITEM_TYPE = "rulestats";
@@ -43,9 +42,20 @@ public class RuleStatistics extends Item {
private long localActionsTime = 0;
private Date lastSyncDate;
+ /**
+ * Constructs a new RuleStatistics instance with default values.
+ * This constructor is used when initializing statistics objects without
+ * an associated item ID.
+ */
public RuleStatistics() {
}
+ /**
+ * Constructs a new RuleStatistics instance, associating it with
+ * the given rule item ID.
+ * @param itemId The unique identifier of the rule item to which
+ * these statistics belong.
+ */
public RuleStatistics(String itemId) {
super(itemId);
}
diff --git a/api/src/main/java/org/apache/unomi/api/security/EncryptionService.java b/api/src/main/java/org/apache/unomi/api/security/EncryptionService.java
index d77c8c1e6..5d23c84af 100644
--- a/api/src/main/java/org/apache/unomi/api/security/EncryptionService.java
+++ b/api/src/main/java/org/apache/unomi/api/security/EncryptionService.java
@@ -17,7 +17,8 @@
package org.apache.unomi.api.security;
/**
- * Service for handling encryption operations.
+ * Encrypts and decrypts sensitive tenant or configuration values.
+ * Implementations hide key management details from the rest of the API.
*/
public interface EncryptionService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/security/SecurityServiceConfiguration.java b/api/src/main/java/org/apache/unomi/api/security/SecurityServiceConfiguration.java
index f3ccc0d31..058b183fb 100644
--- a/api/src/main/java/org/apache/unomi/api/security/SecurityServiceConfiguration.java
+++ b/api/src/main/java/org/apache/unomi/api/security/SecurityServiceConfiguration.java
@@ -22,22 +22,85 @@ import java.util.Map;
import java.util.Set;
/**
- * Configuration for the Security Service
+ * Settings that control authentication, authorization, and API access.
+ * Loaded at startup to configure how the security layer validates users,
+ * roles, and tenant principals.
*/
public class SecurityServiceConfiguration {
- // Permission constants
+ /**
+ * Defines the permission key used when querying items, which is also
+ * utilized to validate the tenant ID scope for query operations.
+ */
public static final String PERMISSION_QUERY = "QUERY";
+ /**
+ * Defines the permission key required for performing aggregations on item
+ * data, and is used internally to validate the tenant ID scope during
+ * aggregation queries.
+ */
public static final String PERMISSION_AGGREGATE = "AGGREGATE";
+ /**
+ * Defines the permission key necessary for continuing or
+ * initiating a scroll query.
+ * This constant is used to validate the tenant ID when
+ * executing scroll operations.
+ */
public static final String PERMISSION_SCROLL_QUERY = "SCROLL_QUERY";
+ /**
+ * Defines the permission key required for saving new items. It is also used
+ * internally to ensure that the correct tenant ID is set
+ * during save operations.
+ */
public static final String PERMISSION_SAVE = "SAVE";
+ /**
+ * Defines the permission key necessary for updating existing items. This
+ * constant is utilized to validate the tenant ID scope when
+ * performing item updates.
+ */
public static final String PERMISSION_UPDATE = "UPDATE";
+ /**
+ * Defines the permission key required for deleting items. It is used both
+ * in defining default roles and internally to validate the tenant ID during
+ * deletion operations.
+ */
public static final String PERMISSION_DELETE = "DELETE";
+ /**
+ * Defines the permission key needed when removing multiple items
+ * using a query condition.
+ * This constant is used to validate the tenant ID scope for remove
+ * by query operations.
+ */
public static final String PERMISSION_REMOVE_BY_QUERY = "REMOVE_BY_QUERY";
+ /**
+ * Defines the permission key required for purging data. It is utilized both
+ * in defining default roles and internally to validate the tenant ID
+ * during purge operations.
+ */
public static final String PERMISSION_PURGE = "PURGE";
+ /**
+ * Defines the permission key required for performing system
+ * maintenance operations.
+ */
public static final String PERMISSION_SYSTEM_MAINTENANCE = "SYSTEM_MAINTENANCE";
+ /**
+ * Defines the permission key needed when profile data
+ * encryption is required.
+ */
public static final String PERMISSION_ENCRYPT_PROFILE_DATA = "ENCRYPT_PROFILE_DATA";
+ /**
+ * Defines the permission key needed when profile data decryption is
+ * required. This constant is used to validate the tenant ID scope
+ * for remove operations.
+ */
public static final String PERMISSION_DECRYPT_PROFILE_DATA = "DECRYPT_PROFILE_DATA";
+ /**
+ * Defines the permission key required for writing or modifying schemas.
+ * This constant is used to validate access during schema write operations.
+ */
public static final String PERMISSION_SCHEMA_WRITE = "SCHEMA_WRITE";
+ /**
+ * Defines the permission key required for deleting schemas. This constant
+ * is used to validate access during schema delete operations.
+ */
public static final String PERMISSION_SCHEMA_DELETE = "SCHEMA_DELETE";
private Map<String, String[]> permissionRoles;
@@ -45,6 +108,11 @@ public class SecurityServiceConfiguration {
private Set<String> systemRoles = new HashSet<>();
private boolean enableEncryption = false;
+ /**
+ * Constructs a default security service configuration, initializing system
+ * roles and mapping permissions for standard operations like query, save,
+ * update, etc., with default roles.
+ */
public SecurityServiceConfiguration() {
// Initialize default system roles
systemRoles.add(UnomiRoles.ADMINISTRATOR);
@@ -68,18 +136,42 @@ public class SecurityServiceConfiguration {
defaultRole = UnomiRoles.USER;
}
+ /**
+ * Retrieves the map containing defined permission keys and the array of
+ * roles authorized to use them.
+ * The returned map is a direct reference to the internal configuration.
+ * @return A {@link Map} where keys are permission strings and values are
+ * arrays of required role names.
+ */
public Map<String, String[]> getPermissionRoles() {
return permissionRoles;
}
+ /**
+ * Sets the complete mapping of permissions to roles for the security
+ * service. This allows external configuration of which roles can perform
+ * specific operations.
+ * @param permissionRoles The map containing all permission keys and their
+ * associated authorized roles.
+ */
public void setPermissionRoles(Map<String, String[]> permissionRoles) {
this.permissionRoles = permissionRoles;
}
+ /**
+ * Retrieves the default role assigned to users or
+ * entities within the system.
+ * @return The configured default role string.
+ */
public String getDefaultRole() {
return defaultRole;
}
+ /**
+ * Sets the default role that should be applied when a user
+ * or entity is created.
+ * @param defaultRole the role to set as the default for new entities.
+ */
public void setDefaultRole(String defaultRole) {
this.defaultRole = defaultRole;
}
@@ -93,26 +185,59 @@ public class SecurityServiceConfiguration {
return permissionRoles.getOrDefault(permission, new String[]{defaultRole});
}
+ /**
+ * Gets the immutable set of system roles recognized by the security
+ * service, such as administrative or core platform roles.
+ * @return A {@link Set} of strings representing the defined system roles.
+ */
public Set<String> getSystemRoles() {
return systemRoles;
}
+ /**
+ * Sets all system roles that the security service should
+ * recognize and manage.
+ * @param systemRoles a set containing all system role names.
+ */
public void setSystemRoles(Set<String> systemRoles) {
this.systemRoles = systemRoles;
}
+ /**
+ * Adds a single specified role name to the collection of
+ * recognized system roles.
+ * This allows dynamic configuration of core platform roles.
+ * @param role the role string to add to the system roles list.
+ */
public void addSystemRole(String role) {
systemRoles.add(role);
}
+ /**
+ * Removes a specified role name from the set of recognized system roles.
+ * This should be used when a system role is deprecated or removed.
+ * @param role the role string to remove from the system roles list.
+ */
public void removeSystemRole(String role) {
systemRoles.remove(role);
}
+ /**
+ * Checks if profile data encryption has been enabled for
+ * the security service.
+ * @return {@code true} if encryption is active, {@code false} otherwise.
+ */
public boolean isEnableEncryption() {
return enableEncryption;
}
+ /**
+ * Sets whether sensitive profile data should be encrypted when stored and
+ * retrieved by the security service. This controls the use of
+ * encryption mechanisms.
+ * @param enableEncryption {@code true} to enable encryption,
+ * {@code false} otherwise.
+ */
public void setEnableEncryption(boolean enableEncryption) {
this.enableEncryption = enableEncryption;
}
diff --git a/api/src/main/java/org/apache/unomi/api/segments/DependentMetadata.java b/api/src/main/java/org/apache/unomi/api/segments/DependentMetadata.java
index 1830c1ee5..0eec441e4 100644
--- a/api/src/main/java/org/apache/unomi/api/segments/DependentMetadata.java
+++ b/api/src/main/java/org/apache/unomi/api/segments/DependentMetadata.java
@@ -22,29 +22,56 @@ import org.apache.unomi.api.Metadata;
import java.io.Serializable;
import java.util.List;
+/**
+ * Holds segment and scoring definitions that depend on each other.
+ * Used when exporting or editing related segment/scoring metadata as one
+ * unit in the segmentation UI.
+ */
public class DependentMetadata implements Serializable {
private List<Metadata> segments;
private List<Metadata> scorings;
+ /**
+ * Constructs a {@link DependentMetadata} instance with specified
+ * segment and scoring lists.
+ * @param segments the list of metadata defining required segments.
+ * @param scorings the list of metadata defining associated scores.
+ */
public DependentMetadata(List<Metadata> segments, List<Metadata> scorings) {
this.segments = segments;
this.scorings = scorings;
}
+ /**
+ * Retrieves the list of metadata representing the dependent segments.
+ * @return a {@link List<Metadata>} containing the segment definitions.
+ */
public List<Metadata> getSegments() {
return segments;
}
+ /**
+ * Sets the list of metadata defining the required segments for this object.
+ * @param segments the new list of segment metadata.
+ */
public void setSegments(List<Metadata> segments) {
this.segments = segments;
}
+ /**
+ * Retrieves the list of metadata representing the dependent scorings.
+ * @return a {@link List<Metadata>} containing the scoring definitions.
+ */
public List<Metadata> getScorings() {
return scorings;
}
+ /**
+ * Sets the list of metadata defining the associated scores for this object.
+ * @param scorings the new list of score metadata.
+ */
public void setScorings(List<Metadata> scorings) {
this.scorings = scorings;
}
diff --git a/api/src/main/java/org/apache/unomi/api/segments/ScoringElement.java b/api/src/main/java/org/apache/unomi/api/segments/ScoringElement.java
index ab79d132a..801132c57 100644
--- a/api/src/main/java/org/apache/unomi/api/segments/ScoringElement.java
+++ b/api/src/main/java/org/apache/unomi/api/segments/ScoringElement.java
@@ -30,7 +30,9 @@ import static org.apache.unomi.api.utils.YamlUtils.circularRef;
import static org.apache.unomi.api.utils.YamlUtils.toYamlValue;
/**
- * A scoring dimension along profiles can be evaluated and associated value to be assigned.
+ * One dimension of a {@link org.apache.unomi.api.segments.Scoring} model.
+ * Assigns a numeric value along an axis (for example engagement) when a
+ * profile matches the element's condition.
*/
public class ScoringElement implements Serializable, YamlConvertible {
private Condition condition;
diff --git a/api/src/main/java/org/apache/unomi/api/segments/SegmentsAndScores.java b/api/src/main/java/org/apache/unomi/api/segments/SegmentsAndScores.java
index f9fafaf3a..da8fe4dec 100644
--- a/api/src/main/java/org/apache/unomi/api/segments/SegmentsAndScores.java
+++ b/api/src/main/java/org/apache/unomi/api/segments/SegmentsAndScores.java
@@ -24,7 +24,9 @@ import java.util.Map;
import java.util.Set;
/**
- * A combination of {@link Segment} and scores (usually associated with a {@link Profile}).
+ * Snapshot of segment memberships and scoring values for a profile.
+ * Returned when clients need both which segments apply and the current
+ * score totals in one structure.
*/
public class SegmentsAndScores implements Serializable {
private Set<String> segments;
diff --git a/api/src/main/java/org/apache/unomi/api/services/ClusterService.java b/api/src/main/java/org/apache/unomi/api/services/ClusterService.java
index f100be286..1b507959c 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ClusterService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ClusterService.java
@@ -23,8 +23,9 @@ import java.util.Date;
import java.util.List;
/**
- * A service to access information about the context server's cluster.
- *
+ * Access point for cluster topology and node health.
+ * Returns {@link ClusterNode} records and coordinates cluster-wide
+ * operations such as viewing which nodes store data.
*/
public interface ClusterService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/ConditionValidationService.java b/api/src/main/java/org/apache/unomi/api/services/ConditionValidationService.java
index 2f77c95a8..5757b3133 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ConditionValidationService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ConditionValidationService.java
@@ -38,7 +38,6 @@ public interface ConditionValidationService {
* <p>
* Skips validation for parameters that contain references ({@code parameter::}) or script expressions
* ({@code script::}). Only literal parameter values are validated.
- *
* @param condition the condition to validate
* @return a list of validation errors, empty when the condition is valid
*/
@@ -58,7 +57,6 @@ public interface ConditionValidationService {
/**
* Instantiates a validation error for a single parameter.
- *
* @param parameterName the parameter that caused the error
* @param message the error description
* @param type the error type
@@ -69,7 +67,6 @@ public interface ConditionValidationService {
/**
* Instantiates a validation error with full condition context and optional parent error.
- *
* @param parameterName the parameter that caused the error
* @param message the error description
* @param type the error type
@@ -92,7 +89,6 @@ public interface ConditionValidationService {
/**
* Retrieves the name of the parameter that caused the error.
- *
* @return the parameter name, or {@code null} if not applicable
*/
public String getParameterName() {
@@ -101,7 +97,6 @@ public interface ConditionValidationService {
/**
* Retrieves the error description message.
- *
* @return the error message
*/
public String getMessage() {
@@ -110,7 +105,6 @@ public interface ConditionValidationService {
/**
* Retrieves the type of validation error.
- *
* @return the error type
*/
public ValidationErrorType getType() {
@@ -119,7 +113,6 @@ public interface ConditionValidationService {
/**
* Retrieves the identifier of the condition associated with this error.
- *
* @return the condition identifier, or {@code null} if not applicable
*/
public String getConditionId() {
@@ -128,7 +121,6 @@ public interface ConditionValidationService {
/**
* Retrieves the identifier of the condition type associated with this error.
- *
* @return the condition type identifier, or {@code null} if not applicable
*/
public String getConditionTypeId() {
@@ -137,6 +129,7 @@ public interface ConditionValidationService {
/**
* @deprecated Use {@link #getConditionTypeId()} instead.
+ * @return the condition type identifier (same as {@link #getConditionTypeId()})
*/
@Deprecated
public String getConditionTypeName() {
@@ -145,7 +138,6 @@ public interface ConditionValidationService {
/**
* Retrieves a copy of the additional context map for this error.
- *
* @return the context map
*/
public Map<String, Object> getContext() {
@@ -154,7 +146,6 @@ public interface ConditionValidationService {
/**
* Retrieves the parent error that caused this error, if any.
- *
* @return the parent error, or {@code null} if none
*/
public ValidationError getParentError() {
@@ -163,7 +154,6 @@ public interface ConditionValidationService {
/**
* Retrieves a detailed error message including condition, parameter, context, and parent error information.
- *
* @return the detailed error message
*/
public String getDetailedMessage() {
@@ -231,13 +221,20 @@ public interface ConditionValidationService {
private final String description;
+ /**
+ * Constructs an error type, setting its descriptive label.
+ * This initializes the {@code ValidationErrorType} constant with a
+ * specific human-readable description used to identify
+ * validation failures.
+ * @param description the descriptive text associated
+ * with this error type.
+ */
ValidationErrorType(String description) {
this.description = description;
}
/**
* Retrieves the human-readable description of this error type.
- *
* @return the error type description
*/
public String getDescription() {
diff --git a/api/src/main/java/org/apache/unomi/api/services/DefinitionsService.java b/api/src/main/java/org/apache/unomi/api/services/DefinitionsService.java
index 03da8090b..96e00a065 100644
--- a/api/src/main/java/org/apache/unomi/api/services/DefinitionsService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/DefinitionsService.java
@@ -31,7 +31,9 @@ import java.util.Map;
import java.util.Set;
/**
- * A service to retrieve definition information about core context server entities such as conditions, actions and values.
+ * Registry of built-in and plugin condition, action, and value type definitions.
+ * Used when loading rules from JSON, validating conditions, and resolving
+ * type metadata in the administration UI.
*/
public interface DefinitionsService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java b/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java
index 00bccb07e..8a5a4d46a 100644
--- a/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java
@@ -20,7 +20,9 @@ package org.apache.unomi.api.services;
import org.apache.unomi.api.Event;
/**
- * A service that gets notified (via {@link #onEvent(Event)}) whenever an event it can handle as decided by {@link #canHandle(Event)} occurs in the context server.
+ * Callback invoked for each {@link Event} the listener chooses to handle.
+ * Plugins implement this interface to react to events in real time alongside
+ * the rules engine.
*/
public interface EventListenerService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/EventService.java b/api/src/main/java/org/apache/unomi/api/services/EventService.java
index d68a2c703..f251c1961 100644
--- a/api/src/main/java/org/apache/unomi/api/services/EventService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/EventService.java
@@ -29,7 +29,9 @@ import java.util.List;
import java.util.Set;
/**
- * A service to publish events, notably issued from user interactions with tracked entities, in the context server.
+ * Publishes and retrieves {@link Event}s in the context server.
+ * Client integrations send visitor actions here; rules and listeners
+ * consume the same event stream.
*/
public interface EventService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/ExecutionContextManager.java b/api/src/main/java/org/apache/unomi/api/services/ExecutionContextManager.java
index da1ab18a0..a163edd4d 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ExecutionContextManager.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ExecutionContextManager.java
@@ -21,7 +21,8 @@ import org.apache.unomi.api.ExecutionContext;
import java.util.function.Supplier;
/**
- * Service interface for managing execution contexts in Unomi.
+ * Creates and binds {@link ExecutionContext} instances to the current thread.
+ * Ensures service calls run with the correct tenant and security credentials.
*/
public interface ExecutionContextManager {
diff --git a/api/src/main/java/org/apache/unomi/api/services/GoalsService.java b/api/src/main/java/org/apache/unomi/api/services/GoalsService.java
index 08e384e36..c04c3a06b 100644
--- a/api/src/main/java/org/apache/unomi/api/services/GoalsService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/GoalsService.java
@@ -31,7 +31,9 @@ import org.apache.unomi.api.rules.Rule;
import java.util.Set;
/**
- * A service to interact with {@link Goal}s and {@link Campaign}s.
+ * CRUD and reporting API for {@link org.apache.unomi.api.goals.Goal}s and
+ * {@link Campaign}s. Manages goal definitions, campaign lifecycle, and
+ * related statistics.
*/
public interface GoalsService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/services/InvalidObjectInfo.java b/api/src/main/java/org/apache/unomi/api/services/InvalidObjectInfo.java
index 7307fb4bd..aa443af7b 100644
--- a/api/src/main/java/org/apache/unomi/api/services/InvalidObjectInfo.java
+++ b/api/src/main/java/org/apache/unomi/api/services/InvalidObjectInfo.java
@@ -23,7 +23,9 @@ import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
/**
- * Information about an invalid object, including detailed reasons for invalidation.
+ * Diagnostic record for a configuration item that failed validation.
+ * Lists missing condition or action types and the contexts where the
+ * invalid object was seen so operators can fix definitions.
*/
public class InvalidObjectInfo {
private final String objectType;
@@ -36,10 +38,35 @@ public class InvalidObjectInfo {
private final Set<String> missingActionTypeIds;
private final Set<String> contextNames;
+ /**
+ * Constructs an {@code InvalidObjectInfo} object using only the basic
+ * identifying information.
+ * This constructor delegates to the full constructor, initializing missing
+ * lists and context names as null or empty.
+ * @param objectType The type name of the invalid object. Must not be null.
+ * @param objectId The unique ID of the invalid object. Must not be null.
+ * @param reason A detailed explanation for why the object
+ * is considered invalid.
+ */
public InvalidObjectInfo(String objectType, String objectId, String reason) {
this(objectType, objectId, reason, null, null, null);
}
+ /**
+ * Constructs an {@code InvalidObjectInfo} object with full details,
+ * including initial tracking information.
+ * This initializes timestamps and encounter counts upon creation.
+ * @param objectType The type name of the invalid object. Must not be null.
+ * @param objectId The unique ID of the invalid object. Must not be null.
+ * @param reason A detailed explanation for why the object
+ * is considered invalid.
+ * @param missingConditionTypeIds Initial list of condition types that were
+ * missing during validation.
+ * @param missingActionTypeIds Initial list of action types that were
+ * missing during validation.
+ * @param contextName The specific context where this initial encounter
+ * occurred. Can be null.
+ */
public InvalidObjectInfo(String objectType, String objectId, String reason,
List<String> missingConditionTypeIds,
List<String> missingActionTypeIds,
@@ -60,38 +87,82 @@ public class InvalidObjectInfo {
}
}
+ /**
+ * Retrieves the type name associated with this invalid object record.
+ * @return The {@code String} representing the object's type name.
+ */
public String getObjectType() {
return objectType;
}
+ /**
+ * Retrieves the unique ID of the invalid object record.
+ * @return The {@code String} representing the object's ID.
+ */
public String getObjectId() {
return objectId;
}
+ /**
+ * Retrieves the reason why this object was flagged as invalid.
+ * @return The detailed explanation for the invalidation, or {@code null}
+ * if none is provided.
+ */
public String getReason() {
return reason;
}
+ /**
+ * Gets the timestamp when this object record was first observed as invalid.
+ * @return The initial {@code long} timestamp (milliseconds since epoch).
+ */
public long getFirstSeenTimestamp() {
return firstSeenTimestamp;
}
+ /**
+ * Gets the most recent timestamp when this object record was
+ * observed as invalid.
+ * This value is updated whenever an encounter occurs.
+ * @return The latest {@code long} timestamp (milliseconds since epoch).
+ */
public long getLastSeenTimestamp() {
return lastSeenTimestamp.get();
}
+ /**
+ * Returns the total number of times this object has been
+ * encountered as invalid.
+ * @return An integer count representing the cumulative encounters.
+ */
public int getEncounterCount() {
return encounterCount.get();
}
+ /**
+ * Retrieves an unmodifiable list of condition type IDs that were found to
+ * be missing or unresolved for this object instance.
+ * @return A {@link java.util.List} containing the
+ * missing condition type IDs.
+ */
public List<String> getMissingConditionTypeIds() {
return Collections.unmodifiableList(new ArrayList<>(missingConditionTypeIds));
}
+ /**
+ * Retrieves an unmodifiable list of action type IDs that were found to be
+ * missing or unresolved for this object instance.
+ * @return A {@link java.util.List} containing the missing action type IDs.
+ */
public List<String> getMissingActionTypeIds() {
return Collections.unmodifiableList(new ArrayList<>(missingActionTypeIds));
}
+ /**
+ * Returns an unmodifiable set of context names in which this invalid
+ * object was encountered.
+ * @return A {@link java.util.Set} containing all recorded context names.
+ */
public Set<String> getContextNames() {
return Collections.unmodifiableSet(contextNames);
}
@@ -101,7 +172,6 @@ public class InvalidObjectInfo {
* Thread-safe: backed by CopyOnWriteArrayList/CopyOnWriteArraySet, so reads via
* {@code getMissingConditionTypeIds()}, {@code getMissingActionTypeIds()}, and
* {@code getContextNames()} are safe during concurrent writes.
- *
* @param missingConditionTypeIds additional missing condition type IDs found in this encounter
* @param missingActionTypeIds additional missing action type IDs found in this encounter
* @param contextName context where this encounter occurred
diff --git a/api/src/main/java/org/apache/unomi/api/services/PersonalizationService.java b/api/src/main/java/org/apache/unomi/api/services/PersonalizationService.java
index f4dea3d9d..4c0c7b9d9 100644
--- a/api/src/main/java/org/apache/unomi/api/services/PersonalizationService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/PersonalizationService.java
@@ -26,13 +26,14 @@ import java.util.List;
import java.util.Map;
/**
- * A service to fulfill personalization request.
+ * Resolves which content variants to show a visitor.
+ * Evaluates personalization requests against profiles, sessions, and
+ * segments, returning {@link PersonalizationResult} with matching content ids.
*/
public interface PersonalizationService {
/**
* Check if an item is visible for the specified profile and session
- *
* @param profile The profile
* @param session The session
* @param personalizedContent Personalized content, containing a list of filters
@@ -42,7 +43,6 @@ public interface PersonalizationService {
/**
* Get the best match among a list of items, for the specified profile and session
- *
* @param profile The profile
* @param session The session
* @param personalizationRequest Personalization request, containing the list of variants and the required strategy
@@ -52,7 +52,6 @@ public interface PersonalizationService {
/**
* Get a personalized list, filtered and sorted, based on the profile and session
- *
* @param profile The profile
* @param session The session
* @param personalizationRequest Personalization request, containing the list of variants and the required strategy
@@ -69,34 +68,70 @@ public interface PersonalizationService {
private Map<String, Object> strategyOptions;
private List<PersonalizedContent> contents;
+ /**
+ * Gets the unique identifier of this personalization request.
+ * @return The ID string.
+ */
public String getId() {
return id;
}
+ /**
+ * Sets the unique identifier for this personalization request.
+ * @param id The unique ID to set.
+ */
public void setId(String id) {
this.id = id;
}
+ /**
+ * Retrieves the name of the personalization strategy to be used.
+ * @return The configured strategy name string.
+ */
public String getStrategy() {
return strategy;
}
+ /**
+ * Sets the personalization strategy that should process this request.
+ * @param strategy The name of the strategy (e.g., "alwaysSet").
+ */
public void setStrategy(String strategy) {
this.strategy = strategy;
}
+ /**
+ * Gets the list of personalized content items
+ * associated with this request.
+ * @return A list of {@link PersonalizedContent} objects.
+ */
public List<PersonalizedContent> getContents() {
return contents;
}
+ /**
+ * Sets the collection of personalized content that should be processed.
+ * @param contents The list of {@link PersonalizedContent} to set.
+ */
public void setContents(List<PersonalizedContent> contents) {
this.contents = contents;
}
+ /**
+ * Retrieves optional configuration parameters specific to the
+ * personalization strategy.
+ * @return A map containing strategy-specific options, or
+ * null if none are set.
+ */
public Map<String, Object> getStrategyOptions() {
return strategyOptions;
}
+ /**
+ * Sets the map of optional configuration parameters for the
+ * personalization process.
+ * @param strategyOptions The map of options to apply.
+ */
public void setStrategyOptions(Map<String, Object> strategyOptions) {
this.strategyOptions = strategyOptions;
}
@@ -112,7 +147,6 @@ public interface PersonalizationService {
/**
* Retrieves the filter identifier associated with this content filtering definition.
- *
* @return the filter identifier associated with this content filtering definition
*/
public String getId() {
@@ -121,7 +155,6 @@ public interface PersonalizationService {
/**
* Sets the filter identifier associated with this content filtering definition.
- *
* @param id the filter identifier associated with this content filtering definition
*/
public void setId(String id) {
@@ -130,7 +163,6 @@ public interface PersonalizationService {
/**
* Sets the filter identifier associated with this content filtering definition.
- *
* @param filterid the filter identifier associated with this content filtering definition
* @deprecated As of version 1.3.0-incubating, please use {@link #setId(String)} instead
*/
@@ -141,7 +173,6 @@ public interface PersonalizationService {
/**
* Retrieves the filters.
- *
* @return the filters
*/
public List<Filter> getFilters() {
@@ -150,17 +181,24 @@ public interface PersonalizationService {
/**
* Sets the filters.
- *
* @param filters the filters
*/
public void setFilters(List<Filter> filters) {
this.filters = filters;
}
+ /**
+ * Retrieves the properties associated with this content definition.
+ * @return The map of properties stored in this object.
+ */
public Map<String, Object> getProperties() {
return properties;
}
+ /**
+ * Sets the properties associated with this content definition.
+ * @param properties The map containing the properties to set.
+ */
public void setProperties(Map<String, Object> properties) {
this.properties = properties;
}
@@ -176,7 +214,6 @@ public interface PersonalizationService {
/**
* Retrieves the list of targets this filter applies on.
- *
* @return the applies on
*/
public List<Target> getAppliesOn() {
@@ -185,7 +222,6 @@ public interface PersonalizationService {
/**
* Specifies which targets this filter applies on.
- *
* @param appliesOn the list of {@link Target} this filter should be applied on
*/
public void setAppliesOn(List<Target> appliesOn) {
@@ -194,7 +230,6 @@ public interface PersonalizationService {
/**
* Retrieves the condition associated with this filter.
- *
* @return the condition associated with this filter
*/
public Condition getCondition() {
@@ -203,17 +238,27 @@ public interface PersonalizationService {
/**
* Sets the condition associated with this filter.
- *
* @param condition the condition associated with this filter
*/
public void setCondition(Condition condition) {
this.condition = condition;
}
+ /**
+ * Retrieves the map of properties associated with this filter.
+ * This method returns a reference to the internal
+ * {@code properties} map.
+ * @return the properties map
+ */
public Map<String, Object> getProperties() {
return properties;
}
+ /**
+ * Sets the properties associated with this filter.
+ * The provided map replaces any existing properties.
+ * @param properties the map of properties to set
+ */
public void setProperties(Map<String, Object> properties) {
this.properties = properties;
}
@@ -228,7 +273,6 @@ public interface PersonalizationService {
/**
* Retrieves the target.
- *
* @return the target
*/
public String getTarget() {
@@ -237,7 +281,6 @@ public interface PersonalizationService {
/**
* Sets the target.
- *
* @param target the target
*/
public void setTarget(String target) {
@@ -246,7 +289,6 @@ public interface PersonalizationService {
/**
* Retrieves the values.
- *
* @return the values
*/
public List<String> getValues() {
@@ -255,7 +297,6 @@ public interface PersonalizationService {
/**
* Sets the values.
- *
* @param values the values
*/
public void setValues(List<String> values) {
diff --git a/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java b/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java
index 3f7d5554b..fb3cf98a6 100644
--- a/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java
@@ -23,7 +23,8 @@ import org.apache.unomi.api.ServerInfo;
import java.util.List;
/**
- * This service regroups all privacy-related operations
+ * Entry point for consent, anonymization, and privacy-related operations.
+ * Wraps profile updates required for GDPR-style requests and consent tracking.
*/
public interface PrivacyService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/ProfileService.java b/api/src/main/java/org/apache/unomi/api/services/ProfileService.java
index 78ecb1ffb..b2493530f 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ProfileService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ProfileService.java
@@ -25,22 +25,26 @@ import java.net.URL;
import java.util.*;
/**
- * A service to access and operate on {@link Profile}s, {@link Session}s and {@link Persona}s.
+ * Primary API for {@link Profile}s, {@link Session}s, and {@link Persona}s.
+ * Loads and saves visitor data, merges profiles, manages sessions, and
+ * supports persona-based testing workflows.
*/
public interface ProfileService {
+ /**
+ * The system tag name used to identify property types that store
+ * personal identifiers.
+ */
String PERSONAL_IDENTIFIER_TAG_NAME = "personalIdentifierProperties";
/**
* Retrieves the number of unique profiles.
- *
* @return the number of unique profiles.
*/
long getAllProfilesCount();
/**
* Retrieves profiles or personas matching the specified query.
- *
* @param <T> the specific sub-type of {@link Profile} to retrieve
* @param query a {@link Query} specifying which elements to retrieve
* @param clazz the class of elements to retrieve
@@ -50,7 +54,6 @@ public interface ProfileService {
/**
* Retrieves sessions matching the specified query.
- *
* @param query a {@link Query} specifying which elements to retrieve
* @return a {@link PartialList} of sessions matching the specified query
*/
@@ -58,7 +61,6 @@ public interface ProfileService {
/**
* Creates a String containing comma-separated values (CSV) formatted version of profiles matching the specified query.
- *
* @param query the query specifying which profiles to export
* @return a CSV-formatted String version of the profiles matching the specified query
*/
@@ -67,10 +69,8 @@ public interface ProfileService {
/**
* Find profiles which have the specified property with the specified value, ordered according to the specified {@code sortBy} String and paged: only
* {@code size} of them are retrieved, starting with the {@code offset}-th one.
- *
* TODO: replace with version using a query instead of separate parameters
* TODO: remove as it's unused?
- *
* @param propertyName the name of the property we're interested in
* @param propertyValue the value of the property we want profiles to have
* @param offset zero or a positive integer specifying the position of the first profile in the total ordered collection of matching profiles
@@ -85,7 +85,6 @@ public interface ProfileService {
/**
* Merges the specified profiles into the provided so-called master profile, merging properties according to the {@link PropertyMergeStrategyType} specified on their {@link
* PropertyType}.
- *
* @param masterProfile the profile into which the specified profiles will be merged
* @param profilesToMerge the list of profiles to merge into the specified master profile
* @return the merged profile
@@ -94,7 +93,6 @@ public interface ProfileService {
/**
* Retrieves the profile identified by the specified identifier.
- *
* @param profileId the identifier of the profile to retrieve
* @return the profile identified by the specified identifier or {@code null} if no such profile exists
*/
@@ -102,7 +100,6 @@ public interface ProfileService {
/**
* Saves the specified profile in the context server.
- *
* @param profile the profile to be saved
* @return the newly saved profile
*/
@@ -110,7 +107,6 @@ public interface ProfileService {
/**
* Adds the alias to the profile.
- *
* @param profileID the identifier of the profile
* @param alias the alias which should be linked with of the profile
* @param clientID the identifier of the client
@@ -119,7 +115,6 @@ public interface ProfileService {
/**
* Removes the alias from the profile.
- *
* @param profileID the identifier of the profile
* @param alias the alias which should be unlinked from the profile
* @param clientID the identifier of the client
@@ -130,7 +125,6 @@ public interface ProfileService {
/**
* Find profile aliases which have the specified property with the specified value, ordered according to the specified {@code sortBy} String and paged: only
* {@code size} of them are retrieved, starting with the {@code offset}-th one.
- *
* @param profileId the identifier of the profile
* @param offset zero or a positive integer specifying the position of the first profile in the total ordered collection of matching profiles
* @param size a positive integer specifying how many matching profiles should be retrieved or {@code -1} if all of them should be retrieved
@@ -143,7 +137,6 @@ public interface ProfileService {
/**
* Merge the specified profile properties in an existing profile,or save new profile if it does not exist yet
- *
* @param profile the profile to be saved
* @return the newly saved or merged profile or null if the save or merge operation failed.
*/
@@ -151,7 +144,6 @@ public interface ProfileService {
/**
* Removes the profile (or persona if the {@code persona} parameter is set to {@code true}) identified by the specified identifier.
- *
* @param profileId the identifier of the profile or persona to delete
* @param persona {@code true} if the specified identifier is supposed to refer to a persona, {@code false} if it is supposed to refer to a profile
*/
@@ -160,9 +152,7 @@ public interface ProfileService {
/**
* Retrieves the sessions associated with the profile identified by the specified identifier that match the specified query (if specified), ordered according to the specified
* {@code sortBy} String and and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one.
- *
* TODO: use a Query object instead of distinct parameter
- *
* @param profileId the identifier of the profile we want to retrieve sessions from
* @param query a String of text used for fulltext filtering which sessions we are interested in or {@code null} (or an empty String) if we want to retrieve all sessions
* @param offset zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions
@@ -177,7 +167,6 @@ public interface ProfileService {
/**
* Retrieves the session identified by the specified identifier.
* @deprecated {@code dateHint} is not supported anymore, please use {@link #loadSession(String)}
- *
* @param sessionId the identifier of the session to be retrieved
* @param dateHint a Date helping in identifying where the item is located
* @return the session identified by the specified identifier
@@ -187,7 +176,6 @@ public interface ProfileService {
/**
* Retrieves the session identified by the specified identifier.
- *
* @param sessionId the identifier of the session to be retrieved
* @return the session identified by the specified identifier
*/
@@ -197,7 +185,6 @@ public interface ProfileService {
/**
* Saves the specified session.
- *
* @param session the session to be saved
* @return the newly saved session
*/
@@ -205,7 +192,6 @@ public interface ProfileService {
/**
* Retrieves sessions associated with the profile identified by the specified identifier.
- *
* @param profileId the profile id for which we want to retrieve the sessions
* @return a {@link PartialList} of the profile's sessions
*/
@@ -213,7 +199,6 @@ public interface ProfileService {
/**
* Removes all sessions of the specified profile
- *
* @param profileId identifier of the profile that we want to remove it's sessions
*/
void removeProfileSessions(String profileId);
@@ -222,14 +207,12 @@ public interface ProfileService {
* Deletes the session identified by the given identifier from persistence.
* Note: events belonging to this session are NOT removed; they remain in persistence
* with a dangling sessionId reference.
- *
* @param sessionIdentifier the unique identifier for the session
*/
void deleteSession(String sessionIdentifier);
/**
* Checks whether the specified profile and/or session satisfy the specified condition.
- *
* @param condition the condition we're testing against which might or might not have profile- or session-specific sub-conditions
* @param profile the profile we're testing
* @param session the session we're testing
@@ -239,14 +222,12 @@ public interface ProfileService {
/**
* Update all profiles in batch according to the specified {@link BatchUpdate}
- *
* @param update the batch update specification
*/
void batchProfilesUpdate(BatchUpdate update);
/**
* Retrieves the persona identified by the specified identifier.
- *
* @param personaId the identifier of the persona to retrieve
* @return the persona associated with the specified identifier or {@code null} if no such persona exists.
*/
@@ -254,7 +235,6 @@ public interface ProfileService {
/**
* Persists the specified {@link Persona} in the context server.
- *
* @param persona the persona to persist
* @return the newly persisted persona
*/
@@ -262,7 +242,6 @@ public interface ProfileService {
/**
* Retrieves the persona identified by the specified identifier and all its associated sessions
- *
* @param personaId the identifier of the persona to retrieve
* @return a {@link PersonaWithSessions} instance with the persona identified by the specified identifier and all its associated sessions
*/
@@ -270,7 +249,6 @@ public interface ProfileService {
/**
* Creates a persona with the specified identifier and automatically creates an associated session with it.
- *
* @param personaId the identifier to use for the new persona
* @return the newly created persona
*/
@@ -279,7 +257,6 @@ public interface ProfileService {
/**
* Retrieves the sessions associated with the persona identified by the specified identifier, ordered according to the specified {@code sortBy} String and and paged: only
* {@code size} of them are retrieved, starting with the {@code offset}-th one.
- *
* @param personaId the persona id
* @param offset zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions
* @param size a positive integer specifying how many matching sessions should be retrieved or {@code -1} if all of them should be retrieved
@@ -292,7 +269,6 @@ public interface ProfileService {
/**
* Save a persona with its sessions.
- *
* @param personaToSave the persona object containing all the persona information and sessions
* @return the persona with sessions
*/
@@ -301,9 +277,7 @@ public interface ProfileService {
/**
* Retrieves all the property types associated with the specified target.
- *
* TODO: move to a different class
- *
* @param target the target for which we want to retrieve the associated property types
* @return a collection of all the property types associated with the specified target
*/
@@ -311,19 +285,15 @@ public interface ProfileService {
/**
* Retrieves all known property types.
- *
* TODO: move to a different class
* TODO: use Map instead of HashMap
- *
* @return a Map associating targets as keys to related {@link PropertyType}s
*/
Map<String, Collection<PropertyType>> getTargetPropertyTypes();
/**
* Retrieves all property types with the specified tag
- *
* TODO: move to a different class
- *
* @param tag the tag name marking property types we want to retrieve
* @return a Set of the property types with the specified tag
*/
@@ -331,9 +301,7 @@ public interface ProfileService {
/**
* Retrieves all property types with the specified system tag
- *
* TODO: move to a different class
- *
* @param tag the system tag name marking property types we want to retrieve
* @return a Set of the property types with the specified system tag
*/
@@ -355,9 +323,7 @@ public interface ProfileService {
/**
* Retrieves the property type identified by the specified identifier.
- *
* TODO: move to a different class
- *
* @param id the identifier of the property type to retrieve
* @return the property type identified by the specified identifier or {@code null} if no such property type exists
*/
@@ -365,9 +331,7 @@ public interface ProfileService {
/**
* Persists the specified property type in the context server.
- *
* TODO: move to a different class
- *
* @param property the property type to persist
* @return {@code true} if the property type was properly created, {@code false} otherwise (for example, if the property type already existed
*/
@@ -375,7 +339,6 @@ public interface ProfileService {
/**
* This function will try to set the target on the property type if not set already, based on the file URL
- *
* @param predefinedPropertyTypeURL the URL to extract the target from if the target is not yet. By default it will
* use the 5's part after a "/" character
* @param propertyType the property type to register
@@ -384,9 +347,7 @@ public interface ProfileService {
/**
* Deletes the property type identified by the specified identifier.
- *
* TODO: move to a different class
- *
* @param propertyId the identifier of the property type to delete
* @return {@code true} if the property type was properly deleted, {@code false} otherwise
*/
@@ -394,9 +355,7 @@ public interface ProfileService {
/**
* Retrieves the existing property types for the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and with the specified tag.
- *
* TODO: move to a different class
- *
* @param tag the tag we're interested in
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return all property types defined for the specified item type and with the specified tag
@@ -406,9 +365,7 @@ public interface ProfileService {
/**
* Retrieves the existing property types for the specified type as defined by the Item subclass public
* field {@code ITEM_TYPE} and with the specified tag (system or regular)
- *
* TODO: move to a different class
- *
* @param tag the tag we're interested in
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @param systemTag whether the specified is a system tag or a regular one
@@ -429,7 +386,6 @@ public interface ProfileService {
* purgeProfiles(10, 0);
* example: Purge profile created since 30 days only:
* purgeProfiles(0, 30);
- *
* @param inactiveNumberOfDays will purge profiles with no visits since this number of days (0 or negative value, will have no effect)
* @param existsNumberOfDays will purge profiles created since this number of days (0 or negative value, will have no effect)
*/
diff --git a/api/src/main/java/org/apache/unomi/api/services/QueryService.java b/api/src/main/java/org/apache/unomi/api/services/QueryService.java
index c397fda75..657c8ab4e 100644
--- a/api/src/main/java/org/apache/unomi/api/services/QueryService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/QueryService.java
@@ -24,7 +24,8 @@ import org.apache.unomi.api.query.AggregateQuery;
import java.util.Map;
/**
- * A service to perform queries.
+ * Runs stored queries and aggregations against the persistence layer.
+ * Complements segment search with lower-level query and aggregate access.
*/
public interface QueryService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/RuleListenerService.java b/api/src/main/java/org/apache/unomi/api/services/RuleListenerService.java
index f65990403..e6555a2ed 100644
--- a/api/src/main/java/org/apache/unomi/api/services/RuleListenerService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/RuleListenerService.java
@@ -21,7 +21,9 @@ import org.apache.unomi.api.Event;
import org.apache.unomi.api.rules.Rule;
/**
- * A service that gets called when a rule's conditions are evaluated or when a rule's actions are executed.
+ * Observer notified when rules are evaluated or executed.
+ * Lets extensions audit rule firing or add diagnostics without changing
+ * core rule processing.
*/
public interface RuleListenerService {
@@ -29,8 +31,11 @@ public interface RuleListenerService {
* This enum indicates which type of already raised event we are dealing with
*/
enum AlreadyRaisedFor {
+ /** Rule was already raised for the session. */
SESSION,
+ /** Rule was already raised for the profile. */
PROFILE,
+ /** Rule was already raised for the event. */
EVENT
}
diff --git a/api/src/main/java/org/apache/unomi/api/services/RulesService.java b/api/src/main/java/org/apache/unomi/api/services/RulesService.java
index dd5a44786..b55e09115 100644
--- a/api/src/main/java/org/apache/unomi/api/services/RulesService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/RulesService.java
@@ -31,7 +31,9 @@ import java.util.Map;
import java.util.Set;
/**
- * A service to access and operate on {@link Rule}s.
+ * Loads, saves, and searches {@link org.apache.unomi.api.rules.Rule} definitions.
+ * Rules tie conditions to actions and drive most automated behavior when
+ * events arrive.
*/
public interface RulesService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/SchedulerService.java b/api/src/main/java/org/apache/unomi/api/services/SchedulerService.java
index 6868ebc65..fe97d3dfc 100644
--- a/api/src/main/java/org/apache/unomi/api/services/SchedulerService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/SchedulerService.java
@@ -280,6 +280,13 @@ public interface SchedulerService {
*/
Map<String, Long> getAllMetrics();
+ /**
+ * Gets a list of scheduled tasks matching the specified status.
+ * This method allows filtering all managed tasks (both persistent and
+ * in-memory) by their current operational state, such as RUNNING or FAILED.
+ * @param taskStatus the desired {@link ScheduledTask.TaskStatus} to filter by
+ * @return tasks that currently match the given status
+ */
List<ScheduledTask> findTasksByStatus(ScheduledTask.TaskStatus taskStatus);
/**
@@ -291,6 +298,7 @@ public interface SchedulerService {
/**
* Sets task parameters.
* @param parameters task-specific parameters
+ * @return this builder for method chaining
*/
TaskBuilder withParameters(Map<String, Object> parameters);
@@ -298,6 +306,7 @@ public interface SchedulerService {
* Sets initial execution delay.
* @param initialDelay delay before first execution
* @param timeUnit time unit for delay
+ * @return this builder for method chaining
*/
TaskBuilder withInitialDelay(long initialDelay, TimeUnit timeUnit);
@@ -305,54 +314,63 @@ public interface SchedulerService {
* Sets execution period.
* @param period time between executions
* @param timeUnit time unit for period
+ * @return this builder for method chaining
*/
TaskBuilder withPeriod(long period, TimeUnit timeUnit);
/**
* Uses fixed delay scheduling.
* Period is measured from completion of one execution to start of next.
+ * @return this builder for method chaining
*/
TaskBuilder withFixedDelay();
/**
* Uses fixed rate scheduling.
* Period is measured from start of one execution to start of next.
+ * @return this builder for method chaining
*/
TaskBuilder withFixedRate();
/**
* Makes this a one-shot task.
* Task will execute once and then be disabled.
+ * @return this builder for method chaining
*/
TaskBuilder asOneShot();
/**
* Disallows parallel execution.
* Task will use locking to ensure only one instance runs at a time.
+ * @return this builder for method chaining
*/
TaskBuilder disallowParallelExecution();
/**
* Sets the task executor.
* @param executor the executor to handle this task
+ * @return this builder for method chaining
*/
TaskBuilder withExecutor(TaskExecutor executor);
/**
* Sets a simple runnable as the executor.
* @param runnable the code to execute
+ * @return this builder for method chaining
*/
TaskBuilder withSimpleExecutor(Runnable runnable);
/**
* Makes this a non-persistent task.
* Task will only exist in memory on this node.
+ * @return this builder for method chaining
*/
TaskBuilder nonPersistent();
/**
* Runs the task on all nodes in the cluster rather than just executor nodes.
* This is helpful for distributed cache refreshes or local data maintenance.
+ * @return this builder for method chaining
*/
TaskBuilder runOnAllNodes();
@@ -381,6 +399,7 @@ public interface SchedulerService {
*
* @param maxRetries maximum number of retries (must be >= 0)
* @throws IllegalArgumentException if maxRetries is negative
+ * @return this builder for method chaining
*/
TaskBuilder withMaxRetries(int maxRetries);
@@ -397,6 +416,7 @@ public interface SchedulerService {
* @param delay delay duration (must be >= 0)
* @param unit time unit for delay
* @throws IllegalArgumentException if delay is negative
+ * @return this builder for method chaining
*/
TaskBuilder withRetryDelay(long delay, TimeUnit unit);
@@ -404,6 +424,7 @@ public interface SchedulerService {
* Sets the task dependencies.
* The task will not execute until all dependencies have completed.
* @param taskIds IDs of tasks this task depends on
+ * @return this builder for method chaining
*/
TaskBuilder withDependencies(String... taskIds);
diff --git a/api/src/main/java/org/apache/unomi/api/services/ScopeService.java b/api/src/main/java/org/apache/unomi/api/services/ScopeService.java
index 91980a407..d9c223697 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ScopeService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ScopeService.java
@@ -22,7 +22,9 @@ import org.apache.unomi.api.Scope;
import java.util.List;
/**
- * A service to create, update and delete scope.
+ * Manages {@link Scope} definitions.
+ * Creates, updates, and deletes scopes that partition data between sites
+ * or applications.
*/
public interface ScopeService {
@@ -51,6 +53,7 @@ public interface ScopeService {
/**
* Get a scope by its id
*
+ * @param id scope identifier
* @return Scope matching the id
*/
Scope getScope(String id);
diff --git a/api/src/main/java/org/apache/unomi/api/services/SegmentService.java b/api/src/main/java/org/apache/unomi/api/services/SegmentService.java
index 601cd5633..935dfa1ce 100644
--- a/api/src/main/java/org/apache/unomi/api/services/SegmentService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/SegmentService.java
@@ -31,7 +31,9 @@ import org.apache.unomi.api.segments.SegmentsAndScores;
import java.util.List;
/**
- * A service to access and operate on {@link Segment}s and {@link Scoring}s
+ * Manages {@link org.apache.unomi.api.segments.Segment}s and
+ * {@link org.apache.unomi.api.segments.Scoring} definitions.
+ * Also recalculates segment membership for profiles when definitions change.
*/
public interface SegmentService {
diff --git a/api/src/main/java/org/apache/unomi/api/services/TenantLifecycleListener.java b/api/src/main/java/org/apache/unomi/api/services/TenantLifecycleListener.java
index 5aab7ad78..d5653d9ab 100644
--- a/api/src/main/java/org/apache/unomi/api/services/TenantLifecycleListener.java
+++ b/api/src/main/java/org/apache/unomi/api/services/TenantLifecycleListener.java
@@ -17,7 +17,8 @@
package org.apache.unomi.api.services;
/**
- * Interface for services that need to be notified of tenant lifecycle events.
+ * Extension point notified when tenants are created, updated, or removed.
+ * Implementations run setup or teardown logic for multi-tenant deployments.
*/
public interface TenantLifecycleListener {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/services/TopicService.java b/api/src/main/java/org/apache/unomi/api/services/TopicService.java
index 6cb5e0b38..f8344ae39 100644
--- a/api/src/main/java/org/apache/unomi/api/services/TopicService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/TopicService.java
@@ -20,11 +20,15 @@ import org.apache.unomi.api.PartialList;
import org.apache.unomi.api.Topic;
import org.apache.unomi.api.query.Query;
+/**
+ * Persistence API for {@link Topic} items.
+ * Supports load, save, search, and delete of topics used to categorize
+ * entities across the context server.
+ */
public interface TopicService {
/**
* Retrieves the topic identified by the specified identifier.
- *
* @param topicId the identifier of the topic to retrieve
* @return the topic identified by the specified identifier or {@code null} if no such topic exists
*/
@@ -32,7 +36,6 @@ public interface TopicService {
/**
* Saves the specified topic in the context server.
- *
* @param topic the topic to be saved
* @return the newly saved topic if the creation or update was successful, {@code null} otherwise
*/
@@ -40,7 +43,6 @@ public interface TopicService {
/**
* Retrieves topic matching the specified query.
- *
* @param query a {@link Query} specifying which elements to retrieve
* @return a {@link PartialList} of {@link Topic} metadata
*/
@@ -48,7 +50,6 @@ public interface TopicService {
/**
* Removes the topic identified by the specified identifier.
- *
* @param topicId the identifier of the profile or persona to delete
* @return {@code true} if the deletion was successful, {@code false} otherwise
*/
diff --git a/api/src/main/java/org/apache/unomi/api/services/UserListService.java b/api/src/main/java/org/apache/unomi/api/services/UserListService.java
index 04d109ab7..7612bde0a 100644
--- a/api/src/main/java/org/apache/unomi/api/services/UserListService.java
+++ b/api/src/main/java/org/apache/unomi/api/services/UserListService.java
@@ -24,7 +24,8 @@ import org.apache.unomi.api.lists.UserList;
import java.util.List;
/**
- * Created by amidani on 24/03/2017.
+ * CRUD and membership operations for {@link UserList} instances.
+ * Maintains static audience lists referenced by campaigns and exports.
*/
public interface UserListService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/services/ValueTypeValidator.java b/api/src/main/java/org/apache/unomi/api/services/ValueTypeValidator.java
index ec6a3e255..37c92930a 100644
--- a/api/src/main/java/org/apache/unomi/api/services/ValueTypeValidator.java
+++ b/api/src/main/java/org/apache/unomi/api/services/ValueTypeValidator.java
@@ -17,7 +17,8 @@
package org.apache.unomi.api.services;
/**
- * A service interface for validating values against specific types.
+ * Validates a value against a {@link org.apache.unomi.api.ValueType} definition.
+ * Called when saving properties or condition parameters to enforce schema rules.
*/
public interface ValueTypeValidator {
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/ApiKeyCreationResult.java b/api/src/main/java/org/apache/unomi/api/tenants/ApiKeyCreationResult.java
index 69d48e0af..0419bbe59 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/ApiKeyCreationResult.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/ApiKeyCreationResult.java
@@ -28,9 +28,22 @@ public class ApiKeyCreationResult {
private ApiKey apiKey;
private String plainTextKey;
+ /**
+ * Constructs an empty {@link ApiKeyCreationResult}.
+ * This result object must be populated manually with the created API key
+ * metadata and the plaintext key value.
+ */
public ApiKeyCreationResult() {
}
+ /**
+ * Creates a result containing both the persisted {@link ApiKey} metadata
+ * and the plaintext key value.
+ * The plaintext key is only available at creation time, as
+ * it is not persisted.
+ * @param apiKey the API key metadata that was successfully persisted.
+ * @param plainTextKey the one-time plaintext key value.
+ */
public ApiKeyCreationResult(ApiKey apiKey, String plainTextKey) {
this.apiKey = apiKey;
this.plainTextKey = plainTextKey;
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/AuditService.java b/api/src/main/java/org/apache/unomi/api/tenants/AuditService.java
index 6fb6460af..758777d8b 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/AuditService.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/AuditService.java
@@ -22,7 +22,8 @@ import java.util.Date;
import java.util.List;
/**
- * Combined service interface for both item and tenant auditing operations.
+ * Combined facade for item-level and tenant-level audit trails.
+ * Delegates to {@link ItemAuditService} and {@link TenantAuditService}.
*/
public interface AuditService extends ItemAuditService, TenantAuditService {
/**
@@ -85,6 +86,12 @@ public interface AuditService extends ItemAuditService, TenantAuditService {
*/
Date getLastSyncDate(String tenantId, String sourceInstanceId);
+ /**
+ * Updates last-modified audit fields on an item.
+ *
+ * @param item the item to update
+ * @param userId the user performing the modification
+ */
default void updateModificationMetadata(Item item, String userId) {
item.setLastModifiedBy(userId);
item.setLastModificationDate(new Date());
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/ItemAuditService.java b/api/src/main/java/org/apache/unomi/api/tenants/ItemAuditService.java
index 77b5bb2c2..bccaf5a13 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/ItemAuditService.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/ItemAuditService.java
@@ -22,7 +22,8 @@ import java.util.Date;
import java.util.List;
/**
- * A service to track and audit changes to items.
+ * Records create, update, and delete operations on configuration items.
+ * Provides an audit trail for who changed segments, rules, and similar entities.
*/
public interface ItemAuditService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantAuditService.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantAuditService.java
index 261a36e23..ab3105a0f 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantAuditService.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantAuditService.java
@@ -17,7 +17,8 @@
package org.apache.unomi.api.tenants;
/**
- * A service to audit tenant-related operations.
+ * Records administrative actions performed in a tenant context.
+ * Complements item audit with tenant-scoped security and operations history.
*/
public interface TenantAuditService {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantBackupMetadata.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantBackupMetadata.java
index 4cae6cfba..fe76b6e57 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantBackupMetadata.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantBackupMetadata.java
@@ -16,22 +16,48 @@
*/
package org.apache.unomi.api.tenants;
+/**
+ * Represents metadata used to track the state or existence of a backup
+ * for a specific tenant.
+ * This class encapsulates essential information linking a backup record
+ * to its owner and time.
+ * The {@link TenantBackupMetadata} holds two primary pieces of data: the unique
+ * identifier of the tenant, stored in {@code tenantId}, and a timestamp
+ * indicating when this metadata was generated or pertains to, stored
+ * in {@code timestamp}.
+ */
public class TenantBackupMetadata {
private String tenantId;
private long timestamp;
+ /**
+ * Retrieves the tenant ID associated with this metadata object.
+ * @return The stored {@link String} tenant ID.
+ */
public String getTenantId() {
return tenantId;
}
+ /**
+ * Sets the tenant ID for this metadata object.
+ * @param tenantId The new {@link String} tenant ID to set.
+ */
public void setTenantId(String tenantId) {
this.tenantId = tenantId;
}
+ /**
+ * Retrieves the timestamp associated with this metadata object.
+ * @return The stored {@link Long} timestamp.
+ */
public long getTimestamp() {
return timestamp;
}
+ /**
+ * Sets the timestamp for this metadata object.
+ * @param timestamp The new {@link Long} timestamp to set.
+ */
public void setTimestamp(long timestamp) {
this.timestamp = timestamp;
}
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantEventPurgeResult.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantEventPurgeResult.java
index 7199a64b1..1c070aa76 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantEventPurgeResult.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantEventPurgeResult.java
@@ -17,7 +17,9 @@
package org.apache.unomi.api.tenants;
/**
- * Result of a tenant-scoped event retention purge request.
+ * Outcome of a request to delete old events for one tenant.
+ * Reports how many events matched the retention cutoff and whether the
+ * delete-by-query completed successfully.
*/
public class TenantEventPurgeResult {
@@ -34,42 +36,94 @@ public class TenantEventPurgeResult {
private boolean purgeRequested;
private long requestedAt;
+ /**
+ * Retrieves the unique identifier of the tenant
+ * associated with this result.
+ * @return The tenant ID string.
+ */
public String getTenantId() {
return tenantId;
}
+ /**
+ * Sets the unique identifier of the tenant associated with this result.
+ * @param tenantId The tenant ID to set.
+ */
public void setTenantId(String tenantId) {
this.tenantId = tenantId;
}
+ /**
+ * Retrieves the number of days events must be retained before
+ * purge consideration.
+ * @return The retention period in days.
+ */
public int getRetentionDays() {
return retentionDays;
}
+ /**
+ * Sets the number of days events must be retained before
+ * purge consideration.
+ * @param retentionDays The retention period in days.
+ */
public void setRetentionDays(int retentionDays) {
this.retentionDays = retentionDays;
}
+ /**
+ * Retrieves the estimated number of events that matched the retention
+ * cutoff before the delete-by-query was submitted; not a post-delete count.
+ * @return The count of matching events.
+ */
public long getEventsMatched() {
return eventsMatched;
}
+ /**
+ * Sets the estimated number of events that matched the retention cutoff
+ * before the delete-by-query was submitted; not a post-delete count.
+ * @param eventsMatched The estimated count of matching events.
+ */
public void setEventsMatched(long eventsMatched) {
this.eventsMatched = eventsMatched;
}
+ /**
+ * Checks whether the delete-by-query for event purging completed
+ * successfully.
+ *
+ * @return {@code true} if the delete-by-query completed successfully,
+ * {@code false} if the persistence layer reported a failure
+ */
public boolean isPurgeRequested() {
return purgeRequested;
}
+ /**
+ * Sets whether the delete-by-query for event purging completed
+ * successfully.
+ *
+ * @param purgeRequested {@code true} if the delete-by-query completed
+ * successfully, {@code false} otherwise
+ */
public void setPurgeRequested(boolean purgeRequested) {
this.purgeRequested = purgeRequested;
}
+ /**
+ * Gets the timestamp (in milliseconds) when this event retention purge
+ * request was initiated.
+ * @return The requested time in milliseconds since the epoch.
+ */
public long getRequestedAt() {
return requestedAt;
}
+ /**
+ * Sets the timestamp when the event retention purge request was initiated.
+ * @param requestedAt the time in milliseconds since the epoch
+ */
public void setRequestedAt(long requestedAt) {
this.requestedAt = requestedAt;
}
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantScopeUsage.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantScopeUsage.java
index 3029b1fb4..775b7be28 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantScopeUsage.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantScopeUsage.java
@@ -17,7 +17,9 @@
package org.apache.unomi.api.tenants;
/**
- * Segment and rule counts for one scope within a tenant.
+ * Usage counters for a single scope inside a tenant usage snapshot.
+ * Tracks how many segments and rules exist in that scope when
+ * {@link TenantUsageService} collects statistics.
*/
public class TenantScopeUsage {
@@ -25,26 +27,50 @@ public class TenantScopeUsage {
private long segmentCount;
private long ruleCount;
+ /**
+ * Retrieves the unique identifier of the scope.
+ * @return The scope ID as a {@link String}.
+ */
public String getScopeId() {
return scopeId;
}
+ /**
+ * Sets the unique identifier of the scope.
+ * @param scopeId The new scope ID to set.
+ */
public void setScopeId(String scopeId) {
this.scopeId = scopeId;
}
+ /**
+ * Retrieves the count of segments associated with this scope usage.
+ * @return The segment count as a {@link Long}.
+ */
public long getSegmentCount() {
return segmentCount;
}
+ /**
+ * Sets the count of segments associated with this scope usage.
+ * @param segmentCount The new segment count to set.
+ */
public void setSegmentCount(long segmentCount) {
this.segmentCount = segmentCount;
}
+ /**
+ * Retrieves the count of rules associated with this scope usage.
+ * @return The rule count as a {@link Long}.
+ */
public long getRuleCount() {
return ruleCount;
}
+ /**
+ * Sets the count of rules associated with this scope usage.
+ * @param ruleCount The new rule count to set.
+ */
public void setRuleCount(long ruleCount) {
this.ruleCount = ruleCount;
}
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantStatus.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantStatus.java
index aad239918..021f71b6e 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantStatus.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantStatus.java
@@ -17,8 +17,8 @@
package org.apache.unomi.api.tenants;
/**
- * Enumeration of possible tenant statuses.
- * This enum defines the various states a tenant can be in within the system.
+ * Lifecycle state of a tenant (for example active, suspended, or pending).
+ * Administrators filter and manage tenants based on these enum values.
*/
public enum TenantStatus {
/**
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantUsage.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantUsage.java
index 5b78ac10d..91414ce90 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantUsage.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantUsage.java
@@ -23,7 +23,6 @@ import java.util.List;
/**
* Read-only usage snapshot for a tenant. Values are refreshed on a background schedule
* (see {@link TenantUsageService}) and may be stale until the next collection cycle.
- *
* <p>Profile, scope, segment, and rule counts are point-in-time totals. {@link #eventCount}
* counts events whose {@code timeStamp} falls within {@link #periodStart} (inclusive) and
* {@link #periodEnd} (exclusive).</p>
@@ -53,116 +52,249 @@ public class TenantUsage {
private List<TenantScopeUsage> scopeUsages = new ArrayList<>();
private long collectedAt;
+ /**
+ * Retrieves the unique identifier for the tenant associated with
+ * this usage snapshot.
+ * @return The tenant ID string.
+ */
public String getTenantId() {
return tenantId;
}
+ /**
+ * Sets the unique identifier for the tenant associated with
+ * this usage snapshot.
+ * @param tenantId The ID of the tenant.
+ */
public void setTenantId(String tenantId) {
this.tenantId = tenantId;
}
+ /**
+ * Returns the normalized period label, e.g., {@code 2026-07}
+ * for a calendar month.
+ * @return The period label string.
+ */
public String getPeriod() {
return period;
}
+ /**
+ * Sets the normalized period label, e.g., {@code 2026-07}
+ * for a calendar month.
+ * @param period The desired period label.
+ */
public void setPeriod(String period) {
this.period = period;
}
+ /**
+ * Returns the inclusive start of the reporting period (epoch millis, UTC).
+ * @return The starting epoch millisecond value.
+ */
public long getPeriodStart() {
return periodStart;
}
+ /**
+ * Sets the inclusive start of the reporting period (epoch millis, UTC).
+ * @param periodStart The starting epoch millisecond value.
+ */
public void setPeriodStart(long periodStart) {
this.periodStart = periodStart;
}
+ /**
+ * Returns the exclusive end of the reporting period (epoch millis, UTC).
+ * @return The ending epoch millisecond value.
+ */
public long getPeriodEnd() {
return periodEnd;
}
+ /**
+ * Sets the exclusive end of the reporting period (epoch millis, UTC).
+ * @param periodEnd The ending epoch millisecond value.
+ */
public void setPeriodEnd(long periodEnd) {
this.periodEnd = periodEnd;
}
+ /**
+ * Retrieves the number of profiles associated with this
+ * tenant usage snapshot.
+ * @return The profile count.
+ */
public long getProfileCount() {
return profileCount;
}
+ /**
+ * Sets the number of profiles for this tenant usage snapshot.
+ * @param profileCount The total count of profiles.
+ */
public void setProfileCount(long profileCount) {
this.profileCount = profileCount;
}
+ /**
+ * Returns the number of events counted for this tenant in the reporting
+ * period. Events are included when their {@code timeStamp} falls within
+ * {@link #getPeriodStart()} (inclusive) and {@link #getPeriodEnd()}
+ * (exclusive).
+ *
+ * @return the event count for the reporting period
+ */
public long getEventCount() {
return eventCount;
}
+ /**
+ * Sets the count of events for this tenant usage snapshot.
+ * @param eventCount The total number of events.
+ */
public void setEventCount(long eventCount) {
this.eventCount = eventCount;
}
+ /**
+ * Retrieves the count of tenant scopes excluding
+ * {@code systemscope} for this period.
+ * @return The scope count.
+ */
public long getScopeCount() {
return scopeCount;
}
+ /**
+ * Sets the count of tenant scopes excluding {@code systemscope}.
+ * @param scopeCount The total number of scopes.
+ */
public void setScopeCount(long scopeCount) {
this.scopeCount = scopeCount;
}
+ /**
+ * Retrieves the count of segments associated with this
+ * tenant usage snapshot.
+ * @return The segment count.
+ */
public long getSegmentCount() {
return segmentCount;
}
+ /**
+ * Sets the count of segments for this tenant usage snapshot.
+ * @param segmentCount The total number of segments.
+ */
public void setSegmentCount(long segmentCount) {
this.segmentCount = segmentCount;
}
+ /**
+ * Retrieves the count of rules associated with this tenant usage snapshot.
+ * @return The number of rules.
+ */
public long getRuleCount() {
return ruleCount;
}
+ /**
+ * Sets the count of rules associated with this tenant usage snapshot.
+ * @param ruleCount The total number of rules.
+ */
public void setRuleCount(long ruleCount) {
this.ruleCount = ruleCount;
}
+ /**
+ * Retrieves the document count across all tenant indices
+ * recorded in this snapshot.
+ * @return The total document count.
+ */
public long getStorageDocumentCount() {
return storageDocumentCount;
}
+ /**
+ * Sets the document count across all tenant indices
+ * recorded in this snapshot.
+ * @param storageDocumentCount The total number of documents.
+ */
public void setStorageDocumentCount(long storageDocumentCount) {
this.storageDocumentCount = storageDocumentCount;
}
+ /**
+ * Retrieves the count of active API keys on the tenant record
+ * for this usage period.
+ * @return The number of active API keys.
+ */
public long getActiveApiKeyCount() {
return activeApiKeyCount;
}
+ /**
+ * Sets the count of active API keys on the tenant record
+ * for this usage period.
+ * @param activeApiKeyCount The total number of active API keys.
+ */
public void setActiveApiKeyCount(long activeApiKeyCount) {
this.activeApiKeyCount = activeApiKeyCount;
}
+ /**
+ * Retrieves the in-memory REST request counter for this tenant since the
+ * Unomi process started.
+ * @return The count of REST requests.
+ */
public long getRestRequestCount() {
return restRequestCount;
}
+ /**
+ * Sets the in-memory REST request counter for this tenant since the
+ * Unomi process started.
+ * @param restRequestCount The total number of REST requests recorded.
+ */
public void setRestRequestCount(long restRequestCount) {
this.restRequestCount = restRequestCount;
}
+ /**
+ * Retrieves an unmodifiable list of usage details for all tenant scopes.
+ * @return An unmodifiable {@link List<TenantScopeUsage>} containing
+ * scope usage snapshots.
+ */
public List<TenantScopeUsage> getScopeUsages() {
return Collections.unmodifiableList(scopeUsages);
}
+ /**
+ * Sets the list of usage details for all tenant scopes. This method
+ * performs a defensive copy of the provided list to ensure
+ * internal state immutability.
+ * @param scopeUsages The list of {@link TenantScopeUsage} objects.
+ */
public void setScopeUsages(List<TenantScopeUsage> scopeUsages) {
// Copy defensively: callers (including the internal usage cache) must not be able to
// mutate this snapshot's state through a shared list reference after construction.
this.scopeUsages = scopeUsages != null ? new ArrayList<>(scopeUsages) : new ArrayList<>();
}
+ /**
+ * Gets the timestamp (epoch millis) when this usage snapshot was collected.
+ * @return The collection time in epoch milliseconds.
+ */
public long getCollectedAt() {
return collectedAt;
}
+ /**
+ * Sets the timestamp (epoch millis) indicating when this usage
+ * snapshot was collected.
+ * @param collectedAt The collection time in epoch milliseconds.
+ */
public void setCollectedAt(long collectedAt) {
this.collectedAt = collectedAt;
}
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/TenantUsageService.java b/api/src/main/java/org/apache/unomi/api/tenants/TenantUsageService.java
index 789584683..5ca4850a9 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/TenantUsageService.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/TenantUsageService.java
@@ -43,6 +43,7 @@ public interface TenantUsageService {
/**
* Records one authenticated REST request for the tenant (in-memory counter).
+ * @param tenantId tenant identifier
*/
void recordRestRequest(String tenantId);
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/security/SecurityAuditReport.java b/api/src/main/java/org/apache/unomi/api/tenants/security/SecurityAuditReport.java
index eb1215bfc..3c4166531 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/security/SecurityAuditReport.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/security/SecurityAuditReport.java
@@ -140,50 +140,99 @@ public class SecurityAuditReport {
private String ipAddress;
private Map<String, Object> details;
+ /**
+ * Retrieves the type identifier of this security event.
+ * @return The string representing the event type.
+ */
public String getType() {
return type;
}
+ /**
+ * Sets the type identifier for this security event.
+ * @param type The type string to set.
+ */
public void setType(String type) {
this.type = type;
}
+ /**
+ * Retrieves the timestamp when the security event occurred.
+ * @return The {@link java.util.Date} representing the event time.
+ */
public Date getTimestamp() {
return timestamp;
}
+ /**
+ * Sets the timestamp for this security event.
+ * @param timestamp The {@link java.util.Date} to set as
+ * the event timestamp.
+ */
public void setTimestamp(Date timestamp) {
this.timestamp = timestamp;
}
+ /**
+ * Retrieves a detailed description of the security event.
+ * @return A string containing the event's description.
+ */
public String getDescription() {
return description;
}
+ /**
+ * Sets the descriptive text for this security event.
+ * @param description The description string to set.
+ */
public void setDescription(String description) {
this.description = description;
}
+ /**
+ * Retrieves the user ID associated with this security event.
+ * @return The unique identifier of the user involved in the event.
+ */
public String getUserId() {
return userId;
}
+ /**
+ * Sets the user ID associated with this security event.
+ * @param userId The user ID to set.
+ */
public void setUserId(String userId) {
this.userId = userId;
}
+ /**
+ * Gets the IP address associated with this security event.
+ * @return The stored {@link String} IP address.
+ */
public String getIpAddress() {
return ipAddress;
}
+ /**
+ * Sets the IP address associated with this security event.
+ * @param ipAddress the IP address to set.
+ */
public void setIpAddress(String ipAddress) {
this.ipAddress = ipAddress;
}
+ /**
+ * Gets a map containing additional details about the security event.
+ * @return The {@link java.util.Map} of details.
+ */
public Map<String, Object> getDetails() {
return details;
}
+ /**
+ * Sets a map containing additional details about the security event.
+ * @param details the map of details to set.
+ */
public void setDetails(Map<String, Object> details) {
this.details = details;
}
diff --git a/api/src/main/java/org/apache/unomi/api/tenants/security/SecuritySettings.java b/api/src/main/java/org/apache/unomi/api/tenants/security/SecuritySettings.java
index ade4913db..0667d2de5 100644
--- a/api/src/main/java/org/apache/unomi/api/tenants/security/SecuritySettings.java
+++ b/api/src/main/java/org/apache/unomi/api/tenants/security/SecuritySettings.java
@@ -103,34 +103,72 @@ public class SecuritySettings {
private int lockoutDurationMinutes;
private boolean requireMfa;
+ /**
+ * Gets the list of allowed authentication methods.
+ * @return A {@link java.util.List} of {@link String} representing the
+ * allowed auth methods.
+ */
public List<String> getAllowedAuthMethods() {
return allowedAuthMethods;
}
+ /**
+ * Sets the list of allowed authentication methods for the tenant.
+ * @param allowedAuthMethods The list of allowed authentication methods.
+ */
public void setAllowedAuthMethods(List<String> allowedAuthMethods) {
this.allowedAuthMethods = allowedAuthMethods;
}
+ /**
+ * Retrieves the maximum number of login attempts
+ * permitted before lockout.
+ * @return The maximum number of login attempts.
+ */
public int getMaxLoginAttempts() {
return maxLoginAttempts;
}
+ /**
+ * Sets the maximum number of consecutive failed login attempts allowed.
+ * @param maxLoginAttempts The maximum number of login attempts.
+ */
public void setMaxLoginAttempts(int maxLoginAttempts) {
this.maxLoginAttempts = maxLoginAttempts;
}
+ /**
+ * Gets the duration, in minutes, that an account remains locked after
+ * exceeding login attempts.
+ * @return The lockout duration in minutes.
+ */
public int getLockoutDurationMinutes() {
return lockoutDurationMinutes;
}
+ /**
+ * Sets the duration (in minutes) for which a user account will be
+ * locked out upon failed logins.
+ * @param lockoutDurationMinutes The desired lockout
+ * duration in minutes.
+ */
public void setLockoutDurationMinutes(int lockoutDurationMinutes) {
this.lockoutDurationMinutes = lockoutDurationMinutes;
}
+ /**
+ * Checks if multi-factor authentication is required for login.
+ * @return {@code true} if MFA is required, {@code false} otherwise.
+ */
public boolean isRequireMfa() {
return requireMfa;
}
+ /**
+ * Sets whether multi-factor authentication must be used during login.
+ * @param requireMfa If {@code true}, MFA is mandatory;
+ * otherwise, it is optional.
+ */
public void setRequireMfa(boolean requireMfa) {
this.requireMfa = requireMfa;
}
@@ -144,26 +182,54 @@ public class SecuritySettings {
private List<String> permissions;
private Map<String, List<String>> rolePermissions;
+ /**
+ * Retrieves the list of roles configured for this tenant.
+ * @return A {@link java.util.List} of strings
+ * representing the assigned roles.
+ */
public List<String> getRoles() {
return roles;
}
+ /**
+ * Sets the list of roles for this tenant.
+ * @param roles The list of role names to set.
+ */
public void setRoles(List<String> roles) {
this.roles = roles;
}
+ /**
+ * Retrieves the list of permissions configured for this tenant.
+ * @return A {@link java.util.List} of strings representing the
+ * assigned permissions.
+ */
public List<String> getPermissions() {
return permissions;
}
+ /**
+ * Sets the list of permissions for this tenant.
+ * @param permissions The list of permission names to set.
+ */
public void setPermissions(List<String> permissions) {
this.permissions = permissions;
}
+ /**
+ * Retrieves the mapping of roles to their associated permissions.
+ * @return A {@link java.util.Map} where keys are role names and values
+ * are lists of permissions.
+ */
public Map<String, List<String>> getRolePermissions() {
return rolePermissions;
}
+ /**
+ * Sets the mapping defining which permissions belong to specific roles.
+ * @param rolePermissions The map containing
+ * role-to-permission mappings to set.
+ */
public void setRolePermissions(Map<String, List<String>> rolePermissions) {
this.rolePermissions = rolePermissions;
}
diff --git a/api/src/main/java/org/apache/unomi/api/utils/ParserHelper.java b/api/src/main/java/org/apache/unomi/api/utils/ParserHelper.java
index 0ab6f08d6..f7fe61f37 100644
--- a/api/src/main/java/org/apache/unomi/api/utils/ParserHelper.java
+++ b/api/src/main/java/org/apache/unomi/api/utils/ParserHelper.java
@@ -37,7 +37,9 @@ import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
/**
- * Helper class to resolve condition, action and values types when loading definitions from JSON files
+ * Utilities for resolving condition, action, and value type references when
+ * importing JSON definitions. Walks condition trees, fills in missing type
+ * metadata, and extracts event types referenced by conditions.
*/
public class ParserHelper {
@@ -54,15 +56,62 @@ public class ParserHelper {
private static final int MAX_RECURSION_DEPTH = 1000;
+ /**
+ * A visitor implementation used by {@link ParserHelper} to traverse and
+ * process {@link Condition} nodes found within parsed
+ * definitions (e.g., from JSON).
+ * Subclasses must implement the required methods to define how conditions
+ * are visited upon entry and exited upon completion of processing.
+ */
public interface ConditionVisitor {
+ /**
+ * Visits a given {@link Condition} object, executing necessary logic
+ * for that specific condition during traversal.
+ * @param condition The condition being visited.
+ */
void visit(Condition condition);
+ /**
+ * Executes post-visit logic for the specified {@link Condition} object.
+ * This method is called after all descendants of the given condition
+ * have been processed.
+ * @param condition The condition whose children have
+ * finished processing.
+ */
void postVisit(Condition condition);
}
+ /**
+ * Utility class responsible for extracting and converting raw string values
+ * found in configuration definitions (such as conditions or actions) into
+ * usable Java objects.
+ * This abstract helper requires subclasses to implement the core logic of
+ * value extraction, utilizing both the {@code String} representation of the
+ * value and the associated {@link Event} context for resolution.
+ */
public interface ValueExtractor {
+ /**
+ * Extracts an object value from a given string representation using the
+ * provided event context.
+ * This method is abstract and must be implemented by
+ * concrete subclasses.
+ * @param valueAsString The string value that needs to be
+ * extracted or parsed.
+ * @param event The {@link Event} providing context for
+ * the extraction process.
+ * @return An object representing the extracted value.
+ * @throws IllegalAccessException if access to a required member fails.
+ * @throws NoSuchMethodException if a necessary method cannot be found.
+ * @throws InvocationTargetException if an exception occurs during
+ * invocation of the target method.
+ */
Object extract(String valueAsString, Event event) throws IllegalAccessException, NoSuchMethodException, InvocationTargetException;
}
+ /**
+ * Default map containing predefined {@link ValueExtractor} implementations.
+ * These extractors are used to retrieve values from various sources
+ * (profile, session, event) when processing definitions.
+ */
public static final Map<String,ValueExtractor> DEFAULT_VALUE_EXTRACTORS = new HashMap<>();
static {
DEFAULT_VALUE_EXTRACTORS.put("profileProperty", (valueAsString, event) -> PropertyUtils.getProperty(event.getProfile(), "properties." + valueAsString));
@@ -73,6 +122,20 @@ public class ParserHelper {
DEFAULT_VALUE_EXTRACTORS.put("simpleEventProperty", (valueAsString, event) -> event.getProperty(valueAsString));
}
+ /**
+ * Resolves the condition types recursively starting from a root condition.
+ * This method traverses the parent chain and parameter values of the given
+ * {@code rootCondition} to ensure all nested conditions have their types
+ * resolved against the provided definitions service. It updates the
+ * condition type on the condition object if successful.
+ * {@code false} otherwise.
+ * @param definitionsService service used to resolve condition types.
+ * @param rootCondition the starting condition for resolution.
+ * @param contextObjectName name of the object providing context
+ * (for error messages).
+ * @return {@code true} if all reachable conditions were
+ * successfully resolved,
+ */
public static boolean resolveConditionType(final DefinitionsService definitionsService, Condition rootCondition, String contextObjectName) {
return resolveConditionType(definitionsService, rootCondition, contextObjectName,
new HashSet<>(), false, 0);
@@ -158,21 +221,48 @@ public class ParserHelper {
}
}
+ /**
+ * Collects a list of unique condition type IDs present within the
+ * given root condition.
+ * This method traverses the entire structure of the condition, including
+ * nested parameters and collections, and gathers all associated
+ * condition type ids.
+ * @param rootCondition the condition whose types are to be collected.
+ * @return a list of unique strings representing the condition type IDs
+ * found in the condition tree.
+ */
public static List<String> getConditionTypeIds(Condition rootCondition) {
final List<String> result = new ArrayList<String>();
visitConditions(rootCondition, new ConditionVisitor() {
@Override
- public void visit(Condition condition) {
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public void visit(Condition condition) {
result.add(condition.getConditionTypeId());
}
@Override
- public void postVisit(Condition condition) {
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public void postVisit(Condition condition) {
}
});
return result;
}
+ /**
+ * Visits every condition within the given condition structure, executing
+ * the provided visitor for each one. This method handles recursive
+ * traversal through parameters and collections that may
+ * contain nested conditions.
+ * @param rootCondition the starting condition to visit.
+ * @param visitor the {@link ConditionVisitor} implementation to execute on
+ * every visited condition.
+ */
public static void visitConditions(Condition rootCondition, ConditionVisitor visitor) {
visitor.visit(rootCondition);
// recursive call for sub-conditions as parameters
@@ -194,6 +284,20 @@ public class ParserHelper {
visitor.postVisit(rootCondition);
}
+ /**
+ * Resolves action types for all actions contained within a given rule.
+ * This method checks if the rule has null or empty actions. If not, it
+ * attempts to resolve the type of each action using the
+ * {@link DefinitionsService}. It logs warnings if resolution fails and
+ * returns {@code false} if any structural error (null/empty actions) or
+ * resolution failure occurs.
+ * @param definitionsService service used to resolve action types.
+ * @param rule the rule containing actions whose types need resolving.
+ * @param ignoreErrors if {@code true}, warnings about missing or empty
+ * actions are suppressed.
+ * @return {@code true} if all actions were successfully resolved,
+ * {@code false} otherwise.
+ */
public static boolean resolveActionTypes(DefinitionsService definitionsService, Rule rule, boolean ignoreErrors) {
boolean result = true;
String ruleId = rule.getItemId();
@@ -227,6 +331,17 @@ public class ParserHelper {
return result;
}
+ /**
+ * Attempts to resolve the action type for a single given action.
+ * If the action's type is not already set, this method queries the
+ * definitions service to find and set the correct {@link ActionType}. It
+ * tracks unresolved types internally, logging warnings if resolution fails.
+ * {@code false} otherwise.
+ * @param definitionsService service used to resolve action types.
+ * @param action the action whose type needs resolving.
+ * @return {@code true} if the action's type was successfully
+ * resolved or already set,
+ */
public static boolean resolveActionType(DefinitionsService definitionsService, Action action) {
if (definitionsService == null) {
return false;
@@ -247,6 +362,16 @@ public class ParserHelper {
return true;
}
+ /**
+ * Resolves the value type for a given property type.
+ * This method first attempts to use the {@link DefinitionsService}'s
+ * internal {@link TypeResolutionService}. If that service is unavailable,
+ * it falls back to resolving the value type directly using the definitions
+ * service's lookup mechanism.
+ * The provided {@code PropertyType} object will be modified if successful.
+ * @param definitionsService service used to resolve property types.
+ * @param propertyType the property type whose value needs resolution.
+ */
public static void resolveValueType(DefinitionsService definitionsService, PropertyType propertyType) {
if (definitionsService == null) {
return;
@@ -268,12 +393,24 @@ public class ParserHelper {
/**
* @deprecated Use {@link #resolveConditionEventTypes(Condition, DefinitionsService)} instead.
+ * @param rootCondition the condition whose event types are to be resolved
+ * @return a set of unique event type identifiers
*/
@Deprecated
public static Set<String> resolveConditionEventTypes(Condition rootCondition) {
return resolveConditionEventTypes(rootCondition, null);
}
+ /**
+ * Resolves all unique event types associated with a condition structure.
+ * This method traverses the entire condition tree starting from
+ * {@code rootCondition} and collects every distinct event type ID found in
+ * any nested condition or parameter.
+ * @param rootCondition the condition whose event types are to be resolved.
+ * @param definitionsService service used for resolving event types.
+ * @return a set of unique strings representing all event types
+ * associated with the condition.
+ */
public static Set<String> resolveConditionEventTypes(Condition rootCondition, DefinitionsService definitionsService) {
if (rootCondition == null) {
return new HashSet<>();
@@ -283,16 +420,34 @@ public class ParserHelper {
return eventTypeConditionVisitor.getEventTypeIds();
}
+ /**
+ * A {@link ConditionVisitor} implementation used to traverse condition
+ * definitions within a rule or definition structure. It collects all unique
+ * event type IDs encountered during the traversal of conditions.
+ * This visitor maintains internal state, using a stack to track the current
+ * path of visited conditions and accumulating discovered {@code String}
+ * event type identifiers in a set.
+ */
public static class EventTypeConditionVisitor implements ConditionVisitor {
private final DefinitionsService definitionsService;
private Set<String> eventTypeIds = new HashSet<>();
private Stack<String> conditionTypeStack = new Stack<>();
+ /**
+ * Constructs an {@code EventTypeConditionVisitor} and initializes it
+ * with a service used to resolve condition types.
+ * @param definitionsService The service providing definitions necessary
+ * for resolving type information.
+ */
public EventTypeConditionVisitor(DefinitionsService definitionsService) {
this.definitionsService = definitionsService;
}
+ /**
+ * {@inheritDoc}
+ */
+ @Override
public void visit(Condition condition) {
conditionTypeStack.push(condition.getConditionTypeId());
@@ -344,15 +499,41 @@ public class ParserHelper {
}
}
+ /**
+ * {@inheritDoc}
+ */
+ @Override
public void postVisit(Condition condition) {
conditionTypeStack.pop();
}
+ /**
+ * Retrieves the set of event type IDs that have been collected by
+ * this visitor instance.
+ * @return A {@link Set} containing all resolved event type identifiers.
+ */
public Set<String> getEventTypeIds() {
return eventTypeIds;
}
}
+ /**
+ * Parses a map of values, resolving any placeholders found within string
+ * values using provided extractors and event context.
+ * This method iterates through the input map. If a value is a String
+ * containing placeholders (e.g., ${placeholder}), it recursively resolves
+ * these placeholders by calling {@link #extractValue(String, Event, Map)}.
+ * The resulting map contains the processed values with resolved objects
+ * instead of placeholder strings.
+ * @param event The current event used for value
+ * extraction during resolution.
+ * @param map The input map containing potentially
+ * placeholder-filled values.
+ * @param valueExtractors A map linking value type names to their
+ * respective extractors.
+ * @return A new {@link Map<String, Object>} with the string placeholders
+ * resolved into actual object values.
+ */
@SuppressWarnings("unchecked")
public static Map<String, Object> parseMap(Event event, Map<String, Object> map, Map<String, ValueExtractor> valueExtractors) {
Map<String, Object> values = new HashMap<>();
@@ -391,6 +572,27 @@ public class ParserHelper {
return values;
}
+ /**
+ * Extracts an object value from a string that follows a specific
+ * format (type::value).
+ * The method splits the input string using "::" to separate the expected
+ * value type from the raw value content. It then uses the provided
+ * {@link ValueExtractor} to perform the actual extraction based
+ * on the event context.
+ * @param s The input string containing the type and
+ * value separated by "::".
+ * @param event The current event used during value extraction.
+ * @param valueExtractors A map of available extractors
+ * keyed by value type name.
+ * @return The extracted object value, or null if no extractor is found
+ * or extraction fails.
+ * @throws IllegalAccessException If the underlying extractor
+ * throws this exception.
+ * @throws NoSuchMethodException If the underlying extractor
+ * throws this exception.
+ * @throws InvocationTargetException If the underlying extractor
+ * throws this exception.
+ */
public static Object extractValue(String s, Event event, Map<String, ValueExtractor> valueExtractors) throws IllegalAccessException, NoSuchMethodException, InvocationTargetException {
Object value = null;
@@ -409,6 +611,19 @@ public class ParserHelper {
return value;
}
+ /**
+ * Determines if any string value within the provided map (including nested
+ * maps) contains a placeholder that references a known
+ * contextual parameter type.
+ * This method recursively checks all values. For strings, it attempts to
+ * extract content from placeholders and validates if the resulting type
+ * name matches an available extractor.
+ * @param values The map of parameters to check for contextual parameters.
+ * @param valueExtractors A map containing all available value extractors,
+ * used to validate parameter types.
+ * @return True if at least one string value represents a contextual
+ * parameter; otherwise, false.
+ */
@SuppressWarnings("unchecked")
public static boolean hasContextualParameter(Map<String, Object> values, Map<String, ValueExtractor> valueExtractors) {
for (Map.Entry<String, Object> entry : values.entrySet()) {
@@ -434,10 +649,8 @@ public class ParserHelper {
/**
* Gets the full parent chain for a condition type.
- *
* This method iteratively collects all parent conditions, detecting
* circular references.
- *
* @param conditionType the condition type
* @param definitionsService service to resolve types
* @param contextName name for error messages
@@ -510,7 +723,6 @@ public class ParserHelper {
/**
* Deep copies a parameter value, handling Condition objects and collections containing Conditions.
* This is a helper method to avoid code duplication when merging parameters.
- *
* @param value the parameter value to deep copy
* @return a deep copy of the value, or the original value if it's not a Condition or collection
*/
@@ -535,11 +747,9 @@ public class ParserHelper {
/**
* Resolves the effective condition to use, following the parent chain.
- *
* This method traverses the parent condition chain and returns the condition
* at the end of the chain (the root parent). It merges parameters from all
* levels in the chain into the context and the effective condition.
- *
* @param condition the condition to resolve
* @param definitionsService service to resolve condition types
* @param context context map for parameter merging (will be modified)
@@ -557,7 +767,6 @@ public class ParserHelper {
/**
* Resolves the effective condition to use, following the parent chain.
- *
* @param condition the condition to resolve
* @param definitionsService service to resolve condition types
* @param context context map for parameter merging (will be modified)
diff --git a/api/src/main/java/org/apache/unomi/api/utils/YamlUtils.java b/api/src/main/java/org/apache/unomi/api/utils/YamlUtils.java
index 0755fbe6d..07d3c4cba 100644
--- a/api/src/main/java/org/apache/unomi/api/utils/YamlUtils.java
+++ b/api/src/main/java/org/apache/unomi/api/utils/YamlUtils.java
@@ -210,6 +210,7 @@ public class YamlUtils {
/**
* Converts a Set to a sorted List for YAML output.
*
+ * @param <T> the element type, which must be {@link Comparable}
* @param set the set to convert
* @return a sorted list, or null if the set is null or empty
*/
@@ -223,6 +224,8 @@ public class YamlUtils {
/**
* Converts a Set to a sorted List using a mapper function.
*
+ * @param <T> the source element type
+ * @param <R> the mapped element type, which must be {@link Comparable}
* @param set the set to convert
* @param mapper the mapper function (must not be null)
* @return a sorted list, or null if the set is null or empty
diff --git a/build.sh b/build.sh
index d4dfb2f30..fd28ed1ff 100755
--- a/build.sh
+++ b/build.sh
@@ -326,7 +326,7 @@ EOF
echo -e " ${CYAN}--search-engine-logs${NC} Stream search engine Docker logs to the Maven console during integration tests"
echo -e " ${CYAN}--no-memory-sampler${NC} Disable JVM/system memory sampling during integration tests"
echo -e " ${CYAN}--memory-interval SEC${NC} Memory sample interval in seconds (default: 30)"
- echo -e " ${CYAN}--javadoc${NC} Build and validate Javadoc after install (fails on doclint errors)"
+ echo -e " ${CYAN}--javadoc${NC} Build and validate Javadoc after install (doclint errors fail; public/protected tag gaps warn)"
echo -e " ${CYAN}--ci${NC} CI mode: no Karaf, non-interactive, includes Javadoc"
echo -e " ${CYAN}--log-file PATH${NC} Tee all output to PATH (console + file)"
echo -e " ${CYAN}--log-file-only${NC} With --log-file: write to file only, suppress console"
@@ -369,7 +369,7 @@ EOF
echo " --search-engine-logs Stream search engine Docker logs to the Maven console during integration tests"
echo " --no-memory-sampler Disable JVM/system memory sampling during integration tests"
echo " --memory-interval SEC Memory sample interval in seconds (default: 30)"
- echo " --javadoc Build and validate Javadoc after install (fails on doclint errors)"
+ echo " --javadoc Build and validate Javadoc after install (doclint errors fail; public/protected tag gaps warn)"
echo " --ci CI mode: no Karaf, non-interactive, includes Javadoc"
echo " --log-file PATH Tee all output to PATH (console + file)"
echo " --log-file-only With --log-file: write to file only, suppress console"
@@ -1161,7 +1161,7 @@ echo "Estimated time: 3-5 minutes for build, 50-60 minutes with integration test
start_timer
# Build phases with enhanced output
-[ "$JAVADOC" = true ] && total_steps=3 || total_steps=2
+[ "$JAVADOC" = true ] && total_steps=4 || total_steps=2
current_step=0
write_it_run_trace_start() {
@@ -1276,7 +1276,7 @@ print_status "success" "Build completed in $(get_elapsed_time)"
if [ "$JAVADOC" = true ]; then
print_section "Javadoc Validation"
- print_progress $((++current_step)) $total_steps "Generating and validating Javadoc..."
+ print_progress $((++current_step)) $total_steps "Generating Javadoc (doclint: links, HTML, syntax)..."
if [ "$HAS_COLORS" -eq 1 ]; then
echo -e "${GRAY}Running: $MVN_CMD javadoc:javadoc -DskipTests $MVN_OPTS${NC}"
else
@@ -1286,7 +1286,19 @@ if [ "$JAVADOC" = true ]; then
print_status "error" "Javadoc validation failed — fix doclint errors above before pushing"
exit 1
}
- print_status "success" "Javadoc validated successfully"
+ print_status "success" "Javadoc doclint passed (no broken links, HTML, or syntax errors)"
+
+ print_progress $((++current_step)) $total_steps "Checking public/protected Javadoc tags (warnings only)..."
+ if [ "$HAS_COLORS" -eq 1 ]; then
+ echo -e "${GRAY}Running: $MVN_CMD -Pjavadoc-tags-warn checkstyle:check -DskipTests $MVN_OPTS${NC}"
+ else
+ echo "Running: $MVN_CMD -Pjavadoc-tags-warn checkstyle:check -DskipTests $MVN_OPTS"
+ fi
+ $MVN_CMD -Pjavadoc-tags-warn checkstyle:check -DskipTests $MVN_OPTS || {
+ print_status "error" "Javadoc tag check failed unexpectedly — see output above"
+ exit 1
+ }
+ print_status "success" "Javadoc tag check completed (review any warnings above)"
fi
# Deployment section with enhanced output
diff --git a/config/checkstyle-javadoc.xml b/config/checkstyle-javadoc.xml
new file mode 100644
index 000000000..775fffc0b
--- /dev/null
+++ b/config/checkstyle-javadoc.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+ "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+ "https://checkstyle.org/dtds/configuration_1_3.dtd">
+<!--
+ Javadoc tag completeness for public + protected API only.
+ Private and package-private members are intentionally out of scope.
+
+ Run: mvn -pl api -Pjavadoc-tags-warn checkstyle:check
+ (warnings only — does not fail the build)
+-->
+<module name="Checker">
+ <property name="severity" value="warning"/>
+ <module name="TreeWalker">
+ <module name="MissingJavadocMethod">
+ <property name="scope" value="protected"/>
+ <property name="allowedAnnotations" value="Override,Deprecated"/>
+ </module>
+ <module name="MissingJavadocType">
+ <property name="scope" value="protected"/>
+
+ </module>
+ <module name="JavadocMethod">
+ <property name="accessModifiers" value="public, protected"/>
+ <property name="allowedAnnotations" value="Override,Deprecated"/>
+ </module>
+ <module name="JavadocType">
+ <property name="scope" value="protected"/>
+ </module>
+ </module>
+</module>
diff --git a/pom.xml b/pom.xml
index 02bd8aa79..00b844bdb 100644
--- a/pom.xml
+++ b/pom.xml
@@ -165,6 +165,7 @@
<checksum-maven-plugin.version>1.7</checksum-maven-plugin.version>
<maven-jar-plugin.version>3.2.2</maven-jar-plugin.version>
<maven-checkstyle-plugin.version>2.13</maven-checkstyle-plugin.version>
+ <maven-checkstyle-javadoc-plugin.version>3.6.0</maven-checkstyle-javadoc-plugin.version>
<license-maven-plugin.version>2.0.0</license-maven-plugin.version>
<maven-notice-plugin.version>1.0.6</maven-notice-plugin.version>
@@ -567,6 +568,37 @@
</plugins>
</build>
</profile>
+ <profile>
+ <id>javadoc-tags-warn</id>
+ <activation>
+ <activeByDefault>false</activeByDefault>
+ </activation>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <version>${maven-checkstyle-javadoc-plugin.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>com.puppycrawl.tools</groupId>
+ <artifactId>checkstyle</artifactId>
+ <version>10.21.4</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <configLocation>config/checkstyle-javadoc.xml</configLocation>
+ <consoleOutput>true</consoleOutput>
+ <failsOnError>false</failsOnError>
+ <failOnViolation>false</failOnViolation>
+ <logViolationsToConsole>true</logViolationsToConsole>
+ <violationSeverity>warning</violationSeverity>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+
<profile>
<id>update-licenses</id>
<build>
@@ -880,6 +912,16 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc.plugin.version}</version>
+ <configuration>
+ <!-- Generated site: public + protected members only (private omitted) -->
+ <show>protected</show>
+ <!-- Doclint: reference/syntax/html/accessibility only (see -missing note below) -->
+ <doclint>all,-missing</doclint>
+ <notimestamp>true</notimestamp>
+ <!-- Broken {@link}/HTML/syntax fail the build; missing @param/@return do not (use -Pjavadoc-tags-warn) -->
+ <failOnError>true</failOnError>
+ <failOnWarnings>false</failOnWarnings>
+ </configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>