[jackrabbit-filevault] 01/01: JCRVLT-494 clarify javadoc of ExecutionPlanBuilder.execute(...)

[kw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/JCRVLT-494-clarify-javadoc-of-executionplanbuilder
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git

commit 257648ef920ebc811d3e0aedd4f654585581ec4a
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Jan 25 19:28:35 2021 +0100

    JCRVLT-494 clarify javadoc of ExecutionPlanBuilder.execute(...)
---
 .../vault/packaging/registry/ExecutionPlan.java        |  4 +++-
 .../vault/packaging/registry/ExecutionPlanBuilder.java | 18 ++++++++++--------
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlan.java b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlan.java
index c1be72b..e0193f6 100644
--- a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlan.java
+++ b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlan.java
@@ -48,7 +48,9 @@ public interface ExecutionPlan {
     boolean isExecuted();
 
     /**
-     * checks if this plan has error
+     * Checks if execution of any of the tasks in the plan resulted in an error.
+     * Only returns a valid result in case {@link #isExecuted()} returns {@code true}.
+     * The concrete errors must be looked up from {@link #getTasks()}.
      * @return {@code true} if it has errors.
      */
     boolean hasErrors();
diff --git a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlanBuilder.java b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlanBuilder.java
index 47f10a4..bad5515 100644
--- a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlanBuilder.java
+++ b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/ExecutionPlanBuilder.java
@@ -19,7 +19,6 @@ package org.apache.jackrabbit.vault.packaging.registry;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
-import java.util.List;
 import java.util.Set;
 
 import javax.jcr.Session;
@@ -64,7 +63,7 @@ public interface ExecutionPlanBuilder {
 
     /**
      * Validates this plan.
-     * @return this.
+     * @return this
      * @throws IOException if an I/O error occurrs.
      * @throws PackageException if the plan is not valid.
      */
@@ -74,7 +73,7 @@ public interface ExecutionPlanBuilder {
     /**
      * Sets the JCR session for this execution plan.
      * @param session the session
-     * @return this.
+     * @return this
      */
     @NotNull
     ExecutionPlanBuilder with(@NotNull Session session);
@@ -82,7 +81,7 @@ public interface ExecutionPlanBuilder {
     /**
      * Sets the progress tracker listener for this plan.
      * @param listener the listener
-     * @return this.
+     * @return this
      */
     @NotNull
     ExecutionPlanBuilder with(@NotNull ProgressTrackerListener listener);
@@ -91,7 +90,7 @@ public interface ExecutionPlanBuilder {
     /**
      * Sets packages handled externally ahead of execution for prevalidation of plan
      * @param externalPackages Set of package ids handled by other builder
-     * @return this.
+     * @return this
      */
     @NotNull
     ExecutionPlanBuilder with(@NotNull Set<PackageId> externalPackages);
@@ -107,10 +106,13 @@ public interface ExecutionPlanBuilder {
     Set<PackageId> preview() throws IOException, PackageException;
     
     /**
-     * builds an executes the plan synchronously.
+     * Builds an executes the plan synchronously. Does not throw an exception in case one or 
+     * multiple task executions fail, therefore the caller should check {@link ExecutionPlan#hasErrors()} 
+     * after calling this method.
+     * 
      * @return the execution plan.
-     * @throws IOException if an I/O error occurrs.
-     * @throws PackageException if a package operation fails.
+     * @throws IOException if an I/O error occurs.
+     * @throws PackageException if the plan contains an unsupported task.
      */
     @NotNull
     ExecutionPlan execute() throws IOException, PackageException;