docs: write javadoc

Author: bevzzz

src/main/java/io/weaviate/client6/v1/api/backup/Backup.java

@@ -13,14 +13,27 @@
 import io.weaviate.client6.v1.internal.ObjectBuilder;
 
 public record Backup(
+    /** Backup ID. */
     @SerializedName("id") String id,
+    /** Path to backup in the backend storage. */
     @SerializedName("path") String path,
+    /** Backup storage backend. */
     @SerializedName("backend") String backend,
+    /** Collections included in the backup. */
     @SerializedName("classes") List<String> includesCollections,
+    /** Backup creation / restoration status. */
     @SerializedName("status") BackupStatus status,
+    /** Backup creation / restoration error. */
     @SerializedName("error") String error,
+    /**
+     * This value indicates if a backup is being created or restored from.
+     * For operations like LIST this value is null.
+     */
+    // We set a bogus SerializedName to make sure we do not pick up this
+    // value from the JSON by accident, but always set it ourselves.
     @SerializedName("__operation__") Operation operation) {
 
+  /** Set operation associated with this backup. */
   public Backup withOperation(Operation operation) {
     return new Backup(id, path, backend, includesCollections, status, error, operation);
   }
@@ -29,19 +42,71 @@ public enum Operation {
     CREATE, RESTORE;
   }
 
+  /**
+   * Block until the backup has been created / restored successfully.
+   *
+   * @param client Weaviate client. Make sure {@link WeaviateClient#close} is not
+   *               called before this method returns.
+   * @throws IllegalStateException if {@link #operation} is not set (null).
+   * @throws TimeoutException      in case the wait times out without reaching
+   *                               BackupStatus.SUCCESS.
+   * @throws IOException           in case the request was not sent successfully
+   *                               due to a malformed request, a networking error
+   *                               or the server being unavailable.
+   */
   public Backup waitForCompletion(WeaviateClient client) throws IOException, TimeoutException {
     return waitForStatus(client, BackupStatus.SUCCESS);
   }
 
+  /**
+   * Block until the backup has been created / restored successfully.
+   *
+   * @param client Weaviate client. Make sure {@link WeaviateClient#close} is not
+   *               called before this method returns.
+   * @param fn     Lambda expression for optional parameters.
+   * @throws IllegalStateException if {@link #operation} is not set (null).
+   * @throws TimeoutException      in case the wait times out without reaching
+   *                               BackupStatus.SUCCESS.
+   * @throws IOException           in case the request was not sent successfully
+   *                               due to a malformed request, a networking error
+   *                               or the server being unavailable.
+   */
   public Backup waitForCompletion(WeaviateClient client, Function<WaitOptions.Builder, ObjectBuilder<WaitOptions>> fn)
       throws IOException, TimeoutException {
     return waitForStatus(client, BackupStatus.SUCCESS, fn);
   }
 
+  /**
+   * Block until the backup operation reaches a certain status.
+   *
+   * @param client Weaviate client. Make sure {@link WeaviateClient#close} is not
+   *               called before this method returns.
+   * @param status Target status.
+   * @throws IllegalStateException if {@link #operation} is not set (null).
+   * @throws TimeoutException      in case the wait times out without reaching
+   *                               the target status.
+   * @throws IOException           in case the request was not sent successfully
+   *                               due to a malformed request, a networking error
+   *                               or the server being unavailable.
+   */
   public Backup waitForStatus(WeaviateClient client, BackupStatus status) throws IOException, TimeoutException {
     return waitForStatus(client, status, ObjectBuilder.identity());
   }
 
+  /**
+   * Block until the backup operation reaches a certain status.
+   *
+   * @param client Weaviate client. Make sure {@link WeaviateClient#close} is not
+   *               called before this method returns.
+   * @param status Target status.
+   * @param fn     Lambda expression for optional parameters.
+   * @throws IllegalStateException if {@link #operation} is not set (null).
+   * @throws TimeoutException      in case the wait times out without reaching
+   *                               the target status.
+   * @throws IOException           in case the request was not sent successfully
+   *                               due to a malformed request, a networking error
+   *                               or the server being unavailable.
+   */
   public Backup waitForStatus(WeaviateClient client, BackupStatus status,
       Function<WaitOptions.Builder, ObjectBuilder<WaitOptions>> fn) throws IOException, TimeoutException {
     if (operation == null) {
@@ -55,10 +120,19 @@ public Backup waitForStatus(WeaviateClient client, BackupStatus status,
     return new Waiter(this, poll, options).waitForStatus(status);
   }
 
+  /**
+   * Cancel backup creation.
+   *
+   * <p>
+   * This method cannot be called cancel backup restore.
+   *
+   * @param client Weaviate client. Make sure {@link WeaviateClient#close} is not
+   *               called before this method returns.
+   * @throws IOException in case the request was not sent successfully
+   *                     due to a malformed request, a networking error
+   *                     or the server being unavailable.
+   */
   public void cancel(WeaviateClient client) throws IOException {
-    if (operation == Operation.RESTORE) {
-      throw new IllegalStateException("backup restore cannot be canceled");
-    }
     client.backup.cancel(id(), backend());
   }
 }

src/main/java/io/weaviate/client6/v1/api/backup/BackupStatus.java

@@ -3,14 +3,22 @@
 import com.google.gson.annotations.SerializedName;
 
 public enum BackupStatus {
+  /** Backup creation / restoration has begun. */
   @SerializedName("STARTED")
   STARTED,
+  /** Backup in progress, data is being transferred. */
   @SerializedName("TRANSFERRING")
   TRANSFERRING,
+  /** Backup creation / restoration completed successfully. */
   @SerializedName("SUCCESS")
   SUCCESS,
+  /** Backup creation / restoration failed. */
   @SerializedName("FAILED")
   FAILED,
+  /**
+   * Backup creation canceled.
+   * This status is never returned for backup restorations.
+   */
   @SerializedName("CANCELED")
   CANCELED;
 }

src/main/java/io/weaviate/client6/v1/api/backup/CompressionLevel.java

@@ -3,10 +3,13 @@
 import com.google.gson.annotations.SerializedName;
 
 public enum CompressionLevel {
+  /** Use default compression algorithm (gzip). */
   @SerializedName("DefaultCompression")
   DEFAULT,
+  /** Use compression algorithm that prioritizes speed. */
   @SerializedName("BestSpeed")
   BEST_SPEED,
+  /** Use compression algorithm that prioritizes compression quality. */
   @SerializedName("BestCompression")
   BEST_COMPRESSION;
 }

src/main/java/io/weaviate/client6/v1/api/backup/CreateBackupRequest.java

@@ -72,44 +72,64 @@ public Builder(String backupId) {
         this.backupId = backupId;
       }
 
+      /** Collection that should be included in the backup. */
       public Builder includeCollections(String... includeCollections) {
         return includeCollections(Arrays.asList(includeCollections));
       }
 
+      /** Collection that should be included in the backup. */
       public Builder includeCollections(List<String> includeCollections) {
         this.includeCollections.addAll(includeCollections);
         return this;
       }
 
+      /** Collection that should be excluded from the backup. */
       public Builder excludeCollections(String... excludeCollections) {
         return excludeCollections(Arrays.asList(excludeCollections));
       }
 
+      /** Collection that should be excluded from the backup. */
       public Builder excludeCollections(List<String> excludeCollections) {
         this.excludeCollections.addAll(excludeCollections);
         return this;
       }
 
+      /**
+       * Set the desired CPU core utilization.
+       *
+       * @param cpuPercentage Percent value of the target CPU utilization (1% to 80%).
+       */
       public Builder cpuPercentage(int cpuPercentage) {
         this.cpuPercentage = cpuPercentage;
         return this;
       }
 
+      /**
+       * Set the desired chunk size. Defaults to 128MB.
+       *
+       * @param chunkSize Chunk size in MB (2MB to 512 MB).
+       */
       public Builder chunkSize(int chunkSize) {
         this.chunkSize = chunkSize;
         return this;
       }
 
+      /** Adjust the parameters of the selected compression algorithm. */
       public Builder compressionLevel(CompressionLevel compressionLevel) {
         this.compressionLevel = compressionLevel;
         return this;
       }
 
+      /**
+       * Set the bucket where backups are stored.
+       * Applicable for cloud storage backends.
+       */
       public Builder bucket(String bucket) {
         this.bucket = bucket;
         return this;
       }
 
+      /** Override default backup location. */
       public Builder path(String path) {
         this.path = path;
         return this;

src/main/java/io/weaviate/client6/v1/api/backup/RbacRestoreOption.java

@@ -2,9 +2,12 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/** Controls which RBAC objects (users, roles) get restored. */
 public enum RbacRestoreOption {
+  /** Do not restore any objects. */
   @SerializedName("noRestore")
   NONE,
+  /** Restore all objects. */
   @SerializedName("all")
   ALL;
 }

src/main/java/io/weaviate/client6/v1/api/backup/RestoreBackupRequest.java

@@ -68,49 +68,69 @@ public static class Builder implements ObjectBuilder<BackupRestore> {
       private final List<String> includeCollections = new ArrayList<>();
       private final List<String> excludeCollections = new ArrayList<>();
 
+      /** Collection that should be restored. */
       public Builder includeCollections(String... includeCollections) {
         return includeCollections(Arrays.asList(includeCollections));
       }
 
+      /** Collection that should be restored. */
       public Builder includeCollections(List<String> includeCollections) {
         this.includeCollections.addAll(includeCollections);
         return this;
       }
 
+      /** Collection that should be not be restored. */
       public Builder excludeCollections(String... excludeCollections) {
         return excludeCollections(Arrays.asList(excludeCollections));
       }
 
+      /** Collection that should be not be restored. */
       public Builder excludeCollections(List<String> excludeCollections) {
         this.excludeCollections.addAll(excludeCollections);
         return this;
       }
 
+      /**
+       * Set the desired CPU core utilization.
+       *
+       * @param cpuPercentage Percent value of the target CPU utilization (1% to 80%).
+       */
       public Builder cpuPercentage(int cpuPercentage) {
         this.cpuPercentage = cpuPercentage;
         return this;
       }
 
+      /**
+       * Set the bucket where backups are stored.
+       * Applicable for cloud storage backends.
+       */
       public Builder bucket(String bucket) {
         this.bucket = bucket;
         return this;
       }
 
+      /** Override default backup location. */
       public Builder path(String path) {
         this.path = path;
         return this;
       }
 
+      /**
+       * Allow restored collection aliases to overwrite existing ones
+       * in case of conflict.
+       */
       public Builder overwriteAlias(boolean overwriteAlias) {
         this.overwriteAlias = overwriteAlias;
         return this;
       }
 
+      /** Control which RBAC users should be restored. */
       public Builder restoreUsers(RbacRestoreOption restoreUsers) {
         this.restoreUsers = restoreUsers;
         return this;
       }
 
+      /** Control which RBAC roles should be restored. */
       public Builder restoreRoles(RbacRestoreOption restoreRoles) {
         this.restoreRoles = restoreRoles;
         return this;

src/main/java/io/weaviate/client6/v1/api/backup/Waiter.java

@@ -53,7 +53,9 @@ Backup waitForStatus(BackupStatus wantStatus) throws IOException, TimeoutExcepti
       try {
         Thread.sleep(wait.interval());
       } catch (InterruptedException e) {
-        System.out.println("Interrupted");
+        // TODO: the interrupted state will be cleared on the next while() check
+        // and then we will simply return the latest state. An absence of an exception
+        // might be misleading here. What should we do?
         Thread.currentThread().interrupt();
       }
     }

src/main/java/io/weaviate/client6/v1/api/backup/WeaviateBackupClient.java

@@ -163,6 +163,9 @@ public List<Backup> list(String backend) throws IOException {
   /**
    * Cancel in-progress backup.
    *
+   * <p>
+   * This method cannot be called cancel backup restore.
+   *
    * @param backupId Backup ID.
    * @param backend  Backup storage backend.
    * @throws WeaviateApiException in case the server returned with an