Javadoc fixes
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/FormattingResultLog.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/FormattingResultLog.java
index d466e46..c1ac526 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/FormattingResultLog.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/FormattingResultLog.java
@@ -27,38 +27,56 @@
@ProviderType
public class FormattingResultLog extends ResultLog {
- private ResultLog.Entry createEntry(Result.Status status, String format, Object... args) {
- return new ResultLog.Entry(status, MessageFormatter.arrayFormat(format, args).getMessage());
- }
- private ResultLog.Entry createEntry(boolean isDebug, String format, Object... args) {
- return new ResultLog.Entry(MessageFormatter.arrayFormat(format, args).getMessage(), isDebug);
+ /**
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void debug(String message, Object... args) {
+ add(createEntry(true, message, args));
}
- public void debug(String format, Object... args) {
- add(createEntry(true, format, args));
+ /**
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void info(String message, Object... args) {
+ add(createEntry(false, message, args));
}
- public void info(String format, Object... args) {
- add(createEntry(false, format, args));
+ /**
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void warn(String message, Object... args) {
+ add(createEntry(Result.Status.WARN, message, args));
}
- public void warn(String format, Object... args) {
- add(createEntry(Result.Status.WARN, format, args));
+ /**
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void critical(String message, Object... args) {
+ add(createEntry(Result.Status.CRITICAL, message, args));
}
- public void critical(String format, Object... args) {
- add(createEntry(Result.Status.CRITICAL, format, args));
- }
-
- public void temporarilyUnavailable(String format, Object... args) {
- add(createEntry(Result.Status.TEMPORARILY_UNAVAILABLE, format, args));
+ /**
+ *
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void temporarilyUnavailable(String message, Object... args) {
+ add(createEntry(Result.Status.TEMPORARILY_UNAVAILABLE, message, args));
}
- public void healthCheckError(String format, Object... args) {
- add(createEntry(Result.Status.HEALTH_CHECK_ERROR, format, args));
+ /**
+ * @param message The message for the log entry (with {} placeholders as known from slf4j)
+ * @param args The args for the placeholders given in message
+ */
+ public void healthCheckError(String message, Object... args) {
+ add(createEntry(Result.Status.HEALTH_CHECK_ERROR, message, args));
}
- /** Utility method to return any magnitude of milliseconds in a human readable format using the appropriate time unit (ms, sec, min)
+ /** Utility method to return any magnitude of milliseconds in a human readable message using the appropriate time unit (ms, sec, min)
* depending on the magnitude of the input.
*
* @param millis milliseconds
@@ -111,5 +129,12 @@
return retVal;
}
+
+ private ResultLog.Entry createEntry(Result.Status status, String message, Object... args) {
+ return new ResultLog.Entry(status, MessageFormatter.arrayFormat(message, args).getMessage());
+ }
+ private ResultLog.Entry createEntry(boolean isDebug, String message, Object... args) {
+ return new ResultLog.Entry(MessageFormatter.arrayFormat(message, args).getMessage(), isDebug);
+ }
}
\ No newline at end of file
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/HealthCheck.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/HealthCheck.java
index 26a4c80..46e0201 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/HealthCheck.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/HealthCheck.java
@@ -23,8 +23,8 @@
* for most cases it is most convenient to use {@link FormattingResultLog} that automatically derives the correct {@link Result.Status} from
* the log messages.
*
- * Clients should not look up health checks directly but rather use the {@link org.apache.felix.hc.api.execution.HealthCheckExecutor}
- * service and executed checks based on tags.
+ * Clients must not look up health checks directly but rather use the {@link org.apache.felix.hc.api.execution.HealthCheckExecutor}
+ * service and execute checks based on tags (or name).
*
* If the {@link #MBEAN_NAME} service registration property is set, the health check is registered as an mbean and can be invoked by getting
* the MBean from the JMX registry. */
@@ -61,6 +61,7 @@
* to OK with a delay (can be useful for load balancers). */
String KEEP_NON_OK_RESULTS_STICKY_FOR_SEC = "hc.keepNonOkResultsStickyForSec";
- /** Execute this health check and return a {@link Result}.*/
+ /** Execute this health check.
+ * @return a {@link Result}.*/
Result execute();
}
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/Result.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/Result.java
index 68737c0..ecf1d63 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/Result.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/Result.java
@@ -22,6 +22,7 @@
/** The result of executing a {@link HealthCheck} */
public class Result implements Iterable<ResultLog.Entry> {
+ /** The status of a {@link Result}. */
public enum Status {
OK, // system is fully operational
WARN, // attention required but system is operational
@@ -34,34 +35,39 @@
/** Build a single-value Result
*
- * @param s if lower than OK, our status is set to OK */
+ * @param s if lower than OK, our status is set to OK
+ * @param explanation message for the status */
public Result(final Status s, final String explanation) {
resultLog = new ResultLog().add(new ResultLog.Entry(s, explanation));
}
/** Build a single-value Result with exception
*
- * @param s if lower than OK, our status is set to OK */
+ * @param s if lower than OK, our status is set to OK
+ * @param explanation message for the status
+ * @param e the exception for this Result */
public Result(final Status s, final String explanation, final Exception e) {
resultLog = new ResultLog().add(new ResultLog.Entry(s, explanation, e));
}
- /** Build a a Result based on a ResultLog, which can provide more details than a single-value Result. */
+ /** Build a a Result based on a ResultLog, which can provide more details than a single-value Result
+ * @param log the log to base the result on*/
public Result(final ResultLog log) {
resultLog = new ResultLog(log);
}
- /** True if our status is OK - provides a convenient way of checking that. */
+ /** True if our status is OK - provides a convenient way of checking that
+ * @return true if the status is ok. */
public boolean isOk() {
return getStatus().equals(Status.OK);
}
- /** Return our Status */
+ /** @return the status of this result */
public Status getStatus() {
return resultLog.getAggregateStatus();
}
- /** Return an Iterator on the entries of our ResultLog */
+ /** @return an Iterator on the entries of our ResultLog */
@Override
public Iterator<ResultLog.Entry> iterator() {
return resultLog.iterator();
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/ResultLog.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/ResultLog.java
index 575a4d2..e09b8eb 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/ResultLog.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/ResultLog.java
@@ -43,17 +43,35 @@
private final boolean isDebug;
private final Exception exception;
+ /**
+ * @param s The status of the message
+ * @param message The message
+ */
public Entry(Status s, String message) {
this(s, message, false, null);
}
+ /**
+ * @param message The message with status OK
+ * @param isDebug Whether this is a debug message
+ */
public Entry(String message, boolean isDebug) {
this(Status.OK, message, isDebug, null);
}
+ /**
+ * @param message The message with status OK
+ * @param isDebug Whether this is a debug message
+ * @param exception An exception that belongs to this message
+ */
public Entry(String message, boolean isDebug, Exception exception) {
this(Status.OK, message, isDebug, exception);
}
+ /**
+ * @param s The status of the message
+ * @param message The message
+ * @param exception An exception that belongs to this message
+ */
public Entry(Status s, String message, Exception exception) {
this(s, message, false, exception);
}
@@ -75,10 +93,16 @@
return builder.toString();
}
+ /**
+ * @return The status of this entry
+ */
public Status getStatus() {
return status;
}
+ /**
+ * @return The log level of this entry
+ */
public String getLogLevel() {
switch (status) {
case OK:
@@ -88,14 +112,23 @@
}
}
+ /**
+ * @return The message of this entry
+ */
public String getMessage() {
return message;
}
+ /**
+ * @return The exception of this entry or null if no exception exists for this message
+ */
public Exception getException() {
return exception;
}
+ /**
+ * @return true if this is a debug message
+ */
public boolean isDebug() {
return isDebug;
}
@@ -108,13 +141,33 @@
setupLogger();
}
- /** Create a copy of the result log */
+ /** Create a copy of the result log
+ * @param log Clone constructor */
public ResultLog(final ResultLog log) {
this.aggregateStatus = log.aggregateStatus;
this.entries = new ArrayList<ResultLog.Entry>(log.entries);
setupLogger();
}
+ /** Add an entry to this log. The aggregate status of this is set to the highest of the current
+ * aggregate status and the new Entry's status
+ * @param entry The entry to add
+ * @return the result log for chaining */
+ public ResultLog add(Entry entry) {
+ if (entries.isEmpty()) {
+ aggregateStatus = Result.Status.OK;
+ }
+
+ entries.add(entry);
+
+ logEntry(entry);
+
+ if (entry.getStatus().ordinal() > aggregateStatus.ordinal()) {
+ aggregateStatus = entry.getStatus();
+ }
+ return this;
+ }
+
private void setupLogger() {
if(Boolean.valueOf(System.getProperty(HC_LOGGING_SYS_PROP))) {
StackTraceElement[] stackTraceElements = Thread.currentThread().getStackTrace();
@@ -133,24 +186,6 @@
}
}
-
- /** Add an entry to this log. The aggregate status of this is set to the highest of the current aggregate status and the new Entry's
- * status */
- public ResultLog add(Entry entry) {
- if (entries.isEmpty()) {
- aggregateStatus = Result.Status.OK;
- }
-
- entries.add(entry);
-
- logEntry(entry);
-
- if (entry.getStatus().ordinal() > aggregateStatus.ordinal()) {
- aggregateStatus = entry.getStatus();
- }
- return this;
- }
-
private void logEntry(Entry entry) {
if(hcLogger != null) {
if(entry.isDebug()) {
@@ -181,14 +216,17 @@
return e.status.name() + " " + e.getMessage();
}
- /** Return an Iterator on our entries */
+ /** Return an Iterator on our entries
+ * @return the iterator over all entries */
@Override
public Iterator<ResultLog.Entry> iterator() {
return entries.iterator();
}
/** Return our aggregate status, i.e. the highest status of the entries added to this log. Starts at OK for an empty ResultLog, so
- * cannot be lower than that. */
+ * cannot be lower than that.
+ *
+ * @return the aggregate status */
public Status getAggregateStatus() {
return aggregateStatus;
}
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionOptions.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionOptions.java
index 8ad1c4e..9de2fcf 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionOptions.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionOptions.java
@@ -24,15 +24,10 @@
private boolean combineTagsWithOr = false;
private int overrideGlobalTimeout = 0;
- @Override
- public String toString() {
- return "[HealthCheckExecutionOptions forceInstantExecution=" + forceInstantExecution + ", combineTagsWithOr=" + combineTagsWithOr
- + ", overrideGlobalTimeout=" + overrideGlobalTimeout + "]";
- }
-
/** If activated, this will ensure that asynchronous checks will be executed immediately.
*
- * @param forceInstantExecution boolean flag */
+ * @param forceInstantExecution boolean flag
+ * @return the HealthCheckExecutionOptions options for chaining */
public HealthCheckExecutionOptions setForceInstantExecution(boolean forceInstantExecution) {
this.forceInstantExecution = forceInstantExecution;
return this;
@@ -40,7 +35,8 @@
/** If activated, the given tags will be combined with a logical "or" instead of "and".
*
- * @param combineTagsWithOr boolean flag */
+ * @param combineTagsWithOr boolean flag
+ * @return the HealthCheckExecutionOptions options for chaining */
public HealthCheckExecutionOptions setCombineTagsWithOr(boolean combineTagsWithOr) {
this.combineTagsWithOr = combineTagsWithOr;
return this;
@@ -48,7 +44,8 @@
/** Allows to override the global timeout for this particular execution of the health check.
*
- * @param overrideGlobalTimeout timeout in ms to be used for this execution of the execution */
+ * @param overrideGlobalTimeout timeout in ms to be used for this execution of the execution
+ * @return the HealthCheckExecutionOptions options for chaining */
public HealthCheckExecutionOptions setOverrideGlobalTimeout(int overrideGlobalTimeout) {
this.overrideGlobalTimeout = overrideGlobalTimeout;
return this;
@@ -70,6 +67,12 @@
}
@Override
+ public String toString() {
+ return "[HealthCheckExecutionOptions forceInstantExecution=" + forceInstantExecution + ", combineTagsWithOr=" + combineTagsWithOr
+ + ", overrideGlobalTimeout=" + overrideGlobalTimeout + "]";
+ }
+
+ @Override
public int hashCode() {
final int prime = 31;
int result = 1;
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionResult.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionResult.java
index 4ab1f58..b5eb032 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionResult.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutionResult.java
@@ -26,10 +26,11 @@
@ProviderType
public interface HealthCheckExecutionResult {
- /** Get the result of the health check run. */
+ /** Get the result of the health check run.
+ * @return the plain result {@link Result} */
Result getHealthCheckResult();
- /** Get the elapsed time in ms */
+ /** @return The elapsed time in ms */
long getElapsedTimeInMs();
/** Get the date, the health check finished or if the execution timed out, the execution was aborted.
@@ -43,6 +44,7 @@
* @return <code>true</code> if execution timed out. */
boolean hasTimedOut();
- /** Get the meta data about the health check service */
+ /** Get the meta data about the health check service
+ * @return The {@link HealthCheckMetadata} the result was created for. */
HealthCheckMetadata getHealthCheckMetadata();
}
\ No newline at end of file
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutor.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutor.java
index 939db09..903fac3 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutor.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckExecutor.java
@@ -22,7 +22,18 @@
import org.apache.felix.hc.api.HealthCheck;
import org.osgi.annotation.versioning.ProviderType;
-/** Executes health checks registered as OSGi services and implementing the interface {@link HealthCheck}. */
+/**
+ * Executes health checks registered as OSGi services and implementing the
+ * interface {@link HealthCheck}.
+ *
+ * The executor is optimized:
+ * <ul>
+ * <li>All health checks as selected by {@link HealthCheckSelector} are executed in parallel</li>
+ * <li>If the same health check is triggered in parallel, it is only executed once</li>
+ * <li>Special handling for async execution, timeout, stickiness and caching as defined by service properties in {@link HealthCheck}</li>
+ * </ul>
+ *
+ */
@ProviderType
public interface HealthCheckExecutor {
diff --git a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckMetadata.java b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckMetadata.java
index 4035aed..76896b2 100644
--- a/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckMetadata.java
+++ b/healthcheck/api/src/main/java/org/apache/felix/hc/api/execution/HealthCheckMetadata.java
@@ -57,7 +57,11 @@
@Deprecated
private final String WARNINGS_STICK_FOR_MINUTES = "hc.warningsStickForMinutes";
-
+ /**
+ * Creates a HealthCheckMetadata from an OSGi service based on the service properties.
+ *
+ * @param ref the ServiceReference for the HC service
+ */
public HealthCheckMetadata(final ServiceReference ref) {
this.serviceId = (Long) ref.getProperty(Constants.SERVICE_ID);
this.name = (String) ref.getProperty(HealthCheck.NAME);
@@ -101,34 +105,40 @@
}
/** The title of the health check. If the health check has a name, this is used as the title. Otherwise the description, PID and service
- * ID are checked for values. */
+ * ID are checked for values.
+ *
+ * @return The computed title */
public String getTitle() {
return title;
}
/** Return the list of defined tags for this check as set through {@link HealthCheckMetadata#tags}
*
- * @return */
+ * @return list of tags (may be empty but never returns <code>null</code>) */
public List<String> getTags() {
return tags;
}
- /** Return the cron expression used for asynchronous execution. */
+ /** Return the cron expression used for asynchronous execution.
+ * @return the async cron expression (or <code>null</code> if not set) */
public String getAsyncCronExpression() {
return asyncCronExpression;
}
- /** Return the interval in sec used for asynchronous execution. */
+ /** Return the interval in sec used for asynchronous execution.
+ * @return the async interval (or <code>null</code> if not set) */
public Long getAsyncIntervalInSec() {
return asyncIntervalInSec;
}
- /** Return the service id. */
+ /** Return the service id.
+ * @return the service id (never <code>null</code>) */
public long getServiceId() {
return this.serviceId;
}
- /** Get the service reference. */
+ /** Get the service reference.
+ * @return the service reference (never <code>null</code>) */
public ServiceReference getServiceReference() {
return this.serviceReference;
}
