From ef81157c477568a906f423cef47288ccafc385c3 Mon Sep 17 00:00:00 2001 From: Chris Earle Date: Sun, 21 Feb 2016 17:12:16 -0500 Subject: [PATCH] Add Javadocs Also a minor fix to the phrasing in `MarvelLicensee#expirationMessages()`. Original commit: elastic/x-pack-elasticsearch@9366c0793001a50b140df5df51d67b88b08f8380 --- .../marvel/agent/AgentService.java | 9 +++ .../marvel/agent/renderer/Renderer.java | 17 +++++- .../marvel/license/MarvelLicensee.java | 56 ++++++++++++++++--- 3 files changed, 72 insertions(+), 10 deletions(-) diff --git a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/AgentService.java b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/AgentService.java index c691b5f34a6..6e115090942 100644 --- a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/AgentService.java +++ b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/AgentService.java @@ -29,6 +29,15 @@ import java.util.Locale; import java.util.Set; import java.util.concurrent.TimeUnit; +/** + * The {@code AgentService} is a service that does the work of publishing the details to the monitoring cluster. + *

+ * If this service is stopped, then the attached, monitored node is not going to publish its details to the monitoring cluster. Given + * service life cycles, the intended way to temporarily stop the publishing is using the start and stop collection methods. + * + * @see #stopCollection() + * @see #startCollection() + */ public class AgentService extends AbstractLifecycleComponent { private volatile ExportingWorker exportingWorker; diff --git a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/renderer/Renderer.java b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/renderer/Renderer.java index caa49e4eac3..5903fad1452 100644 --- a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/renderer/Renderer.java +++ b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/renderer/Renderer.java @@ -11,9 +11,22 @@ import java.io.IOException; import java.io.OutputStream; /** - * Renderers are used to render documents using a given OutputStream. + * {@code Renderer}s are used to render documents using a given OutputStream. + *

+ * Each {@code Renderer} can be thought of as a generator of a unique document type within the resulting ES index. For example, + * there will be details about shards, which requires a unique document type and there will also be details about indices, which requires + * their own unique documents. + * + * @see AbstractRenderer */ public interface Renderer { - + /** + * Convert the given {@code document} type into something that can be sent to the monitoring cluster. + * + * @param document The arbitrary document (e.g., details about a shard) + * @param xContentType The rendered content type (e.g., JSON) + * @param os The buffer + * @throws IOException if any unexpected error occurs + */ void render(T document, XContentType xContentType, OutputStream os) throws IOException; } diff --git a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/license/MarvelLicensee.java b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/license/MarvelLicensee.java index fdd94dfd1bf..79896e19e3d 100644 --- a/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/license/MarvelLicensee.java +++ b/elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/license/MarvelLicensee.java @@ -16,7 +16,15 @@ import org.elasticsearch.license.plugin.core.Licensee; import org.elasticsearch.license.plugin.core.LicenseeRegistry; import org.elasticsearch.marvel.Marvel; - +/** + * {@code MarvelLicensee} determines whether certain features of Monitoring are enabled or disabled. + *

+ * Once the license expires, the agent will stop: + *

+ */ public class MarvelLicensee extends AbstractLicenseeComponent implements Licensee { @Inject @@ -24,11 +32,17 @@ public class MarvelLicensee extends AbstractLicenseeComponent im super(settings, Marvel.NAME, clientService); } + /** + * {@inheritDoc} + * + * @see #collectionEnabled() + * @see #cleaningEnabled() + */ @Override public String[] expirationMessages() { return new String[] { "The agent will stop collecting cluster and indices metrics", - "The agent will stop to automatically clean up indices older than [xpack.monitoring.history.duration]", + "The agent will stop automatically cleaning indices older than [xpack.monitoring.history.duration]", }; } @@ -58,21 +72,47 @@ public class MarvelLicensee extends AbstractLicenseeComponent im return Strings.EMPTY_ARRAY; } + /** + * Determine if the index cleaning service is enabled. + *

+ * Collection is only disabled automatically when the license expires/becomes invalid. Collection can be disabled + * explicitly by the user, although that's generally a temporary solution to unrelated issues (e.g., initial setup when the monitoring + * cluster doesn't actually exist). + * + * @return {@code true} as long as the license is valid. Otherwise {@code false}. + */ public boolean collectionEnabled() { - // when checking multiple parts of the status, we should get a local reference to the status object since it is - // volatile and can change between check statements... + // note: status is volatile, so don't do multiple checks without a local ref Status status = this.status; - return status.getMode() != License.OperationMode.NONE && - status.getLicenseState() != LicenseState.DISABLED; + return status.getMode() != License.OperationMode.NONE && status.getLicenseState() != LicenseState.DISABLED; } + /** + * Determine if the index cleaning service is enabled. + *

+ * Index cleaning is only disabled when the license expires/becomes invalid. + * + * @return {@code true} as long as the license is valid. Otherwise {@code false}. + */ public boolean cleaningEnabled() { + // note: status is volatile, so don't do multiple checks without a local ref Status status = this.status; - return status.getMode() != License.OperationMode.NONE && - status.getLicenseState() != LicenseState.DISABLED; + return status.getMode() != License.OperationMode.NONE && status.getLicenseState() != LicenseState.DISABLED; } + /** + * Determine if the current license allows the retention of indices to be modified. + *

+ * Only users with the following license types can update the retention period: + *

    + *
  • {@link License.OperationMode#PLATINUM}
    • + *
  • {@link License.OperationMode#GOLD}
    • + *
+ * + * @return {@code true} if the user is allowed to modify the retention. Otherwise {@code false}. + */ public boolean allowUpdateRetention() { + // note: status is volatile, so don't do multiple checks without a local ref Status status = this.status; return status.getMode() == License.OperationMode.PLATINUM || status.getMode() == License.OperationMode.GOLD; }