[jackrabbit-filevault] branch master updated: JCRVLT-494 clarify javadoc of ExecutionPlanBuilder.execute(...) (#117)

[kw...@apache.org]

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

kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git


The following commit(s) were added to refs/heads/master by this push:
     new beb4a72  JCRVLT-494 clarify javadoc of ExecutionPlanBuilder.execute(...) (#117)
beb4a72 is described below

commit beb4a72adcf963c1da6ed9604c18b8b5b69ee57c
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Tue Jan 26 08:55:51 2021 +0100

    JCRVLT-494 clarify javadoc of ExecutionPlanBuilder.execute(...) (#117)
---
 .../vault/packaging/registry/ExecutionPlan.java    |  4 +++-
 .../packaging/registry/ExecutionPlanBuilder.java   | 22 ++++++++++++----------
 .../registry/impl/ExecutionPlanBuilderImpl.java    |  2 +-
 3 files changed, 16 insertions(+), 12 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..e3f9c24 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,26 +90,29 @@ 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);
 
     /**
-     * Triggers Validation and returns PackageIds of all packages to be installed
+     * Triggers validation and returns {@link PackageId}s of all packages to be installed
      * by this builder
      * @return Set of packages to be installed by this builder.
-     * @throws IOException if an I/O error occurrs.
+     * @throws IOException if an I/O error occurs.
      * @throws PackageException if the plan is not valid.
      */
     @NotNull
     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;
diff --git a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/impl/ExecutionPlanBuilderImpl.java b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/impl/ExecutionPlanBuilderImpl.java
index c3335bb..5fdca4e 100644
--- a/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/impl/ExecutionPlanBuilderImpl.java
+++ b/vault-core/src/main/java/org/apache/jackrabbit/vault/packaging/registry/impl/ExecutionPlanBuilderImpl.java
@@ -357,7 +357,7 @@ public class ExecutionPlanBuilderImpl implements ExecutionPlanBuilder {
     @Override
     public Set<PackageId> preview() throws IOException, PackageException {
         validate();
-        if (plan.getTasks().size() == 0) {
+        if (plan.getTasks().isEmpty()) {
             return Collections.emptySet();
         } else {
             Set<PackageId> packages = new HashSet<>();